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.
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.
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 |
|
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:
|
Knowledge Questions | questionPresentationMode | Group | Use one of the following values:
|
Knowledge Questions | questionPresentationOrder | Random | Use one of the following values:
|
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:
|
FIDO Universal 2nd Factor | attestationType | None |
The type of certificate attestation validation to perform. Use one of the following values:
|
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:
|
FIDO2/WebAuthn Authentication | username | No default value | The user name for the FIDO2/WebAuthn authentication. If the Pass check box is not checked, the FIDO2/WebAuthn authentication mechanism retrieves the user name from the current authentication service credential. |
FIDO2/WebAuthn Authentication | relyingPartyConfigID | No default value | The relying party configuration ID to use with this mechanism, which identifies the Relying Party and the relying party specific configuration to use. If the Pass check box is not checked, the relyingPartyConfigId set on the mechanism will be used instead. |
FIDO2/WebAuthn Authentication | userVerification | No default value | Whether user verification is required, preferred, or discouraged. User verification is
authenticator dependent, but could be a PIN code, password entry, biometric or other method. If the Pass check box is not checked, the user verification default that is configured against the relying party ID is used instead. |
FIDO2/WebAuthn Authentication | abortOnError | No default value | Whether the policy should abort completely in an error case, or return a state ID such that a user can re-attempt authentication. If the Pass check box is not checked, the abortOnError set on the mechanism will be used instead. |
MMFA Authenticator | contextMessage | No default value | A message that is associated with a transaction, which can contain the detail of the transaction. This message may be displayed on the user's device when prompted for verification. |
MMFA Authenticator | pushMessage | No default value. If not defined, the contextMessage value is used. | Defines a message that is sent as a push notification when a transaction is awaiting verification. |
MMFA Authenticator | signingAttributeList | If not set, the value set for the property Signing Attributes in the MMFA Authenticator mechanism is used. See Configuring a Mobile Multi-Factor Authentication (MMFA) Authenticator Mechanism. | A comma separated list of context attributes that is added to a new JSON value attribute
that gets passed as a new pending attribute to the target mobile device. If supported by the device,
this JSON value is used to extract the various messages that is displayed to the end user. The MMFA
server also uses this JSON value during signature validation. Note: The value that is set here
overrides the Signing Attributes property set in the MMFA authenticator
mechanism.
|
MMFA Authenticator | username | No default value | The name of the user for which the challenge is generated. |
MMFA Authenticator | reauthenticate | True | An authentication value that indicates whether the user must authenticate even if the user is previously authenticated. |
MMFA Authenticator | policyURI | No default value | The policy ID of the authentication policy that handles the challenge response from the Authenticator Client. |
MMFA Authenticator | mode | Initiate | The mode the MMFA Authenticator authentication mechanism operate in. Use one of the following values:
|
FIDO2/WebAuthn Registration | username | No default value | The user name for the FIDO2/WebAuthn registration. If the Pass check box is not checked, the FIDO2/WebAuthn authentication mechanism retrieves the user name from the current authentication service credential. |
FIDO2/WebAuthn Registration | relyingPartyConfigID | No default value | The relying party configuration ID to use with this mechanism, which identifies the Relying Party and the relying party specific configuration to use. If the Pass check box is not checked, the relyingPartyConfigId set on the mechanism will be used instead. |
FIDO2/WebAuthn Registration | templatePage | No default value | The template page to be displayed to the end user as part of this mechanism. Allows for the page branding or user experience to be customized depending on the policy. If the Pass check box is not checked, the templatePage set on the mechanism will be used instead. |
FIDO2/WebAuthn Registration | optionsTemplate | No default value | In the attestation flow an options request is usually sent from the browser to the server, and the response is passed into the navigator.credentials.create call. This registration mechanism will populate the options request from the Options JSON template file, instead of a request payload. Allows for the user experience to be customized depending on the policy. If the Pass check box is not checked, the optionsTemplate set on the mechanism will be used instead. |
FIDO2/WebAuthn Registration | abortOnError | No default value | Whether the policy should abort completely in an error case, or return a state ID such that a user can re-attempt registration. If the Pass check box is not checked, the abortOnError set on the mechanism will be used instead. |
Pass
- 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.
- 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.
- A literal string that you provide in the credential settings.
- A context attribute reference
- 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
- 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.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 body | The raw body of the current HTTP request | Request | urn:ibm:security:asf:request | requestBody |
HTTP request method | The HTTP request method of the current HTTP request. | Request | urn:ibm:security:asf:request | method |
HTTP request parameters | The HTTP request parameters of the current HTTP request. | Request |
Each attribute can contain multiple 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:
|
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:
|
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:
|
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
Each attribute can contain multiple values. You can retrieve the first value or all of the values:
|
The name of the attribute. |
Request attribute names | A list of attribute names that are present in the request token. | Request | urn:ibm:security:asf:request | attributes |
Request header names | A list of header names in the incoming request. | Request | urn:ibm:security:asf:request | headers |
Request parameter names | A list of parameter names in the incoming request. | Request | urn:ibm:security:asf:request | parameters |
Request header names | A list of attribute names in the request token. | Session | urn:ibm:security:asf:response | attributes |
Target URL | The target URL that was included when the current authentication process was triggered. | Request | urn:ibm:security:asf:request | targetURL |