Before you can use an OAuth2Client, OAuth2AccountLink, or OAuthAccountLink component in a skill, an administrator must register a confidential application (also referred to as an OAuth client) with OCI IAM or OAM.

To learn how to register an application with OCI IAM, see Adding a Confidential Application in the Oracle Cloud Infrastructure documentation. Information about registering an application with OAM can be found at Configuring OAuth Services in Administering Oracle Access Management.

When you register an application (client) with OCI IAM or OAM, 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 OCI IAM.

• 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/v2/tenants/<tenantId>/listeners/facebook/channels/<channelId>) to create the redirect URL, which must be in the format https://<domain>:<port>/connectors/v2/callback. For example https://example.com:443/connectors/v2/callback.

  If your instance is provisioned on Oracle Cloud Platform (as all version 19.4.1 instances are), use v1 instead of v2.

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 as described in Authentication Services.

To register an application with Microsoft identity platform, follow Microsoft's instructions at Quickstart: Register an application with the Microsoft identity platform.

Set the app type to Web.

You'll need to provide the URL that the platform uses to send back the authorization code. To figure out what to use for the URL, go to the Digital Assistant's 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/v2/tenants/<tenantId>/listeners/facebook/channels/<channelId>) to create the redirect URL, which must be in the format https://<domain>:<port>/connectors/v2/callback. For example https://example.com:443/connectors/v2/callback.

After you register the application, you need to create a client secret as described in the Microsoft topic Create a new application secret. You'll use this secret when you create an authentication service for the application.

To register an application with Google OAuth2, you create a project and enable the necessary APIs as shown in the Google topic Enable APIs for your project. If you plan to use the calendar components, ensure that you enable both the Google Calendar API and the CalDAV API.

Next, get the application's client ID and secret as described in the Google topic Create authorization credentials.

On the OAuth consent screen, specify the scopes that your app will need permission to access. See the Google topic Identify access scopes for more information.

Here's how to create an authentication service for grant type Authorization Code for OCI IAM, OAM, Microsoft Identity Platform, and Google Identity Platform. 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.

     • OCI IAM: Use https://<IAM-Service-Instance>.identity.oraclecloud.com/oauth2/v1/token.

     • OAM: Use http://<Managed-Server-Host>:<Managed-Server-Port>/oauth2/rest/token.

     • Microsoft Identity Platform: Use https://login.microsoftonline.com/<Azure-Active-Directory-TenantID>/oauth2/v2.0/token.

     • Google Identity Platform: Use https://www.googleapis.com/oauth2/v4/token.

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

     • OCI IAM: Use https://<IAM-Service-Instance>.identity.oraclecloud.com/oauth2/v1/authorize.

     • OAM: Use http://<host>:<port>/oauth2/rest/authz.

     • Microsoft Identity Platform: Use https://login.microsoftonline.com/<Azure-Active-Directory-TenantID>/oauth2/v2.0/authorize.

     • Google Identity Platform: Use https://accounts.google.com/o/oauth2/v2/auth.

   • 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 URLs for each platform are:

     • OCI IAM and OAM:

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

     • Microsoft Identity Platform:

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

     • Google Identity Platform:

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

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

     
     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 Reset OAuth 2.0 Tokens component to revoke the user's tokens for this service.

     • OCI IAM: Use https://<IAM-Service-Instance>.identity.oraclecloud.com/oauth2/v1/revoke.

     • OAM: Use https://<host>:<port>/ms_oauth/oauth2/endpoints/<OAuth-Service-Name>/tokens.

     • Microsoft Identity Platform: Not supported.

     • Google Identity Platform: Use https://oauth2.googleapis.com/revoke.

   • 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. With Microsoft identity platform, use the application ID and secret.

   • Scopes: A space-separated list of 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).

     • OCI IAM: Use the urn:opc:idm:__myscopes__ scope when you need to obtain an access token that contains all of the allowed scopes. Use the urn:opc:idm:role.<roll-name> scope (for example, urn:opc:idm:role.User%20Administrator) when you need to obtain an access token that contains the applicable scopes of a given role.

     • Microsoft Identity Platform: You must include openid email profile offline_access. If you plan to use calendar components, you must include https://graph.microsoft.com/Calendars.ReadWrite. For other permissions, use the format https://graph.microsoft.com/<permission>. Replace <permission> with a valid permission name from the Microsoft Graph permissions reference.

     • Google Identity Platform: You must include https://www.googleapis.com/auth/userinfo.email, which is used to obtain the user’s login ID. If you plan to use calendar components, you must include https://www.googleapis.com/auth/calendar. For other scopes, see OAuth 2.0 Scopes for Google APIs.

   • Subject Claim: The access-token profile claim to use to identify the user.

     • OCI IAM and OAM: This is typically the sub (subject) claim. However, if the sub claim contains an internal user ID, that's 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.

     • Microsoft Identity Platform: Use preferred_username.

     • Google Identity Platform: Use email.

   • 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 the illustration auth-service-ac.png
