Backend Authentication
If you are building a skill for a Microsoft Teams user channel, a skill that accesses a Google or Outlook calendar, or a skill that's invoked by an application-initiated conversation that uses an authenticated user ID to identify the mobile user, then you need to set up an authentication service to enable interaction between Digital Assistant and the identity provider. You also need to set up an authentication service if your skill uses a System.OAuth2Client
, System.OAuth2AccountLink
, or System.OAuth2ResetTokens
built-in component.
If you have a Digital Assistant instance that is paired with a subscription to a Fusion-based Oracle Cloud Applications service, such as Oracle Sales or Oracle Fusion Cloud Human Capital Management, then you don't have to do anything to configure backend authentication for the provided skills. This has been taken care of for you.
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 in a skill, register an application as described in Identity Provider Registration, and then ask your administrator to add a service for the client as described in Authentication Services. If you have a Digital Assistant instance that is paired with a subscription to a Fusion-based Oracle Cloud Applications service, such as Oracle Sales Cloud or Oracle Human Capital Management Cloud, then your IDCS instance already has a registered application and an authentication service has already been created.
-
System.OAuth2AccountLink
: Obtains an OAuth2 access token of grant type Authorization Code that a custom component can use to access resources that are secured by one of these identity providers:-
Oracle Identity Cloud Service
-
Oracle Access Manager (OAM)
-
Microsoft identity platform
-
Google Identity Platform
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.
Before you use this component in a skill, register an application as described in Identity Provider Registration, and then ask your administrator to add a service for the client as described in Authentication Services. If you have a Digital Assistant instance that is paired with a subscription to a Fusion-based Oracle Cloud Applications service, such as Oracle Sales Cloud or Oracle Human Capital Management Cloud, then your IDCS instance already has a registered application and an authentication service has already been created.
-
-
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 theSystem.OAuth2AccountLink
component.Note that you can't use this component with the Microsoft identity platform because it doesn't support the revoking of access tokens through REST calls, only through the command line interface.
-
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 OAuthAccountLink
component in a skill.
Register an Application with IDCS or OAM
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 IDCS or OAM.
If you have a Digital Assistant instance that is paired with a subscription to a Fusion-based Oracle Cloud Applications service, such as Oracle Sales Cloud or Oracle Human Capital Management Cloud, then your IDCS instance already has a registered application named IDCS_OAuthForFA.
To learn how to register an application with IDCS, see Add a Confidential Application in Administering Oracle Identity Cloud Service. 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 IDCS 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 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/v2/tenants/<tenantId>/listeners/facebook/channels/<channelId>
) to create the redirect URL, which must be in the formathttps://<domain>:<port>/connectors/v2/callback
. For examplehttps://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 ofv2
.
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.
Register an Application with Microsoft Identity Platform
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.
Register an Application with Google OAuth2 Authorization
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.
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.
If you have a Digital Assistant instance that is paired with a subscription to a Fusion-based Oracle Cloud Applications service, such as Oracle Sales Cloud or Oracle Human Capital Management Cloud, then an authentication service has already been created for the IDCS instance that's associated with your Digital Assistant instance.
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 for IDCS, OAM, Microsoft Identity Platform, and Google Identity Platform. This grant type authenticates on user name and password.
Tip:
For IDCS, when a user signs in through theSystem.OAuth2AccountLink
component, you can automatically store the IDCS user's profile information for the duration of a session. See Store IDCS User Profile for the Duration of the Session. This feature works only with instances of Oracle Digital Assistant that were provisioned on Oracle Cloud Infrastructure (sometimes referred to as the Generation 2 cloud infrastructure).