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