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 custom component can use to get an access token. Both of these components require that you register a client with the identity provider (IDP). For the OAuth2AccountLink component, your administrator must use Authentication Services to configure the IDP.

Identity Provider Registration

The client that accesses the secured resources must be registered with the IDP before you can use either of the security components in a skill.

When you register a client, you'll need to provide this information:

  • Scopes or roles: Include the resources that your custom components need to access.
  • Allowed grant types: The Authorization Code grant type is required. For OAuth2AccountLink you can optionally include the refresh token grant type.

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 an access token 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 IDP on the Authentication Services page.

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

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 client 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 access the resources.

  • 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 Digital Assistant. 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 query parameters) 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.