Oracle Cloud Infrastructure Documentation

Backend Authentication

You use custom components to access backend services, many of which require authentication. When you use a custom component that calls an API that supports OAuth, you can use one of the built-in security components to get the access information that the custom component needs. You can also use a security component for application-initiated conversations that use an authenticated user ID to identify the mobile user.

Built-In Security Components

Oracle Digital Assistant provides the following security components:

  • System.OAuth2Client: Obtains an OAuth2 access token of grant type Client Credentials that a custom component can use to access client resources that are secured by Oracle Identity Cloud Service or Oracle Access Manager (OAM). Before you use this component, ask your administrator to add a service for the client on the Authentication Services page.
  • System.OAuth2AccountLink: Obtains an OAuth2 access token of grant type Authentication Code that a custom component can use to access resources that are secured by Oracle Identity Cloud Service or Oracle Access Manager (OAM). Before you use this component, ask your administrator to add a service for the identity provider on the Authentication Services page.

    Another use for this component is to authenticate users for application-enabled conversations that identify mobile users by their user names, as described in Create a Channel for the External App.

  • System.OAuth2ResetTokens: Revokes all the logged-in user's refresh and access tokens from a specified authentication service. This is for dialog flows that use the System.OAuth2AccountLink component.

  • System.OAuthAccountLink: Obtains the authorization code for identity providers that support the OAuth2 protocol. The custom component must exchange this code for an access token. This component doesn't use an authentication service.

Identity Provider Registration

An administrator must register an application (also referred to as an OAuth client) with the identity provider (IDP) before you can use OAuth2Client, OAuth2AccountLink, or OAuth2Link in a skill.

When you register an application, you'll need to provide this information:

  • Allowed Grant Types: The application must use either the Authorization Code grant type or the Client Credentials grant type.

  • Scopes or Roles: Include the resources that your custom components need to access. If you include the refresh token grant type, then you also need to add the corresponding scope, which is offline_access for IDCS.

  • Redirect or Callback URL: You'll need to provide the URL that the IDP uses to send back the authorization code. Some identity providers refer to this as the redirect URL or the callback URI. To figure out what to use for the redirect URL, go to the Channels page and open any Facebook or Webhook channel (if you don't have any, create a fictitious one). You use the domain and port from the channel's Webhook URL (e.g., https://<domain>:<port>/connectors/v1/tenants/<tenantId>/listeners/facebook/channels/<channelId>) to create the redirect URL, which must be in the format https://<domain>:<port>/connectors/v1/callback. For example https://example.com:443/connectors/v1/callback.

If you are using OAuth2Client or OAuth2AccountLink for authenticating with the IDP, then, after you create the application (OAuth client), note the client credentials, IDP token, and authorization URL. You'll need this information when you create an authentication service for the IDP.

Authentication Services

To use the System.OAuth2Client and System.OAuth2AccountLink security components, your administrator must first add a service for the IDP on the Authentication Services page. You can create services for Authorization Code and Client Credential grant types. Authentication Services supports IDCS and OAM R2PS3 identity providers.

Before you create a service, you'll need to ask your IDP administrator to give you the information that you need to add a service.

Add an Authorization Code Service

Here's how to create an authentication service for grant type Authorization Code. This grant type authenticates on user name and password.

  1. Open the side menu and click Settings > Authentication Services.
  2. Click + Service.
  3. Select the Authorization Code grant type.
  4. Enter these values:
    • Identity Provider: Which type of identity provider (IDP) you are using.

    • Name: A name to identify the authentication service.

    • Token Endpoint URL: The IDP's URL for requesting access tokens.

    • Authorization Endpoint: The IDP's URL for the page that users authenticate with by entering their user name and password.

    • Short Authorization Code Request URL: (Optional) A shortened version of the authorization URL, which you can get from a URL shortener service (one that allows you to send query parameters) . You might need this because the generated authorization-code-request URL could be too long for SMS and older smart phones.

      By default, the authorization code request URL is built as follows:

      {Authorization Endpoint
            URL}?client_id={clientId}&response_type=code&scope={scope}&redirect_uri={redirectUri}&state={state}

      Here's an example of the URL displayed in a text message:

      Description of long-url.png follows
      Description of the illustration long-url.png

      For example, you can get a shortened version of this URL:

      {Authorization Endpoint
            URL}?client_id={clientId}&response_type=code&scope={scope}&redirect_uri={redirectUri}&state={state}

      Using the Short Authorization Code Request URL, Oracle Digital Assistant builds the authorization code request URL like this:

      {Short Authorization Code Request URL}?state={state}
    • Revoke Token Endpoint URL: (Optional) If you want to revoke all the refresh tokens and access tokens of the logged-in user from a dialog flow, then you need the IDP's revoke refresh token URL. If you provide this URL, then you can use the System.OAuth2ResetTokens component to revoke the user's tokens for this service.

    • Client ID and Client Secret: The client ID and secret for the IDP application (OAuth Client) that was registered as described in Identity Provider Registration.

    • Scopes: The scopes that must be included when Digital Assistant requests an access token from the provider. Include all the scopes that are required to access the resources. If refresh tokens are enabled, include the scope that’s necessary to get the refresh token (typically offline_access).

    • Subject Claim: The access-token profile claim to use to identify the user. Typically, this is the sub (subject) claim. However, some IDPs put an internal user ID in the sub claim, which is not helpful for Digital Assistant. In these cases, specify a profile claim that can help Digital Assistant identify the user, such as email or name.

    • Refresh Token Retention Period: The number of days to keep the refresh token in the Digital Assistant cache. If you leave this blank, it defaults to 7.
    Description of auth-service-ac.png follows
    Description of the illustration auth-service-ac.png
  5. Click Create.

Add a Client Credentials Service

Here's how to create an authentication service for grant type Credentials. This grant type authenticates on client ID and client secret.

  1. Open the side menu and click Settings > Authentication Services.
  2. Click + Service.
  3. Select the Client Credentials grant type.
  4. Enter these values:
    • Identity Provider: Which type of identity provider (IDP) you are using.

    • Name: A name to identify the authentication service.

    • Token Endpoint URL: The IDP's URL for requesting access tokens.

    • Client ID and Client Secret: The client ID and secret for the IDP application (OAuth Client) that was registered as described in Identity Provider Registration.

    • Scopes: The scopes that must be included when Digital Assistant requests an access token from the provider. Include all the scopes that are required to access the resources.



  5. Click Create.