Authentication policy parameters and credentials

When you add or modify an authentication policy, you specify parameters for the authentication mechanism and the attributes that you want in the credential. The credentials are evaluated as part of the access control decision.

Note: You cannot modify predefined authentication policies.

Parameters

Parameters pass policy configuration to the authentication mechanism. Parameters can be set for each workflow step. Parameter values can be a literal string that you provide in the parameter settings or they can be a context attribute reference. A context attribute consists of an attribute source, attribute namespace, and attribute ID. See Table 2 for a list of context attributes that you can use.

Table 1. Authentication mechanism runtime parameters
Authentication mechanism	Parameter name	Default value	Description
Username Password	`reauthenticate`	`true`	An authentication value that indicates whether the user must authenticate even if the user previously authenticated.
One-Time Password	`reauthenticate`	`true`	An authentication value that indicates whether the user must authenticate even if the user previously authenticated.
One-Time Password	`username`	No default value	The user name for OTP authentication. If the Pass check box is not checked, the OTP authentication mechanism retrieves the user name from the current authentication service credential.
HOTP One-Time Password	`reauthenticate`	`true`	An authentication value that indicates whether the user must authenticate even if the user previously authenticated.
HOTP One-Time Password	`username`	No default value	The user name in HOTP authentication. If the Pass check box is not checked, the HOTP authentication mechanism retrieves the user name from the current authentication service credential.
HOTP One-Time Password	`secretKey`	No default value	The secret key in HOTP authentication. If the Pass check box is not checked, the HOTP authentication mechanism retrieves the secret key of the user from its internal database. Users can configure their own secret key on the OTP Secret Keys management page. See Managing OTP secret keys
TOTP One-Time Password	`reauthenticate`	`true`	An authentication value that indicates whether the user must authenticate even if the user previously authenticated.
TOTP One-Time Password	`username`	No default value	The user name in TOTP authentication. If the Pass check box is not checked, TOTP authentication mechanism retrieves the user name from the current authentication service credential.
TOTP One-Time Password	`secretKey`	No default value	The secret key in TOTP authentication. If the Pass check box is not checked, the TOTP authentication mechanism retrieves the secret key of the user from its internal database. Users can configure their own secret key on the OTP Secret Keys management page. See Managing OTP secret keys
MAC Email One-time Password MAC One-time Password MAC SMS One-time password	`mobileNumber`	No default value	The phone number that delivers the one-time password value.
MAC Email One-time Password MAC One-time Password MAC SMS One-time password	`emailAddress`	No default value	The email address that delivers the one-time password value.
MAC Email One-time Password MAC One-time Password MAC SMS One-time password	`reauthenticate`	`true`	An authentication value that indicates whether the user must authenticate even if the user previously authenticated. Note: If you create a policy that uses both the SMS and Email delivery types with reauthenticate set to `false`, only the first delivery type is executed.
MAC Email One-time Password MAC One-time Password MAC SMS One-time password	`username`	No default value	The user name in MAC OTP authentication. If the Pass check box is not checked, MAC OTP authentication mechanism retrieves the user name from the current authentication service credential.
MAC Email One-time Password MAC One-time Password MAC SMS One-time password	`deliveryType`	`Email` `SMS`	The type of delivery mechanisms to use for delivering the one-time password value. When specified, the MAC One-Time password bypasses the OTPMethods mapping rule. Note: If you create a policy and have both the SMS and Email delivery types defined and `reauthenticate` is set to `false`, only the first delivery type is executed.
RSA One-Time Password	`reauthenticate`	`true`	The authentication value that indicates whether the user must authenticate even if the user previously authenticated.
RSA One-Time Password	`username`	No default value	The user name in RSA authentication. If the Pass check box is not checked, RSA authentication mechanism retrieves the user name from the current authentication service credential.
HTTP Redirect Authentication	`redirectURL`	No default value	The URL that contacts the custom authentication implementation. The HTTP Redirect authentication mechanism redirects the user's browser to the specified URL.
HTTP Redirect Authentication	`reauthenticate`	`true`	An authentication value that indicates whether the user must authenticate even if the user previously authenticated.
HTTP Redirect Authentication	`returnCredAttrName`	No default value	The credential attribute name that determines whether the HTTP Redirect authentication is successful.
HTTP Redirect Authentication	`returnCredAttrValue`	No default value	The credential attribute value that is compared against to determine whether the HTTP Redirect authentication is successful.
End-User License Agreement	`alwaysShowLicense`	`False`	The prompt for the license file. Set this option to `true` to always prompt the user to accept the license file.
End-User License Agreement	`licenseRenewalTerm`	`0`	The number of days until the user must accept the license again. When you specify a value that is less than `1`, there is not a renewal term. Note: This parameter compares the date that the user last accepted the license to the current date to determine the number of days since the user last accepted the license.
End-User License Agreement	`licenseFile`	No default value	The path to the license template file to display for the End-User License Agreement. For more information about how to update the license and add more license files, see Template files and Template file macros. Note: The path to the license file is relative to the locale in the template tree.
End-User License Agreement	`acceptIfLastAccepted Before`	No default value	The date that the license was last accepted. If the date the user last accepted the license is before this date, this parameter requires the user to accept the license again. Use the date format of `YYYY-MM-DD`.
End-User License Agreement	`username`	No default value	The user name of the user who is prompted to accept the license. If the Pass check box is not checked, the End-User License Agreement authentication mechanism retrieves the user name from the current authentication service credential.
End-User License Agreement	`reauthenticate`	`True`	An authentication value that indicates whether the user must authenticate even if the user previously authenticated. Note: The mechanism displays the license once per authenticated session under the following conditions: `alwaysShowLicense=true` `reauthenticate=false`
Knowledge Questions	`questionPresentationMode`	`Group`	Use one of the following values: Individual Presents each question one at a time. Group Presents all questions to the user in the same form.
Knowledge Questions	`questionPresentationOrder`	`Random`	Use one of the following values: Random Presents the questions in random order. Sequential Presents the questions in the order in which they are stored.
Knowledge Questions	`amountOfCorrectAnswersRequired`	`1`	The number of correct answers that is required for successful authentication. Specify any positive integer value that is not higher than the number of questions that is stored for each user.
Knowledge Questions	`username`	No default value	The user name of the user who is prompted to answer the knowledge questions. If you do not specify the user name, the user must log in before the Knowledge Questions authentication mechanism starts. The value must be a string.
Knowledge Questions	`reauthenticate`	`True`	An authentication value that indicates whether the user must authenticate with the Knowledge Questions authentication mechanism even if the user previously authenticated. The value is Boolean.
Knowledge Questions	`maxGracePeriodAuthenticationCount`	`0`	The maximum number of user authentications during the grace period. The mechanism does not require the user to configure knowledge questions during the grace period. The value is any positive integer.
FIDO Universal 2nd Factor	`username`	No default value	The user name for the FIDO Universal 2nd Factor authentication. If the Pass check box is not checked, the FIDO Universal 2nd Factor authentication mechanism retrieves the user name from the current authentication service credential.
FIDO Universal 2nd Factor	`appId`	`https:/ /webseal.com`	The protocol, hostname, and port that the user will use to attempt authentication.
FIDO Universal 2nd Factor	`mode`	`Authenticate`	The mode the FIDO Universal 2nd Factor authentication mechanism operates in. Use one of the following values: Authenticate Performs FIDO U2F Authentication with already registered tokens. Register Performs FIDO U2F Registration to add tokens.
FIDO Universal 2nd Factor	`attestationType`	`None`	The type of certificate attestation validation to perform. Use one of the following values: None No certificate attestation validation is performed. Keystore Certificate attestation validation is performed using the keystore configured in `attestationSource`. JWKS Certificate attestation validation is performed using the JSON Web Key Set configured in `attestationSource`.
FIDO Universal 2nd Factor	`attestationSource`	No default value	The keystore or key set to use for certificate attestation validation. Either the name of the keystore on the appliance, or the URL for a JSON Web Key Set.
FIDO Universal 2nd Factor	`attestationEnforcement`	`Required`	The level of enforcement of certificate attestation validation. Use one of the following values: Required Certificate attestation validation is required, and requests that fail validation will return a validation error. Optional Certificate attestation validation is performed, but requests that fail validation will not return an error.

