18 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 the built-in OAuth2AccountLink and OAuthAccountLink security components to get the access information that the custom component needs.

OAuth2AccountLink, which works with Oracle Identity Cloud Service and Oracle Access Management, returns an access token. OAuthAccountLink returns an authorization code that a component can use to get an access token. Both of these components require that you register your Oracle Digital Assistant instance with the identity provider (IDP). For the OAuth2AccountLink component, your administrator must use Authentication Services to configure the IDP.

Identity Provider Registration

Your Oracle Digital Assistant instance must be registered with the IDP before you can use either of the security components in a skill. That is, you need to create in the IDP an OAuth client that represents your instance.

When you register an instance, you'll need to provide the allowed grant types. OAuth2AccountLink requires authorization code and refresh token grant types. For scopes or roles, you'll need to know the resources that your custom components need access to.

You'll also need to provide the URL that the IDP uses to send back the access token. 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 the OAuth2AccountLink component for the IDP then, after you create the 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.

Built-In Security Components

Oracle Digital Assistant provides the following security components:

  • System.OAuth2AccountLink: Obtains the access token for a custom component that calls an API 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 IDP on the Authentication Services page.

  • System.OAuth2ResetTokens: Revokes all the logged-in user's refresh and access tokens from a specified authentication service.

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

See the Security component reference.

Authentication Services

To use the System.OAuth2AccountLink security component, your administrator must first add a service for the IDP on the Authentication Services page, which you access by opening the side menu, and clicking Settings > Authentication Services. Authentication Services supports IDCS and OAM R2PS3 identity providers.

Ask your IDP for the following information that's required to add a service:

  • The token endpoint from which to request the access tokens.

  • The authorization endpoint to redirect to for authentication.

  • The client ID and secret.

  • The scopes that must be included when Digital Assistant requests an access token from the provider. For example, the scope that’s necessary to get the refresh token (typically offline_access), as well as all scopes that are required to authorize calls to the API.

  • Which 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 ADA. In these cases, specify a profile claim that can help Digital Assistant identify the user, such as email or name.

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.

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

Sometimes, such as with SMS and older smart phones, this URL is too long. You can use a URL shortener service (one that allows you to send variables) to shorten the authorization URL, and then set the optional short authorization code request URL to that value.

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

When you set the short authorization code request URL, the authorization code request URL is built as follows:

{Short Authorization Code Request URL}?state={state}

Tip:

If the IDP issues a refresh token, Digital Assistant stores it. The administrator can specify the retention period for refresh tokens.