"clients":[]
The section is an array that contains details about each RADIUS client (NAS) that uses this RADIUS server.
Format
“clients”:[
{
“name”:”client1”,
“client-id”:”xxx”,
…
},
{
“name”:”client2”,
“client-id”:”xxx”,
…
},
…
]
Values
- "name": "client1"
- The client entry name value. This must be unique for all clients.
- "obf-secret": "fgb3A1/rOkxW0ogmlJ5Ex23PMrn9/vDrb93YFMwJ/Jg="
- The obfuscated secret value. Use as a preferable alternative to the "secret" option.
To generate this value, use the following command on Windows systems (located in C:\Program Files\IBM\IbmRadius\)
Use the following command on Linux systems.IbmRadius.exe -obf "the-client-secret"
/opt/ibm/ibm_radius/ibm_radius_64 --obf "the-client-secret"
- "voice-in-choice": false
- Adds the user's registered voice 2FA to the list of 2FA choices that are available to the user during authentication.
- "verify-message": "Do you approve this request from client1 ?"
- The message sent to the device that is used for 2FA approval to prompt the user. By default, the message sent is "Do you approve this request from {name} ?" where {name} is the "name":"client" value.
- "user-name-attr": "userName"
- Maps the username that is provided to RADIUS to an IBM Security Verify user, based on matching
an attribute that is contained on the IBM Security Verify user. For example, the RADIUS username
might be added to an IBM Security Verify user custom attribute called
otherUserName. That custom attribute
specifies
By default, the user attribute "userName" is used to locate the IBM Security Verify user that matches the RADIUS username."user-name-attr": "urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes.otherUserName"
- "ignore-isvalidated": false
-
When set to true, the RADIUS client can use 2FA methods that were not validated.
- "use-first-device": false
- When set to true, and the "auth-method" is "password-and-device", then the RADIUS client uses the first device that is listed for the user, even if the user has multiple devices for 2FA.
- "prompts": {}
- This configuration block customizes the 2FA choice prompt. Following entries can be inside this
configuration block:
- "choice-start":"{prompt}"
- The {prompt} string is output immediately before the list of 2FA choices.
- "choice-end":"{prompt}"
- The {prompt} string is output immediately after the list of 2FA choices. Any
%T
value within this{prompt}
is replaced with a number that represents the total number of choices. - "trans-email": "{prompt}"
- "trans-sms": "{prompt}"
- "totp": "{prompt}"
- "email": "{prompt}"
- "sms": "{prompt}"
- "voice": "{prompt}"
- "device-presence": "{prompt}"
- "device-biometric": "{prompt}"
- These arguments customize the prompt option for each 2FA type. The following substitutions can
be applied:
- %I The 2FA option index
- %N The value that is associated with the 2FA option name (for example, an email address)
- %T The total number of choices
prompts
configuration is
then the resulting 2FA choices might look like"prompts": { "choice-start": "Choose one of:\n", "email": "%I) %D\n", "sms": "%I) %D\n", "totp": "%I) TOTP\n", "choice-end": "Your choice (1->%T) " },
Choose one of: 1) us**@us.ibm.com 2) #######4567 3) TOTP Your choice (1->3)
- "secret":"passw0rd"
-
This value is required. This password is the shared secret between the IBM RADIUS server and the RADIUS client (NAS). The value is used to encrypt passwords and sign response packets between the two the server and the client.
Note: This secret can be set in an obfuscated form. Use theIbmRadius.exe -obf <password>
command to generate the obfuscated version and use the alternative setting:
.“obf-client-secret”:”KsjKZsKrbbgNaPe7+kYIcOyWzZdzYNtF4KlCyYoNEFA=”,
- "address":"192.168.0.129"
-
This value is required. This address is the IP address packets from the RADIUS client (NAS) come from, and where the responses are returned. The address is used to match the RADIUS client (NAS) to the appropriate secret value.
- "mask": "255.255.255.255"
- This value is optional and defaults to
"255.255.255.255"
. This setting is a netmask that, along with the"address"
configuration setting, is used to match an incoming client to a RADIUS client. A mask of"255.255.255.255"
means that an incoming client must have the exact IP address as the"address"
to be matched. A mask of"0.0.0.0"
means that any incoming client might be matched to this client. A mask of"255.255.0.0"
matches incoming clients whose first two IP address octets matched the first two IP address octets in"address"
. If there are multiple matching clients, the match that has the "more specific" mask is chosen. For example, for two clients:Client1 address: 192.168.0.0, mask: 255.255.255.0 Client2 address: 192.168.0.1, mask: 255.255.255.255
- If the incoming client address is
192.168.0.1
, then it would match Client2. - If the incoming client address is
192.168.0.2
, then it would match Client1. - If the incoming client address is
192.168.1.1
, then it would not match any client.
- If the incoming client address is
- "auth-method":"password-then-smsotp"
-
This value is optional and defaults to
“password”
. This method is the method of authentication that is required to authenticate users. Acceptable values are as follows:Table 1. Accepted values Value Description password Only a valid password is required. password-and-totp A password plus a TOTP value must be provided in a single value. You can configure whether the password or the TOTP value is first in the value. See the password-first
setting. To configure the character that is used to separate the two values, see thepassword-separator
setting.password-then-totp After a valid password is provided, a subsequent RADIUS challenge is sent that requests the TOTP value. password-then-smsotp After a valid password is provided, an SMS message is sent to the user's registered mobile device with an OTP value. Then a RADIUS challenge is sent that requests the SMSOTP value. password-then-emailotp After a valid password is provided, an email message is sent to the user with an OTP value. Then a RADIUS challenge is sent that requests the EmailOTP value. password-then-transsmsotp After a valid password is provided, an SMS message with an OTP value is sent to the phone number in the user's profile. A RADIUS challenge is sent that requests the OTP value. Unlike password-then-smsotp
, the user's phone number does not need to be enrolled for SMS OTP.password-then-transemailotp After a valid password is provided, an email message with an OTP value is sent to the email address in the user's profile. A RADIUS challenge is sent requesting the OTP value. Unlike password-then-emailotp
, the user's email address does not need to be enrolled for email OTP.password-then-choice-then-otp After a valid password is provided, a RADIUS challenge is sent that requests a choice of one of the user's OTP enrollments to use. After the choice is sent, a RADIUS challenge is sent that requests the OTP value for the choice.
Note:If the user is only enrolled in one OTP method, then the choice challenge step is skipped and the user is challenged directly for the OTP value.
If the user has no OTP enrollments, then reject-on-missing-auth-method comes into effect.
password-and-device After a valid password is provided, a RADIUS challenge is sent that requests a choice of one of the user's valid registered devices to use. After the choice of device is sent, a RADIUS challenge is sent that corresponds to the highest priority authentication mechanism that is supported by the device.
Note:- Authentication mechanisms, such as, Face, Fingerprint, or User Presence, are configurable by the administrator. If more than one mechanism is enabled, they are handled in an order of priority. The mechanism of greatest priority that is supported by the selected device is always chosen.
- For a registered device to be valid, it must support at least one valid authentication mechanism that is configured by the administrator.
- If only one registered device that supports the valid mechanisms exists, then the device choice step is skipped. The user is challenged with the priority mechanism for that device.
- If no registered devices that support the valid mechanisms exist, then a REJECT response is issued.
password-and-totp-or-device If a TOTP value is detected in the user-provided password, then the equivalent to the "password-and-totp" method is used. See password-and-totp for additional information.
If a TOTP value is not detected in the user-provided password, then the equivalent to the "password-and-device" method is used. See password-and-device for additional information.
Note: If the user's password begins or ends with six digits and a separator, it can be mistaken as an embedded TOTP value by the RADIUS server. For example, the password-first option is set to false and the password begins with the six digits and separator. Similarly, if set to true, and the password ends with a separator and six digits, the same condition occurs. In either situation, a device push cannot be used as a second factor for the RADIUS authentication. The RADIUS server interprets it as a TOTP value and tries to validate it. The validation fails and the authentication is rejected.totp The password is assumed to be only a TOTP (Time-based One-Time Password) value and only the TOTP 2FA is validated. No 1FA validation is done. - "password-first":false
- This value is optional and defaults to
false
. This setting controls whether the password is the first value in the password-separator-OTP concatenation that is submitted by the user for the password-and-totp authentication method.For example, the OTP value is
1234
, the user's password isPassword
, and the separator character is:
. If password-first is set to false, the user enters "1234:Password". If password-first is set to true, the user enters "Password:1234".The separator character can be configured with the password-separator setting.
- "password-separator":":"
- This value is optional and defaults to
:
. This setting configures the character that is used to separate the password and OTP values that are submitted by the user for the"password-and-totp"
auth-method. - "no-devices-in-choice":true
- This value is optional and defaults to
false
. If set totrue
, the user's IBM Verify devices are not presented as authentication method choices. - "reject-on-missing-auth-method":false
- This value is optional and defaults to
true
. If set tofalse
, and the user is not registered for second factor OTP, then the user is not prompted for it and is successfully authenticated. If set totrue
, and the user is not registered for second factor OTP, then the user is not authenticated. - "otp-prompt":"Enter OTP %C:"
- This value is optional and defaults to the English string
"Enter OTP %C:"
. This string is returned in the RADIUS challenge packet in the put into the RADIUS response packet variable"Reply-Message" (18)
. Many RADIUS clients (NAS) show this string when the input is requested from the user. Any%C
in the prompt is replaced by the OTP correlation, or the empty string for TOTP. Any%%
in the prompt is replaced by a single%
. - "user-name-append": "@VerifyRealm"
-
This value is optional and defaults to the empty string (""). The value is appended to the username that is provided to RADIUS logon. The value is used with the username to locate the user in the Cloud Directory. For example, if the RADIUS user was "scott", and "user-name-append": "@VerifyRealm", then the server locates "scott@VerifyRealm" in the user registry.
- "use-local-pwd-check":false
- This value is not available when running on Linux systems. It is
optional and defaults to
false
. If set totrue
, then passwords are authenticated with the server's local account database rather than cloud directory.Note: The usernames in the local account database and cloud directory must match. This option cannot be used withuse-external-ldap
. - "local-domain":"."
- This value is not available when running on Linux systems. It is used
only when
use-local-pwd-check
istrue
and affects the local windows password authentication check. When a user logs into RADIUS with a username that does not include a windows domain value, the RADIUS server validates the user against the windows account with domain set to "." When the domain is set to ".", the account password is validated against the local account database only. This option allows the "." to be overridden by specifying a windows domain name, or the empty string value "".Note:- A RADIUS username is considered to have a domain specified if the name contains a “\” or an “@” character. For example, mydomain\testuser or testuser@mydomain.com.
- The RADIUS server uses the Windows function
LogonUserA()
, for additional details about the domain value . See LogonUserA function (winbase.h) - Win32 apps.
- "use-external-ldap":false
- This value is optional and defaults to
false
. Users are authenticated against a configured LDAP pass-through identity source. When set totrue
the"identity-source"
value must be specified. This option cannot be used withuse-local-pwd-check
. - "identity-source":"869e5652-bbb1-4f9b-8e55-0ae53d3bc30b"
- This value is only required when
"use-external-ldap"
is set totrue
, it's otherwise optional. It specifies the identity source to be used to authenticate users. A collection of configured identity sources and their IDs can be retrieved from a GET request to https://<tenant>/verify/v1.0/authnmethods/password . - "choice-prompt":"Please select an authentication method from the list: \r\n"
- This value is optional. It defaults to the empty string:
""
. It allows a prefix to the choice line prompts to be configured. The choice line prompts and their prefixes are displayed when the user is required to choose an authentication method. - "choice-line-prompt":"Enter %I for %D \r\n"
- This value is optional. It allows each choice in the choice prompt to be customized. A choice
prompt is generated for each choice that is available to the user. The default is
"%I) %D\r\n"
, where%I
is replaced by the character that selects the choice, and%D
is the choice description. - "device-prompt":"A push notification has been sent to your device [%D]. "
- This value is optional. It allows the device/fingerprint/userpresence
prompt to be customized. The default is
"A push notification has been sent to your device [%D]. Please refresh your IBM Verify application if you did not receive it."
where%D
is replaced by the device description. - “device-choice-prompt”: "\r\nYou have multiple authenticators, please choose one by entering a number:"
- When the
“auth-method”
of“password-and-device”
is used, the user might have multiple devices that are registered. The RADIUS server prompts the user to choose which device to use. This choice is the prefix to the list of choices. It defaults to the English message:"\r\nYou have multiple authenticators, please choose one by entering a number:"
Note: Some RADIUS clients cannot handle the return and newline characters\r\n
If the client does not react correctly, retry without these characters in the format configuration. - “device-choice-line-prompt”:"\r\n%I/%T: %D"
- When prompted with a choice of devices, this parameter defines the format for each device
choice. The default value is the message:
"\r\n%I/%T: %D"
Where- %I - is replaced by the index of the device that the user needs to type in to select the device.
- %T - is replaced by the total number of device choices.
- %D - is replaced by the user device description.
Note: Some RADIUS clients cannot handle the return and newline characters\r\n
If the client does not react correctly, retry without these characters in the format configuration. - "transients-in-choice":false
- If the "transients-in-choice" configuration line is set to
"true"
, then the OTP authentication choices that are listed in"transient-choices"
based on the attributes from a user's cloud directory profile are included as OTP authentication choices, regardless of whether they're enrolled to receive SMS or email OTPs. - "transient-choices": ["emails", "phoneNumbers"]
- This value is optional. It defaults to
["emails","phoneNumbers"]
. This setting controls which transient OTP authentication choices are available to users. - "no-enrollments-in-choice":false
- This value is optional. It defaults to
false
. If the "no-enrollments-in-choice" configuration line is set to"true"
, then the user's enrolled OTP methods that include TOTP, email, and SMS are not included as authentication choices. - "poll-device":false
- This value is optional. It defaults to
false
. If set totrue
, then the server polls Verify for a verification's state instead of prompting the user and waiting for the response. - "poll-timeout":"60"
- This value is optional. It defaults to
60
. This attribute sets the maximum number of seconds that the server polls Verify after a device verification is created. It has no effect if"poll-device"
is set tofalse
. - "poll-delay":"2"
- This option determines the delay between each poll in seconds. The RADIUS server periodically
polls Verify to determine
whether to accept or reject the user's authentication on the device. The default setting is to poll
every 2 seconds. The value is ignored unless it is
>= 1 and < (“poll-timeout” / 2)
- "auth-method-order": [ "fingerprint", "userPresence" ]
- Defines the device PUSH methods and their order.
- "id-link-attr": "userName"
- When there are multiple identity sources defined in the tenant and they are using identity
linking, this configuration item defines the name of an attribute from the user located by
"user-name-attr" that identifies the username to validate the password against. Here are a few
examples of values:
- "urn:ietf:params:scim:schemas:extension:ibm:2.0:user:linkedAccounts.myOnPremIdSource"
- "emails.work"
- "urn:ietf:params:scim:schemas:extension:ibm:2.0:user:customAttributes.myCustomAttribute"
- "userName"
- "user-name-table": [ { "from": "{radius-user-name}", "to": "{isv-user-name}" }, ... ]
- Provides an array of mappings from the radius client supplied user name to the IBM Security Verify username.
- "use-mapping-user-id": false
- If "id-link-attr" is set and this option is set to true, the MFA settings of the user who is located by "user-name-attr" is used rather than the one used for authentication referenced by "id-link-attr".
- "require-msg-auth": false
- RADIUS servers version 1.0.11.0 and later always validate the Message-Authenticator attribute
signature if it is present. They always add a Message-Authenticator attribute signature to
responses. The Message-Authenticator attribute is specified in RFC 3579 section 3.2. If this option
is set to
true
, then the Message-Authenticator attribute must be present and valid in Access-Request packets for the RADIUS server to process the request. - "reject-bad-packet": false
- By default, the RADIUS server ignores incorrectly formed or incorrectly signed requests. When
this option is set to
true
, the RADIUS server responds by sending back an Access-Reject response.