Pass

A check in the Pass check box passes the parameter to the authenticator. The value for a passed parameter is either specified in the Value field or with the session or request information. If the Pass check box is not checked, the mechanism takes one of the following actions:

Uses the default value.
Uses the default method to get the default value.
Reports an error, depending on the mechanism and the parameter.

Credentials

When the user completes the authentication process, the Authentication Service creates a credential for that user. It uses the credential to log in the user. The user credential contains information such as the name of the user, the groups that the user belongs to, and attributes that further describe the user. You might want to modify the information that is included in the credential depending on the information required in your policies.

The Authentication Service automatically includes the following attributes:

username: The name of the user who is making the access request.
authenticationTypes: A list of URIs of all authentication policies that the user completed.
authenticationMechanismTypes: A list of URIs of all the authentication mechanisms that the user completed.
authenticationTransactionId: An identifier of the latest authentication transaction that the user completed.

Use Credentials to restrict the attributes in the credential by explicitly including each attribute. These attributes can be:

A literal string that you provide in the credential settings.
A context attribute reference

A context attribute consists of an attribute source, attribute namespace, and attribute ID. See Table 2 for a list of context attributes that you can use.

Credential attribute

The name of an attribute to use as an authentication credential.

ASCII letters
ASCII digits
Period (.)
Underscore (_)
Hyphen (-)

