11.2.3 Creating an OAuth 2.0 / OpenID Connect 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:

  1. Click Events > New Event.

  2. Specify a name for the event.

  3. Set Is enabled to ON.

  4. Select OAuth2 / OpenID Connect in the Event type.

  5. Select the Authenticator category. The Authenticator category option is displayed only if you have added categories in the Event Categories policy.

  6. Select the chains that you want to assign to the current event.

  7. (Conditional) In Risk Policy, select the policy that you want to assign to this event for assessing the risk associated with a login attempt.

  8. (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.

  9. 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.

  10. 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.

    • 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.

  11. 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.

  12. 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.

  13. 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.

  14. 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.

  15. A top administrator can enforce the configuration of events (except the RADIUS Server event) on secondary tenants. For more information, see Step 17.

  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:

  1. Specify the Client ID, Client secret, and redirect URIs in the consumer web application.

  2. 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.

  3. 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>