-
Notifications
You must be signed in to change notification settings - Fork 5
/
pizauth.conf.5
231 lines (231 loc) · 6.83 KB
/
pizauth.conf.5
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
.Dd $Mdocdate: September 13 2022 $
.Dt PIZAUTH.CONF 5
.Os
.Sh NAME
.Nm pizauth.conf
.Nd pizauth configuration file
.Sh DESCRIPTION
.Nm
is the configuration file for
.Xr pizauth 1 .
.Pp
The top-level options are:
.Bl -tag -width Ds
.It Sy auth_notify_cmd = Qo Em shell-cmd Qc ;
specifies a shell command to be run via
.Ql $SHELL -c
when an account needs to be authenticated.
Two special environment variables are set:
.Em $PIZAUTH_ACCOUNT
is set to the account name;
.Em $PIZAUTH_URL
is set to the URL required to authorise the account.
Optional.
.It Sy auth_notify_interval = Em time ;
specifies the gap between reminders to the user of authentication requests.
Defaults to 15 minutes if not specified.
.It Sy error_notify_cmd = Qo Em shell-cmd Qc ;
specifies a shell command to be run via
.Ql $SHELL -c
when an error has occurred when authenticating an account.
Two special environment variables are set:
.Em $PIZAUTH_ACCOUNT
is set to the account name;
.Em $PIZAUTH_MSG
is set to the error message.
Defaults to logging via
.Xr syslog 3
if not specified.
.It Sy http_listen = Em none | Qo Em bind-name Qc ;
specifies the address for the
.Xr pizauth 1
HTTP server to listen on.
If
.Em none
is specified, the HTTP server is turned off entirely.
Note that at least one of the HTTP and HTTPS servers must be turned on.
Defaults to
.Qq 127.0.0.1:0 .
.It Sy https_listen = Em none | Qo Em bind-name Qc ;
specifies the address for the
.Xr pizauth 1
HTTPS server to listen on.
If
.Em none
is specified, the HTTPS server is turned off entirely.
Note that at least one of the HTTP and HTTPS servers must be turned on.
Defaults to
.Qq 127.0.0.1:0 .
.It Sy transient_error_if_cmd = Qo Em shell-cmd Qc ;
specifies a shell command to be run when pizauth repeatedly encounters
errors when trying to refresh a token.
One special environment variable is set:
.Em $PIZAUTH_ACCOUNT
is set to the account name.
If
.Em shell-cmd
returns a zero exit code, the transient errors are ignored.
If
.Em shell-cmd
returns a non-zero exit code, or exceeds a 3 minute timeout, pizauth treats
the errors as permanent: the access token is invalidated (forcing the user
to later reauthenicate).
Defaults to ignoring non-fatal errors if not specified.
.It Sy refresh_at_least = Em time ;
specifies the maximum period of time before an access token will be forcibly
refreshed.
Defaults to 90 minutes if not specified.
.It Sy refresh_before_expiry = Em time ;
specifies how far in advance an access token should be refreshed before it
expires.
Defaults to 90 seconds if not specified.
.It Sy refresh_retry = Em time ;
specifies the gap between retrying refreshing after transitory errors
(e.g. due to network problems).
Defaults to 40 seconds if not specified.
.It Sy token_event_cmd = Qo Em shell-cmd Qc ;
specifies a shell command to be run via
.Ql $SHELL -c
when an account's access token changes state.
Two special environment variables are set:
.Em $PIZAUTH_ACCOUNT
is set to the account name;
.Em $PIZAUTH_EVENT
is set to the event type.
The event types are:
.Em token_invalidated
if a previously valid access token is invalidated;
.Em token_new
if a new access token is obtained;
.Em token_refreshed
if an access token is refreshed;
.Em token_revoked
if the user has requested that any token, or ongoing authentication for,
an account should be removed or cancelled.
Token events are queued and processed one-by-one in the order they were
received: at most one instance of
.Sy token_event_cmd
will be executed at any point in time; and there is no guarantee
that an event reflects the current state of an account's access token,
since further events may be stored in the queue.
Note that
.Sy token_event_cmd
is subject to a 10 second timeout.
Optional.
.El
.Pp
An
.Sq account
block supports the following options:
.Bl -tag -width Ds
.It Sy auth_uri = Qo Em URI Qc ;
where
.Em URI
is a URI specifying the OAuth2 server's authentication URI.
Mandatory.
.It Sy auth_uri_fields = { Qo Em Key 1 Qc : Qo Em Val 1 Qc , ..., Qo Em Key n Qc : Qo Val n Qc } ;
specifies zero or more query fields to be passed to
.Sy auth_uri
after any fields that
.Nm
may have added itself.
Keys (and their values) are added to
.Sy auth_uri
in the order they appear in
.Sy auth_uri_fields ,
each separated by
.Qq & .
The same key may be specified multiple times.
Optional.
.It Sy client_id = Qo Em ID Qc ;
specifies the OAuth2 client ID (i.e. the identifier of the client software).
Mandatory.
.It Sy client_secret = Qo Em Secret Qc ;
specifies the OAuth2 client secret (similar to the
.Em client_id ) .
Optional.
.It Sy login_hint = Qo Em Hint Qc ;
is used by the authentication server to help the user understand which account
they are authenticating.
Typically a username or email address.
Optional.
.Em Deprecated :
use
.Ql auth_uri_fields = { Qo login_hint Qc : Qo Hint Qc }
instead.
.It Sy redirect_uri = Qo Em URI Qc ;
where
.Em URI
is a URI specifying the OAuth2 server's redirection URI.
Defaults to
.Qq http://localhost/
if not specified.
.It Sy refresh_at_least = Em time ;
Overrides the global
.Sy refresh_at_least
option for this account.
Follows the same format as the global option.
.It Sy refresh_before_expiry = Em time ;
Overrides the global
.Sy refresh_before_expiry
option for this account.
Follows the same format as the global option.
.It Sy refresh_retry = Em time ;
Overrides the global
.Sy refresh_retry
option for this account.
Follows the same format as the global option.
.It Sy scopes = [ Qo Em Scope 1 Qc , ..., Qo Em Scope n Qc ] ;
specifies zero or more OAuth2 scopes (roughly speaking,
.Qq permissions )
that access tokens will give you permission to utilise.
Optional.
.It Sy token_uri = Qo Em URI Qc ;
is a URI specifying the OAuth2 server's token URI.
Mandatory.
.El
.Pp
Times can be specified as
.Em int [smhd]
where the suffixes mean (in order): seconds, minutes, hours, days.
For example,
.Em 90s
means 90 seconds and
.Em 5m
means 5 minutes.
.Sh EXAMPLES
An example
.Nm
file for accessing IMAP and SMTP services in Office365
is as follows:
.Bd -literal -offset 4n
account "officesmtp" {
auth_uri = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize";
token_uri = "https://login.microsoftonline.com/common/oauth2/v2.0/token";
client_id = "..."; // Fill in with your Client ID
client_secret = "..."; // Fill in with your Client secret
scopes = [
"https://outlook.office365.com/IMAP.AccessAsUser.All",
"https://outlook.office365.com/SMTP.Send",
"offline_access"
];
// You don't have to specify login_hint, but it does make
// authentication a little easier.
auth_uri_fields = { "login_hint": "[email protected]" };
}
.Ed
.Pp
Note that Office365 requires the non-standard
.Qq offline_access
scope to be specified in order for
.Xr pizauth 1
to be able to operate successfully.
.Sh SEE ALSO
.Xr pizauth 1
.Pp
.Lk https://tratt.net/laurie/src/pizauth/
.Sh AUTHORS
.An -nosplit
.Xr pizauth 1
was written by
.An Laurence Tratt Lk https://tratt.net/laurie/