5. Click Create.

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.

   
   

   
   Description of the illustration auth-service-cc.png

   
   
5. Click Create.

You can configure skills for unified user identies with the following general steps:

1. Enable channel account linking in the Digital Assistant instance.
2. Add an authorization code service in your Digital Assistant instance.
3. In the skill's dialog flow, add a OAuth 2.0 Account Link component (for Visual dialog mode) or System.OAuth2AccountLink (for YAML mode).
4. In the component, configure the handling of user consent to storing the unified user identity data.

The unified user ID for a given user is set the first time the user accesses the digital assistant and authenticates with a Authorize using OAuth 2.0 component. That is, the initial authenticated identity becomes the "point of truth". All the channel account IDs for the same OAuth 2.0 authenticated user are associated with the unified user ID.

You can enable channel account linking to enable user identities to be recognized across multiple channels of a skill. For example, if a user starts a conversation in one channel and is waiting for a response, they could also receive a notification of that response in the other channel.

To enable channel linking:

1. Click to open the side menu and select Settings > Unified Identity Services.
2. Set the Channel Account Linking switch to On.

When you have activated channel account linking, you can configure how to handle user consent for each skill individually, using the requiresAssociationConsent property in the skill's OAuth 2.0 Account Link component. Here are the options:

• Yes: Presents the user with the following consent choices for association of the channel account data with a unified user ID:
  • Associate Account. Confirms the user has approved the linking of the current channel identity with the centralized unified user ID.
  • Never Link This Account. Indicates that this specific channel account should not be associated with the unified user ID. The user is not subsequently asked whether to link this account going forward. (though the user can later reverse that decision).
  • Not At This Time. Does not link the accounts for the current session, but does not prevent the user from being asked for approval in subsequent sessions. The consent prompt is temporarily suppressed after the user selects this option but may reappear when the user authenticates again more than 24 hours later.
• No . The user channel account is automatically linked to the unified user ID without the user being prompted for consent.
• Notify. The user channel account is automatically linked to the unified user ID, and the user is notified of that fact.

The default value of the property is Yes.

There is a set of a prompts and messages that are displayed in the conversation when a user is notified that their channel account identity information is being linked with a unified user identity or if they are given consent options. You can adjust the phrasing of these prompts in messages in the skill's resource bundle.

To access these particular prompts and messages in the resource bundle:

1. In the skill, click to open the Resources Bundle.
2. Select the Configuration tab.
3. In the Filter field, enter OAuthAccount2Link - consent to display the consent-related bundle entries.

The length of time that unified user identity data is stored is set at the instance level.

To configure the amount of time that such data is stored:

1. Click to open the side menu and select Settings > Unified Identity Services.
2. Set the Delete user's channel account data after the specified retention period switch to On.

   If it is not switched on, the user's channel account data will be retained indefinitely.

3. In the Retention period for channel account user data (in days), enter the number of days that you want the data to be stored.

   The minimum of 7 and the maximum is 1100.

   Note
   
   Jobs to purge the data run only once every 24 to 48 hours. So, depending on the time of the job, the data might be retained for up to 48 hours longer than the retention period that you designate.