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 > Add.
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, if you want to allow users who are locked on repository to authenticate on the Advanced Authentication. By default, Bypass user lockout in repository is set to OFF and users who are locked on repository are not allowed to authenticate.
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.
A top administrator can enforce the configuration of events (except the RADIUS Server event) on secondary tenants. For more information, see Step 16.
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 event, perform the following steps:
Click Events > Add.
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.
(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.
In Advanced Settings, perform the following actions:
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.
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, if you want to allow users who are locked on repository to authenticate on the Advanced Authentication. By default, Bypass user lockout in repository is set to OFF and users who are locked on repository are not allowed to authenticate.
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.
A top administrator can enforce the configuration of events (except the RADIUS Server event) on secondary tenants. For more information, see Step 16.
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 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 end point (authorization end point) 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 nname.
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.
You can create this event for third-party integrations with SAML 2.0.
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.
(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.
Set the Send E-Mail as NameID (suitable for G-Suite) option to ON for integrating with the G-suite.
Set the Send SAMAccount as NameID option to ON to send SAMAccountName in the NameID attribute as a SAML response from the Advanced Authentication server.
This option must be enabled for the integration with CyberArk.
WARNING:You can set Send SAMAccount as NameID to ON only when the Send E-Mail as NameID (suitable for G-Suite) option is turned OFF.
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, if you want to allow users who are locked on repository to authenticate on the Advanced Authentication. By default, Bypass user lockout in repository is set to OFF and users who are locked on repository are not allowed to authenticate.
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.
A top administrator can enforce the configuration of events (except the RADIUS Server event) on secondary tenants. For more information, see Step 16.
Click Save.
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 > Add.
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, if you want to allow users who are locked on repository to authenticate on the Advanced Authentication. By default, Bypass user lockout in repository is set to OFF and users who are locked on repository are not allowed to authenticate.
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.