You can create customized events in the following scenarios:
Third-party integrations.
When you must use Windows Client or Linux PAM Client, or Mac OS X Client on both the domain joined and non-domain workstations and you must have a separate event to use the non-domain mode.
For integrations using SAML 2.0 and OAUTH 2.0.
To create more than one RADIUS Server event.
You can create the following types of customized events:
You can create a generic event for Windows Client, Mac OS X Client, and Linux PAM Client workstation when these clients are not joined or bound to a domain.Perform the following steps to create a generic event:
Click Events > New Event.
Specify a name for the event.
Set Is enabled to ON.
By default Generic is set in Event Type.
Select the Authenticator category. The Authenticator category option is displayed only if you have added categories in the Event categories
policy.
Select the chains that you want to assign to the current event.
(Conditional) In Risk Policy, select the policy that you want to assign to this event for assessing the risk associated with a login attempt.
(Conditional) Click Create New Policy to create a new risk policy for this event.
Clicking this option opens the Risk Settings page.
IMPORTANT:Risk Policy and Create New Policy options are available when you enable Risk Settings. For more information, see Section III, Configuring risk settings.
If you want to restrict access of some endpoints to the event, add all the endpoints that must have access to the Endpoints whitelist. The remaining endpoints are blacklisted automatically. If you leave the Endpoints whitelist blank, all the endpoints will be considered for authentication.
IMPORTANT:Endpoints whitelist supports only Windows Logon, Linux Logon, and Mac OS Logon events.
Set Geo-fencing to ON to enable geo-fencing. Move the permitted zones from Available to Used. For more information about configuring geo-fencing, see the Smartphone method.
IMPORTANT:You must enable the Geo fencing options policy to use the geo fencing functionality.
Set Logon with Expired Password with one of the following options based on your requirement:
Allow: Select this option to allow users to log in to the event with the expired LDAP password.
Ask to change: If the password has expired this option prompts users to change the password during logon. Change in the LDAP Password is supported only for the Active Directory repositories. However, the LDAP Password change in Advanced Authentication is not allowed when the LDAP Servers in the Repository settings are configured with port 389. The LDAP server rejects the new password.
Deny: Select this option to deny access to the event with the expired LDAP password. When the access is denied, the following message is displayed to users:
You must change your password to logon.
Set Bypass user lockout in repository to ON, users, who are locked in the repository, must select and authenticate with the chain that does not include the LDAP Password method. By default, Bypass user lockout in repository is set to OFF and locked users cannot authenticate by using any chain.
To use this functionality, it is required to have more than one chain without the LDAP Password method assigned to the event. This is to provide more options to users.
NOTE:All authentication chains irrespective of whether it includes the LDAP Password method or not are displayed to users who are locked in the repository.
Set Return groups on logon to ON if you want to retrieve the group details of users who authenticated to the event in the authentication response.
With Return groups on logon set to ON, if Groups is empty, all the groups that the users are associated with are returned in the response. However, to return the required groups, specify the preferred groups in Groups.
By default, Return groups on logon is set to OFF, the groups of users authenticated to the event are not returned in the response.
Select the Allow to logon to this event by shared authenticator option to allow users to login using shared authenticators. By default this option is disabled for the Authenticators Management, Helpdesk, Helpdesk User, AdminUI, Search Card, Token Management, and Report Logon events and enabled for all the other events.
NOTE:The Allow to logon to this event by shared authenticator option is displayed if you enable the Enable sharing of authenticators option in Authenticator management options policy.
A top administrator can enforce the configuration of events (except the RADIUS Server event) on secondary tenants. For more information, see Step 18.
Click Save.
NOTE:When you create a custom event, you must specify the custom event in the configuration file of the related endpoints. For more information, see the Advanced Authentication- Linux PAM client, Advanced Authentication - Mac OS X client, or Advanced Authentication - Windows client guides related to the specific endpoint.
You can create this event when the third-party application needs to read password of a user after authentication. For example, when Windows Client, Mac OS X Client, or Linux PAM Client workstation is joined or bound to a domain, the third-party application must read the password of the user.
The steps to create an OS Logon (domain) event are similar to the Generic event.
You can create this event for third-party integrations using OAuth 2.0 protocol.
To create an OAuth 2 / OpenID Connect event, perform the following steps:
Click Events > New Event.
Specify a name for the event.
Set Is enabled to ON.
Select OAuth2 / OpenID Connect in the Event type.
Select the Authenticator category. The Authenticator category option is displayed only if you have added categories in the Event categories
policy.
Select the chains that you want to assign to the current event.
The top chain (first chain) in the list of selected chains will be considered as a high-priority or high-security chain for that specific event.
Set the Enable chain selection with one of the following options on your requirements:
ON: Select this option to allow users to select their preferred authentication chain from all the chains that are available to them. By default, this option is set to ON.
OFF: Select this option to force users to use the chain that has the highest priority for authentication.
OPTIONAL: Select this option to display the high-priority chain with the ability to select the other chains from the list. If the user doesn’t wish to continue with the highest priority chain, they can click the Select Chain button to select their preferred chain from all the chains that are available to them.
(Conditional) In Risk Policy, select the policy that you want to assign to this event for assessing the risk associated with a login attempt.
(Conditional) Click Create New Policy to create a new risk policy for this event.
Clicking this option opens the Risk Settings page.
IMPORTANT:Risk Policy and Create New Policy options are available when you enable Risk Settings. For more information, see Section III, Configuring risk settings.
Specify the Redirect URIs. The Client ID and Client secret are generated automatically. The Client ID, Client secret, and Redirect URI are consumed by the consumer web application. After successful authentication, the redirect URI web page specified in the event is displayed.
NOTE:You cannot view the Client secret after saving the event. Later, you can reset the Client secret if you need.
NOTE:Resetting the Client secret will disrupt the service that relies on the event. To resume the service, you need to share the new client secret in the consumer web application and authenticate.
In Advanced Settings, perform the following actions:
NOTE:The options for Advanced Settings are hidden. To view all options click + icon.
Set the Enable Public Client option to ON to enable the public clients. By default, Enable Public Client option is set to OFF.
Set the Support Authorization Code to ON to enable the event to support the authorization code. By default, Support Authorization Code is set to OFF
Enabling the Use for Resource Owner Password Credentials setting will enable the event with the ability to use the Resource Owner Password Credentials grant in order to get access tokens as outlined by the OAuth 2.0 specifications. By default, Use for Resource Owner Password Credentials is set to OFF
Set the Support Client Credentials to ON to enable the event to support the client credentials. By default, Support Client Credentials is set to OFF.
Set the Support Implicit to ON to enable the event to support Implicit. By default, Support Implicit is set to OFF.
Set the Enable Token Revocation to ON to enable the vent to revoke the token. By default, Enable Token Revocation is set to OFF.
Set the Enable Session Token Revocation to ON to enable the event to revoke the session token. By default, Enable Session Token Revocation is set to OFF.
Set the Enable Token Sharing to ON to enable the event to share the token. By default, Enable Token Sharing is set to OFF.
Set the Enable OpenID Connect to ON to enable the Open ID connect. by default, Enable OpenID Connect is set to OFF.
Set the Enable all Claims in ID token to On to enable all the claims in ID token. By default, Enable all Claims in ID token is set to OFF.
Specify the Attribute Maps in Attribute Maps. One Map per line field.
The Attribute maps should be specified in the following format:
localName="<local name>" clientName="<client name>"
For example, localName="mail" clientName="user_email"
where,
localName: This value indicates the name of the attribute in the Web Authentication (local) namespace. This is how it is referred in Advanced Authentication. This value can be defined by users.
clientName: This value is the name by which the attribute value appears in JWTs.
Specify the timeout value in seconds till when the authorization code is valid in Authorization Code Timeout. By default, this value is set to 120 seconds. The request for an Access Token or an ID Token fails if the Authorization Code has expired and is no longer valid. The Authorization code becomes invalid if the client does not request for Token ID from the server within the specified time.
For security reasons, some OAuth2 / OpenID Connect code flow schemes require that first an Authorization Code be requested. The Authorization Code is then used to request an Access Token and ID Token.
IMPORTANT:Before configuring the timeout value in Authorization Code Timeout, Access Token Timeout, Refresh Token Timeout, Public Refresh Token Timeout, or Session Token Revocation Timeout in OAuth event, it is required to enable the relevant OAuth grant types under Advanced Settings. If the OAuth grant types are not enabled, default timeout values from Web Authentication policy are applicable.
Specify the time in seconds till when the access token is valid in Access Token Timeout. By default, this value is set to 120 seconds. Once the token expires, a new token is required before accessing the protected resources. The application might create a new token by using a Refresh Token and the client secret, or else the user is required to authenticate again.
Specify the time in seconds till when the token is valid in Refresh Token Timeout. Once the token expires it can no longer be used to create a new Access Token. By default, this value is set to 2592000 seconds.
Specify the timeout value for refreshing token for public clients in Public Refresh Token Timeout. This timeout is applicable when there are two client types, private and public. By default, this value is set to 3600 seconds.
Specify the timeout value till when the session-based refresh token revocation entries are retained in Session Token Revocation Timeout. Retained entries are removed when the session is properly logged out or after the refresh token expires. By default, this value is set to 172800 seconds.
NOTE:If you do not modify the values in Authorization Code Timeout, Access Token Timeout, Refresh Token Timeout, Public Refresh Token Timeout, and Session Token Revocation Timeout, these settings will contain default values in the Web Authentication Policy.
Set Logon with Expired Password with one of the following options based on your requirement:
Allow: Select this option to allow users to log in to the event with the expired LDAP password.
Ask to change: If the password has expired this option prompts users to change the password during logon. Change in the LDAP Password is supported only for the Active Directory repositories. However, the LDAP Password change in Advanced Authentication is not allowed when the LDAP Servers in the Repository settings are configured with port 389. The LDAP server rejects the new password.
Deny: Select this option to deny access to the event with the expired LDAP password. When the access is denied, the following message is displayed to users:
You must change your password to logon.
Set Bypass user lockout in repository to ON, users, who are locked in the repository, must select and authenticate with the chain that does not include the LDAP Password method. By default, Bypass user lockout in repository is set to OFF and locked users cannot authenticate by using any chain.
To use this functionality, it is required to have more than one chain without the LDAP Password method assigned to the event. This is to provide more options to users.
NOTE:All authentication chains irrespective of whether it includes the LDAP Password method or not are displayed to users who are locked in the repository.
Set Allow token re-use to ON, if you want to allow users to apply the OTP multiple times within the Allow re-sending after (seconds) duration for authentication. This option is applicable for Email OTP, SMS OTP, and Voice OTP methods.
By default, Allow token re-use is set to OFF and users are not allowed to apply the OTP more than once within the Allow re-sending after (seconds) duration that has been set for Email OTP, SMS OTP, and Voice OTP methods.
Select the Allow to logon to this event by shared authenticator option to allow users to login using shared authenticators. By default this option is disabled for the Authenticators Management, Helpdesk, Helpdesk User, AdminUI, Search Card, Token Management, and Report Logon events and enabled for all the other events.
NOTE:The Allow to logon to this event by shared authenticator option is displayed if you enable the Enable sharing of authenticators option in Authenticator management options policy.
A top administrator can enforce the configuration of events (except the RADIUS Server event) on secondary tenants. For more information, see Step 18.
Click Save.
For other customization and configurations related to the OAuth 2.0 or OpenID Connect event, see Downloading the identity provider SAML metadata.
NOTE:The logout URL must follow the below format:
https://<AAServer>/osp/a/TOP/auth/app/logout
where TOP is the name of the tenant.
However, it is possible to perform the logout from both Identity Provider and Service Provider using the following URL:
https://<AAServer>/osp/a/TOP/auth/app/logout?target=https://<Service Provider>/app/logout
For example: https://<AAServer>/osp/a/TOP/auth/app/logout?target=https://<NAMServer>/nidp/app/logout
After you have created an OAuth 2 / OpenID Connect event, perform the following steps to access the consumer web application:
Specify the Client ID, Client secret, and redirect URIs in the consumer web application.
Specify the appliance endpoint (authorization endpoint) in the web application.
For example, https://<Appliance IP>/osp/a/TOP/auth/oauth2/grant in the URL, TOP can be replaced by the tenant name.
Authenticate with the required authentication method(s) to access the consumer web application.
NOTE:Authorization is provided in the form of Authorization Code Grant or Implicit Grant or Resource Owner Password Credentials Grant.
OAuth events support the step-up authentication. It does not prompt users to authenticate with the same method that the user has succeeded for an event during the session. Let us understand the step-up authentication with an example, assume there are three OAuth events, EVT1, EVT2, and EVT3. Chains associated with each event are as follows:
EVT1 - LDAP Password + Security Questions
EVT2 - LDAP Password + SMS OTP
EVT3 - Security Questions + SMS OTP
Possible scenarios:
First the user logs in to EVT1 by furnishing LDAP password and valid secret questions. During the same session if the user tries to authenticate to EVT3 then a prompt to provide the SMS OTP is displayed. This happens because user has succeeded Security Questions method for EVT1.
User logs in to EVT3 first with the Security Questions and SMS OTP. Later, the user can authenticate to EVT2 with the LDAP Password method because SMS OTP is succeeded for the previous event.
NOTE:To bypass the username prompt during the authorization process, you can include the Ecom_User_ID parameter to retrieve and pass the username along with the redirect URL as follows:
https://<AA_IP>/osp/a/TOP/auth/oauth2/grant?response_type=code&client_id=<CLIENT_ID>&Ecom_User_ID=<USERNAME_ENTERED_IN_CLIENT_SITE>&redirect_uri=<REDIRECT_URL>
You can create this event for third-party integrations with SAML 2.0.
To create an SAML 2.0 event, perform the following steps:
Click Events > Add.
Specify a name for the event.
Set Is enabled to ON.
Select SAML 2 in the Event type.
Select the Authenticator category. The Authenticator category option is displayed only if you have added categories in the Event categories
policy.
Select the chains that you want to assign to the current event.
The top chain (first chain) in the list of selected chains will be considered as a high-priority or high-security chain for that specific event.
Set the Enable chain selection with one of the following options on your requirements:
ON: Select this option to allow users to select their preferred authentication chain from all the chains that are available to them. By default, this option is set to ON.
OFF: Select this option to force users to use the chain that has the highest priority for authentication.
OPTIONAL: Select this option to display the high-priority chain with the ability to select the other chains from the list. If the user doesn’t wish to continue with the highest priority chain, they can click the Select Chain button to select their preferred chain from all the chains that are available to them.
(Conditional) In Risk Policy, select the policy that you want to assign to this event for assessing the risk associated with a login attempt.
(Conditional) Click Create New Policy to create a new risk policy for this event.
Clicking this option opens the Risk Settings page.
IMPORTANT:Risk Policy and Create New Policy options are available when you enable Risk Settings. For more information, see Section III, Configuring risk settings.
In SAML 2.0 settings, perform the following actions:
NOTE:You must configure the Web Authentication policy for the SAML 2.0 event to work appropriately.
You can either insert your Service Provider's SAML 2.0 metadata in SP SAML 2.0 metadata or click Browse and select a Service Provider's SAML 2.0 metadata XML file to upload it.
Select the required option from NameID formatting options based on the SAML response requirement of service provider. The available options are:
Use default: To send NameID in SAML response without any customization.
Send E-Mail as NameID (suitable for G-Suite): To send email address in the NameID attribute and is required for integrating with the G-suite.
Send SAMAccount as NameID: To send SAMAccountName in the NameID attribute of SAML response from the Advanced Authentication server.
Send CN as NameID: To send UID of user in the NameID attribute of SAML response from the Advanced Authentication server. This is required, when eDirectory is used as the repository and service providers want nameid format as unspecified however need Common Name (UID by default) in the SAML response. This is required for integrating with Cyberark.
Send ImmutableId (User objectId) as NameID (required for Microsoft Office 365): To send User objectId in the NameID attribute as a SAML response from the Advanced Authentication server. This is required for integrating with Microsoft Office 365.
Create Custom NameID: To send custom details about user, such as Windows domain qualified name, unspecified and so on in the NameID attribute as a SAML response.
For sending custom details in NameID attribute, perform the following:
Select the preferred NameID Format to send in the SAML response. The available options are:
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName
urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos
Specify the attribute that you want as identifier in the SAML response.
Some attributes that do not need additional configurations are DN, CN, mail, mobile, sid, upn, netbiosname, sAMAccountName, and userImmutableID. Other attributes that are not in the list must be configured in the LDAP repository’s Custom attributes to fetch and Custom attributes to return.
To customize LDAP attributes in the SAML assertion, see Customizing LDAP attributes in the SAML assertion.
Specify the Attribute Maps in Attribute Maps. One Map per line.
The Attribute maps should be specified in the following format:
localName="<local name>" samlName="<Service Provider name>"
For example,
localName="mail" samlName="e-mail address"
Here, the service provider expects the "e-mail address" instead of "mail" from the Identity Provider (in this case, Advanced Authentication).
localName="userLastName" samlName="Surname"
localName="userFirstName" samlName="Given Name"
localName="mobile" samlName="Telephonenumber"
where,
localName: This value indicates the name of the attribute in the Web Authentication (local) namespace. This is how it is referred in Advanced Authentication. This value can be defined by users.
samlName: This value indicates the name of the attribute in SAML assertion.
Set Logon with Expired Password with one of the following options based on your requirement:
Allow: Select this option to allow users to log in to the event with the expired LDAP password.
Ask to change: If the password has expired this option prompts users to change the password during logon. Change in the LDAP Password is supported only for the Active Directory repositories. However, the LDAP Password change in Advanced Authentication is not allowed when the LDAP Servers in the Repository settings are configured with port 389. The LDAP server rejects the new password.
Deny: Select this option to deny access to the event with the expired LDAP password. When the access is denied, the following message is displayed to users:
You must change your password to logon.
Set Bypass user lockout in repository to ON, users, who are locked in the repository, must select and authenticate with the chain that does not include the LDAP Password method. By default, Bypass user lockout in repository is set to OFF and locked users cannot authenticate by using any chain.
To use this functionality, it is required to have more than one chain without the LDAP Password method assigned to the event. This is to provide more options to users.
NOTE:All authentication chains irrespective of whether it includes the LDAP Password method or not are displayed to users who are locked in the repository.
Set Allow token re-use to ON, if you want to allow users to apply the OTP multiple times within the Allow re-sending after (seconds) duration for authentication. This option is applicable for Email OTP, SMS OTP, and Voice OTP methods.
By default, Allow token re-use is set to OFF and users are not allowed to apply the OTP more than once within the Allow re-sending after (seconds) duration that has been set for Email OTP, SMS OTP, and Voice OTP methods.
Set Return groups on logon to ON to retrieve the group details of users who authenticated to the SAML 2.0 event in the authentication response.
With Return groups on logon set to ON, if Groups is empty, all the groups that the users are associated with are returned in the response. However, to return the required groups, specify the preferred groups in Groups.
By default, this option is set to OFF, the groups of users authenticated to the event are not returned in the response.
Select the Allow to logon to this event by shared authenticator option to allow users to login using shared authenticators. By default this option is disabled for the Authenticators Management, Helpdesk, Helpdesk User, AdminUI, Search Card, Token Management, and Report Logon events and enabled for all the other events.
NOTE:The Allow to logon to this event by shared authenticator option is displayed if you enable the Enable sharing of authenticators option in Authenticator management options policy.
A top administrator can enforce the configuration of events (except the RADIUS Server event) on secondary tenants. For more information, see Step 18.
Click Save.
SAML events support the step-up authentication. It does not prompt users to authenticate with the same method that is succeeded for an event during the session. Let us understand the step-up authentication with an example, assume there are three SAML events, SMEVT1, SMEVT2, and SMEVT3. Chains associated with each event are as follows:
SMEVT1 - LDAP Password + Security Questions
EVT2 - LDAP Password + SMS OTP
EVT3 - Security Questions + SMS OTP
Possible scenarios:
First the user logs in to SMEVT1 by furnishing LDAP password and valid secret questions. During the same session if the user tries to authenticate to SMEVT3 then a prompt to provide the SMS OTP is displayed. This happens because user has succeeded Security Questions method for SMEVT1.
User logs in to SMEVT3 first with the Security Questions and SMS OTP. Later, the user can authenticate to SMEVT2 with the LDAP Password method because SMS OTP is succeeded in the previous event.
When you want to add multiple RADIUS clients, you can add them to the predefined RADIUS Server event. But all the RADIUS clients will use the same authentication chain(s). If you want to configure specific authentication chain(s) for different RADIUS clients, then you must create a custom RADIUS event. To add a custom RADIUS event, perform the following steps:
Click Events > New Event.
Specify a name for the event.
Ensure that Is enabled is set to ON.
Select RADIUS from Event Type.
Select the chains that you want to assign to the event.
(Conditional) In Risk Policy, select the policy that you want to assign to this event for assessing the risk associated with a login attempt.
(Conditional) Click Create New Policy to create a new risk policy for this event.
Clicking this option opens the Risk Settings page.
IMPORTANT:Risk Policy and Create New Policy options are available when you enable Risk Settings. For more information, see Section III, Configuring risk settings.
Set Logon with Expired Password with one of the following options based on your requirement:
Allow: Select this option to allow users to log in to the event with the expired LDAP password.
Ask to change: If the password has expired this option prompts users to change the password during logon. Change in the LDAP Password is supported only for the Active Directory repositories. However, the LDAP Password change in Advanced Authentication is not allowed when the LDAP Servers in the Repository settings are configured with port 389. The LDAP server rejects the new password.
Deny: Select this option to deny access to the event with the expired LDAP password. When the access is denied, the following message is displayed to users:
You must change your password to logon.
Set Bypass user lockout in repository to ON, users, who are locked in the repository, must select and authenticate with the chain that does not include the LDAP Password method. By default, Bypass user lockout in repository is set to OFF and locked users cannot authenticate by using any chain.
To use this functionality, it is required to have more than one chain without the LDAP Password method assigned to the event. This is to provide more options to users.
NOTE:All authentication chains irrespective of whether it includes the LDAP Password method or not are displayed to users who are locked in the repository.
Set Return groups on logon to ON if you want to retrieve the group details of users who authenticated to the event in the authentication response.
With Return groups on logon set to ON, if Groups is empty, all the groups that the users are associated with are returned in the response. However, to return the required groups, specify the preferred groups in Groups.
The RADIUS protocol according to RFC has a 4KB limit of response size. The authentication response might exceed the set limit, if a user is a member of several groups. Therefore, it is recommended to use Groups to limit the groups' in the response.
By default, Return groups on logon is set to OFF, the groups of users authenticated to the event are not returned in the response.
Select the Allow to logon to this event by shared authenticator option to allow users to login using shared authenticators. By default this option is disabled for the Authenticators Management, Helpdesk, Helpdesk User, AdminUI, Search Card, Token Management, and Report Logon events and enabled for all the other events.
Configure Input rule
Configure Chain selection rule
Configure Result specification rule
You can configure the above RADIUS rules in RADIUS Options policy also. For more information about configuring the RADIUS rules in RADIUS Options Policy, see RADIUS Options.
The rules configured in RADIUS Options policy are called Global level rules and rules configured in RADIUS event are called Event level rules. All the RADIUS rules are executed in the following order.
Input rule configured in Global level rules.
Event Selection rule configured in Global level rules.
Input rule configured in Event level rules.
Chain selection rule configured in Event level rules.
Chain selection rule configured in Global level rules (if no chain in Event level rules).
Authenticate the user.
Result specification configured in Global level rules.
Result specification configured in Event level rules.
Click Save.