Section 3.67. <AuthBy REST>

3.67. <AuthBy REST>

<AuthBy REST> allows you to handle authentication and accounting requests by using HTTP REST API backends.

The response must decode to a Perl hash data structure which is automatically done for JSON object format responses. If the response is, for example, a JSON array, you can update the decoded response to a Perl hash with MapResponseHook

See goodies/rest.cfg for an example configuration.

This clause supports all the common HTTP client configuration parameters. For more information about the HTTP client configuration parameters, see Section 3.12. HTTP client configuration.

Radiator's special character formatting is supported for the URL parameter as follows:

%0 is the current username
information of the current request is available

Here is an example where the URL must contain username@example.org in an encoded format:

<AuthBy REST>
     # Format result for user 'mik/em' is
     # https://api.example.org/mi%2Fkem%40example.org/auth
     URL https://api.example.org/user/%{URIEncodeUTF8:%0}%%40example.org/auth
     FormatURL

The current username in %0 is encoded with URIEncodeUTF8 formatter. %% is simply formatted to a single %. For more about Radiator special formatters, see Section 3.3. Special formatters.

<AuthBy REST> understands also the same parameters as <AuthBy xxxxxx>. For more information, see Section 3.32. <AuthBy xxxxxx>.

3.67.1. RestAuthRequestDef

This parameter allows you to define parameters for authentication requests sent via HTTP REST API.

You can specify any number of RestAuthRequestDef parameters, one for each parameter sent to the server. The general format is:

RestAuthRequestDef authtparam,attributename[,type[,formatted]]

authparam is the REST parameter name
attributename defines the value for authparam. The value may be fetched from the current request, be a value that is subject to special formatting, or a literal value
type consists of the word “literal” or the word “request”. If type is empty or “request”, the value is fetched from the current request. If type is "literal", it is added to the HTTP request as it is.
formatted indicates that the value specified with attributename is to be subject to special character processing before being used.

Tip

The type and formatted fields are optional. If they are not specified, type defaults to "request" and formatted defaults to not enabled.

Example

The following example adds 3 parameters in the REST API request Radiator sends. Parameter "request_type" is set to literal value "authentication". Parameter "server_name" is set to the hostname of server that Radiator runs on. Value for parameter "username" is copied from the "User-Name" attribute of the currently processed request.

RestAuthRequestDef request_type, authentication, literal
RestAuthRequestDef server_name, %h, literal, formatted
RestAuthRequestDef username, User-Name

3.67.2. RestAcctRequestDef

This parameter allows you to define parameters for accounting requests sent via HTTP REST API.

You can specify any number of RestAcctRequestDef parameters, one for each parameter sent to the server. The general format is:

RestAcctRequestDef acctparam,attributename[,type[,formatted]]

acctparam is the REST parameter name
attributename defines the value for acctparam. The value may be fetched from the current request, be a value that is subject to special formatting, or a literal value
type consists of the word “literal” or the word “request”. If type is empty or “request”, the value is fetched from the current request. If type is "literal", it is added to the HTTP request as it is.
formatted indicates that the value specified with attributename is to be subject to special character processing before being used.

Tip

The type and formatted fields are optional. If they are not specified, type defaults to "request" and formatted defaults to not enabled.

Example

The following example adds 3 parameters in the REST API request Radiator sends. Parameter "request_type" is set to literal value "accounting". Parameter "server_name" is set to the hostname of server that Radiator runs on. Value for parameter "username" is copied from the "User-Name" attribute of the currently processed request. Values from "acct_sess_id" and "acc_status_id" are respectively copied from "Acct-Session-Id" and "Acct-Status-Type" attributes.

RestAcctRequestDef request_type, accounting, literal
RestAcctRequestDef server_name, %h, literal, formatted
RestAcctRequestDef username, User-Name
RestAcctRequestDef acct_sess_id, Acct-Session-Id
RestAcctRequestDef acct_status_type, Acct-Status-Type

3.67.3. NoReplyReject

This is an optional flag parameter. When this parameter is set, it forces <AuthBy REST> to return with result REJECT to trigger an Access-Reject when a REST request times out. This parameter is not set by default.