Note: Do not use any other special characters or non-ASCII Unicode characters.

Source

The source specifies the provider of the value for the credential:

Value
The value for the credential. Use any characters.
Session
A context attribute with a lifetime throughout the authentication process.
Request
A context attribute with a lifetime of the HTTP Request.

Value

The value of the credential attribute. The value that you specify depends on the source you select in the previous field.

If you select Value as a source, type a literal value in this field.
If you select Session or Request, type an attribute ID and namespace.

Context attributes

The following table lists of types of values you can retrieve from a session or a request.

Table 2. Context attributes
Type	Description	Attribute Source	Attribute Namespace	Attribute ID
Policy ID	The ID of the authentication policy in the current authentication process.	Session	urn:ibm:security:asf:policy	`policyID`
Transaction ID	The ID that triggers the current authentication process.	Session	urn:ibm:security:asf:transaction	`transactionID`
HTTP request parameters	The HTTP request parameters of the current HTTP request.	Request	Each attribute can contain multiple values. urn:ibm:security:asf:request:parameter Retrieves the first value. urn:ibm:security:asf:request:parameters Retrieves all the values.	The name of the parameter.
HTTP request headers	The HTTP request headers of the current HTTP request.	Request	Each attribute can contain multiple values. You can retrieve the first value or all of the values: urn:ibm:security:asf:request:header Retrieves the first value. urn:ibm:security:asf:request:headers Retrieves all the values.	The name of the header.
Request credential	The credential of the user in the current request.	Request	Each attribute can contain multiple values. You can retrieve the first value or all of the values: urn:ibm:security:asf:request:token:attribute Retrieves the first value. urn:ibm:security:asf:request:token:attributes Retrieves all the values.	The name of the Request credential attribute. Use `username` to retrieve the name of the user. Use `group` to retrieve the groups of the user.
Authentication Service credential	The credential of the user that the Authentication Service began constructing at the beginning of the authentication process.	Session	Each attribute can contain multiple values. You can retrieve the first value or all of the values: urn:ibm:security:asf:response:token:attribute Retrieves the first value. urn:ibm:security:asf:response:token:attributes Retrieves all the values.	The name of the Authentication Service credential attribute. Use `username` to retrieve the name of the user. User `group` to retrieve the groups of the user.
Context-based access attributes	The attributes that specify the context of the request that is evaluated as part of an access control decision.	Session	Attention: Before you can use context attributes, you must add the attributes to the `attributeCollection.authenticationContextAttributes` property in the Advanced Configuration settings. See Managing advanced configuration. Each attribute can contain multiple values. You can retrieve the first value or all of the values: urn:ibm:security:asf:cba:attribute Retrieves the first value. urn:ibm:security:asf:cba:attributes Retrieves all the values.	The name of the attribute.