1Auth_radius Module
2
3Jan Janak
4
5 FhG Fokus
6 <jan@iptel.org>
7
8Juha Heinanen
9
10 <jh@tutpro.com>
11
12Stelios Sidiroglou-Douskos
13
14Bogdan-Andrei Iancu
15
16 Voice Sistem SRL
17 <bogdan@voice-system.ro>
18
19Edited by
20
21Jan Janak
22
23 <jan@iptel.org>
24
25Phil Lavin
26
27 <phil.lavin@synety.com>
28
29 Copyright © 2002, 2003 FhG FOKUS
30
31 Copyright © 2005 Voice Sistem SRL
32
33 Copyright © 2008-2010 Juha Heinanen
34 __________________________________________________________________
35
36 Table of Contents
37
38 1. Admin Guide
39
40 1. Overview
41 2. Additional Credentials
42 3. Dependencies
43
44 3.1. Modules
45 3.2. External Libraries or Applications
46
47 4. Parameters
48
49 4.1. radius_config (string)
50 4.2. service_type (integer)
51 4.3. auth_extra (string)
52 4.4. use_ruri_flag (integer)
53 4.5. radius_avps_mode (integer)
54 4.6. append_realm_to_username (integer)
55
56 5. Functions
57
58 5.1. radius_www_authorize(realm [, uri_user])
59 5.2. radius_proxy_authorize(realm [, uri_user])
60
61 List of Examples
62
63 1.1. “SIP-AVP” RADIUS AVP examples
64 1.2. radius_config parameter usage
65 1.3. service_type parameter usage
66 1.4. auth_extra parameter usage
67 1.5. use_ruri_flag parameter usage
68 1.6. radius_avps_mode parameter usage
69 1.7. append_realm_to_username parameter usage
70 1.8. radius_www_authorize usage
71 1.9. proxy_authorize usage
72
73Chapter 1. Admin Guide
74
75 Table of Contents
76
77 1. Overview
78 2. Additional Credentials
79 3. Dependencies
80
81 3.1. Modules
82 3.2. External Libraries or Applications
83
84 4. Parameters
85
86 4.1. radius_config (string)
87 4.2. service_type (integer)
88 4.3. auth_extra (string)
89 4.4. use_ruri_flag (integer)
90 4.5. radius_avps_mode (integer)
91 4.6. append_realm_to_username (integer)
92
93 5. Functions
94
95 5.1. radius_www_authorize(realm [, uri_user])
96 5.2. radius_proxy_authorize(realm [, uri_user])
97
981. Overview
99
100 This module contains functions that are used to perform authentication
101 using a Radius server. Basically the proxy will pass along the
102 credentials to the radius server which will in turn send a reply
103 containing result of the authentication. So basically the whole
104 authentication is done in the Radius server. Before sending the request
105 to the radius server we perform some sanity checks over the credentials
106 to make sure that only well formed credentials will get to the server.
107 We have implemented radius authentication according to
108 draft-sterman-aaa-sip-00. This module requires the radiusclient-ng
109 library version 0.5.0 or higher or freeradius-client which is available
110 from https://github.com/FreeRADIUS/freeradius-client/. You can also
111 install this library from distribution repositories.
112
1132. Additional Credentials
114
115 When performing authentication, the RADIUS server may include
116 additional credentials in the response. This scheme is very useful in
117 fetching additional user information from the RADIUS server without
118 making extra queries.
119
120 The additional credentials are embedded in the RADIUS reply as AVPs
121 “SIP-AVP”. The syntax of the value is:
122 * value = SIP_AVP_NAME SIP_AVP_VALUE
123 * SIP_AVP_NAME = STRING_NAME | '#'ID_NUMBER
124 * SIP_AVP_VALUE = ':'STRING_VALUE | '#'NUMBER_VALUE
125
126 All additional credentials will be stored as Kamailio AVPs
127 (SIP_AVP_NAME = SIP_AVP_VALUE).
128
129 The RPID value may be fetch via this mechanism.
130
131 Example 1.1. “SIP-AVP” RADIUS AVP examples
132....
133"email:joe@yahoo.com"
134 - STRING NAME AVP (email) with STRING VALUE (joe@yahoo.com)
135"#14:joe@yahoo.com"
136 - ID AVP (14) with STRING VALUE (joe@yahoo.com)
137"age#28"
138 - STRING NAME AVP (age) with INTEGER VALUE (28)
139"#14#28"
140 - ID AVP (14) with INTEGER VALUE (28)
141....
142
1433. Dependencies
144
145 3.1. Modules
146 3.2. External Libraries or Applications
147
1483.1. Modules
149
150 The module depends on the following modules (in the other words the
151 listed modules must be loaded before this module):
152 * auth -- Generic authentication functions
153
1543.2. External Libraries or Applications
155
156 The following libraries or applications must be installed before
157 compiling Kamailio with this module loaded:
158
159 One of these libraries. Notice that development of radiusclient-ng has
160 stopped, as the project merged with freeradius-client.
161 * freeradius-client available from
162 https://github.com/FreeRADIUS/freeradius-client/.
163 * radiusclient-ng 0.5.0 or higher -- library and development files.
164 See http://developer.berlios.de/projects/radiusclient-ng/.
165
1664. Parameters
167
168 4.1. radius_config (string)
169 4.2. service_type (integer)
170 4.3. auth_extra (string)
171 4.4. use_ruri_flag (integer)
172 4.5. radius_avps_mode (integer)
173 4.6. append_realm_to_username (integer)
174
1754.1. radius_config (string)
176
177 This is the location of the configuration file of radius client
178 libraries.
179
180 Default value is “/usr/local/etc/radiusclient-ng/radiusclient.conf”.
181
182 Example 1.2. radius_config parameter usage
183modparam("auth_radius", "radius_config", "/etc/radiusclient.conf")
184
1854.2. service_type (integer)
186
187 This is the value of the Service-Type radius attribute to be used. The
188 default should be fine for most people. See your radius client include
189 files for numbers to be put in this parameter if you need to change it.
190
191 Default value is “15”.
192
193 Example 1.3. service_type parameter usage
194modparam("auth_radius", "service_type", 15)
195
1964.3. auth_extra (string)
197
198 Semi-colon separated list of extra RADIUS attribute name=pseudo
199 variable pairs. When radius_www_authorize() or radius_proxy_authorize()
200 function is called, listed extra attributes are included in RADIUS
201 request with current values of corresponding pseudo variables.
202
203 There is no default value, i.e., by default no extra attributes are
204 included.
205
206 Example 1.4. auth_extra parameter usage
207modparam("auth_radius", "auth_extra", "Acct-Session-Id=$ci")
208
2094.4. use_ruri_flag (integer)
210
211 When this parameter is set to the value other than "-1" and the request
212 being authenticated has flag with matching number set via setflag()
213 function, use Request URI instead of uri parameter value from the
214 Authorization / Proxy-Authorization header field to perform RADIUS
215 authentication. This is intended to provide workaround for misbehaving
216 NAT / routers / ALGs that alter request in the transit, breaking
217 authentication. At the time of this writing, certain versions of
218 Linksys WRT54GL are known to do that.
219
220 Default value is “-1”.
221
222 Example 1.5. use_ruri_flag parameter usage
223modparam("auth_radius", "use_ruri_flag", 22)
224
2254.5. radius_avps_mode (integer)
226
227 If set to 1, all RADIUS AVPs returned by RADIUS server are stored in
228 Kamailio AVPs list. If set to 0, only the SIP_AVP type of RADIUS AVPs
229 are stored in Kamailio AVPs list.
230
231 Default value is 0.
232
233 Example 1.6. radius_avps_mode parameter usage
234modparam("auth_radius", "radius_avps_mode", 1)
235
2364.6. append_realm_to_username (integer)
237
238 If set to 1, the username passed to the RADIUS server will have the
239 digest realm appended to it, if no domain is provided in the digest
240 username.
241
242 Default value is 1.
243
244 Example 1.7. append_realm_to_username parameter usage
245modparam("auth_radius", "append_realm_to_username", 0)
246
2475. Functions
248
249 5.1. radius_www_authorize(realm [, uri_user])
250 5.2. radius_proxy_authorize(realm [, uri_user])
251
2525.1. radius_www_authorize(realm [, uri_user])
253
254 The function verifies credentials according to RFC2617. If the
255 credentials are verified successfully then the function will succeed
256 and mark the credentials as authorized (marked credentials can be later
257 used by some other functions).
258
259 If the function was unable to verify the credentials for some reason,
260 it fails and assigns a WWW-Authorize header containing a new challenge
261 to digest_challenge AVP (see modules/auth). The script should then
262 respond with 401 that includes this header, which will challenge the
263 user again.
264
265 Negative result codes may be interpreted as follows:
266 * -7 (internal error) - some internal error occurred (see syslog);
267 * -6 (nonce reused) - nonce is used more than once;
268 * -5 (no credentials) - credentials were not found in request;
269 * -4 (stale nonce) - stale nonce;
270 * -2 (authorization failed) - RADIUS responded with Access Reject
271 which may be, for example, due to user not found or wrong password;
272 * -1 (error) - some error occurred during authorization (see syslog);
273
274 This function will perform sanity checks over the received credentials
275 and then pass them along to RADIUS server which will verify the
276 credentials and return whether they are valid or not.
277
278 Meaning of the parameter is as follows:
279 * realm - Realm is a opaque string that the user agent should present
280 to the user so he can decide what username and password to use. In
281 case of REGISTER requests it is usually hostpart of To URI.
282 The string may contain pseudo variables.
283 * uri_user - Uri_user is an optional pseudo variable parameter whose
284 value, if present, will be given to Radius server as value of
285 SIP-URI-User check item. If uri_user pseudo variable parameter is
286 not present, the server will generate SIP-URI-User check item value
287 from user part of To/From URI.
288
289 This function can be used from REQUEST_ROUTE.
290
291 Example 1.8. radius_www_authorize usage
292...
293 if (!radius_www_authorize("$td")) {
294 switch ($rc) {
295 case -7:
296 send_reply("500", "Server Internal Error");
297 exit;
298 case -1:
299 send_reply("400", "Bad Request");
300 exit;
301 default:
302 };
303 if (defined($avp(digest_challenge)) &&
304 ($avp(digest_challenge) != "")) {
305 append_to_reply("$avp(digest_challenge)");
306 };
307 send_reply("401", "Unauthorized");
308 exit;
309 };
310...
311
3125.2. radius_proxy_authorize(realm [, uri_user])
313
314 The function verifies credentials according to RFC2617. If the
315 credentials are verified successfully then the function will succeed
316 and mark the credentials as authorized (marked credentials can be later
317 used by some other functions).
318
319 If the function was unable to verify the credentials for some reason,
320 it fails and assigns a Proxy-Authorize header containing a new
321 challenge to digest_challenge AVP. The script should then respond with
322 407 that includes this header, which will challenge the user again. For
323 negative result codes, see the above function.
324
325 This function will perform sanity checks over the received credentials
326 and then pass them along to RADIUS server which will verify the
327 credentials and return whether they are valid or not.
328
329 Meaning of the parameters is as follows:
330 * realm - Realm is a opaque string that the user agent should present
331 to the user so he can decide what username and password to use. In
332 case of non-REGISTER requests it is usually hostpart of From or
333 P-Preferred-Identity URI.
334 The string may contain pseudo variables.
335 * uri_user - Uri_user is an optional pseudo variable parameter whose
336 value, if present, will be given to Radius server as value of
337 SIP-URI-User check item. If uri_user pseudo variable parameter is
338 not present, the server will generate SIP-URI-User check item value
339 from user part of To/From URI.
340
341 This function can be used from REQUEST_ROUTE.
342
343 Example 1.9. proxy_authorize usage
344...
345 if (!radius_proxy_authorize("$pd", "$pU")) { # Realm and URI user are taken
346 switch ($rc) { # from P-Preferred-Identity
347 case -7: # header field
348 send_reply("500", "Server Internal Error");
349 exit;
350 case -1:
351 send_reply("400", "Bad Request");
352 exit;
353 default:
354 };
355 if (defined($avp(digest_challenge)) &&
356 ($avp(digest_challenge) != "")) {
357 append_to_reply("$avp(digest_challenge)");
358 };
359 send_reply("407", "Proxy Authentication Required");
360 exit;
361 };
362...
363