When NoReplyReject is enabled, the reject reason is set to 'REST request timeout'.

3.67.4. ServerChecksPassword

Normally, Radiator fetches the user's credentials, such as password hash, from the server using the PasswordAttr or EncryptedPasswordAttr parameter and checks the password internally. This optional parameter causes the server to check the password instead. This is useful with servers that implement proprietary encryption algorithms in their passwords, or do not provide access to password attribute.

When ServerChecksPassword is specified, Radiator sends the plaintext password with "password" REST API parameter to the server and the password checking is performed by the server only. This is done in addition to any parameters added by RestAuthRequestDef.

Here is an example of using ServerChecksPassword:

# Send plaintext password to server to check
ServerChecksPassword

CAUTION

ServerChecksPassword is compatible with PAP, EAP-TTLS/PAP, and other authentication methods that provide a plain text password. ServerChecksPassword does not work with CHAP, MSCHAP, and most EAP methods since these do not provide a password Radiator can use with an LDAP bind operation.

3.67.5. RestAuthReplyDef

This parameter allows you to specify how to use REST API reply parameters as check, reply or other items during authentication.

You can specify any number of RestAuthReplytDef parameters, one for each parameter sent to the server. The general format is:

RestAuthReplyDef replyparam,attributename[,type[,formatted]]

replyparam is the REST parameter name
attributename is the name of the attribute that is used as the check, reply or other item. The special attributename ‘GENERIC’ indicates that the replyparam value is a list of comma separated attribute=value pairs.
type indicates whether replyparam is a check, reply or other item. Possible values are “check” or “reply” for check and reply items. If type is “request” the value is saved in the current request, from where it can be later collected with a special formatting macro like: %{attributename}.
formatted indicates that the value specified with attributename is to be subject to special character processing before being used.

Tip

The type and formatted fields are optional. If they are not specified, type defaults to empty and formatted defaults to not enabled.

Example

The following example uses 3 parameters from REST API requests Radiator receives. Parameters "nas_id" and "client_mac" must match request attributes "NAS-Identifier" and "Calling-Station-Id", respectively. Parameter "sess_timeout" sets the value for reply attribute "Session-Timeout".

# How to handle reply for REST authentication request
RestAuthReplyDef nas_id,NAS-Identifier,check
RestAuthReplyDef client_mac,Calling-Station-Id,check
RestAuthReplyDef sess_timeout,Session-Timeout,reply

Tip

Password check is defined with configuration parameters PasswordAttr, EncryptedPasswordAttr and ServerChecksPassword.

3.67.6. EncryptedPasswordAttr

Name of the HTTP reply parameter that contains an encrypted password for the user. If you specify EncryptedPasswordAttr, it will be used instead of PasswordAttr, and PasswordAttr is ignored. You must specify either PasswordAttr or EncryptedPasswordAttr or ServerChecksPassword.

# HTTP server sends password hash with pw-hash parameter
EncryptedPassword pw-hash

3.67.7. PasswordAttr

Name of the HTTP reply parameter that has the correct plaintext password for the user. If you specify EncryptedPasswordAttr, it will be used instead of PasswordAttr, and PasswordAttr is ignored. You must specify either PasswordAttr or EncryptedPasswordAttr or ServerChecksPassword.

# HTTP server sends plaintext password with pw parameter
PasswordAttr pw

3.67.8. HandleAcctStatusTypes

This optional parameter specifies a list of Acct-Status-Type attribute values that will be processed in Accounting requests. The value is a comma-separated list of valid Acct-Status-Type attribute values including, Start, Stop, Alive, Modem-Start, Modem-Stop, Cancel, Accounting-On and Accounting-Off. See your dictionary for a full list.

If HandleAcctStatusTypes is specified and an Accounting request has an Acct-Status-Type not mentioned in HandleAcctStatusTypes, then the request will be ACCEPTed but not otherwise processed by the enclosing clause. The default is to handle all Acct-Status-Type values.

# Only process Start and Stop requests, ACCEPT and acknowledge everything else
HandleAcctStatusTypes Start,Stop