Use this component to obtain an OAuth2 access token of grant type Client Credentials. That is, you use it to get an access token that's based on the client's credentials, and not the user's name and password. You can use this component to get a token that enables access to client resources that are protected by Oracle Identity Cloud Service or Oracle Access Manager (OAM).

If you need to access resources on behalf of a user, see System.OAuth2AccountLink and System.OAuthAccountLink.

Before you can use this component in a skill, you must do the following tasks:

1. If it isn't already registered, register the client with the identity provider as described in Identity Provider Registration.
2. Add a client-credentials authentication service for the identity provider, as described in Authentication Services.

This component doesn't have any actions. To handle system problems that might occur, add a next transition that goes to a state that can handle such errors.

Here's an example of a state that uses this component:

  getAccessToken:
    component: "System.OAuth2Client"
    properties:
      authenticationService: "myAuthenticationService"
      accessTokenVariableName: "myAuthServiceToken"
    transitions:
      next: "next"
      error: "error" # handle auth service issues

Use this component to obtain an OAuth2 user access token (grant type Authorization Code) for resources that are secured by Oracle Identity Cloud Service (IDCS), Oracle Access Manager (OAM), Microsoft identity platform, or Google OAuth 2.0 authorization. This component completes all the steps for the 3-legged OAuth2 flow and returns the OAuth2 access token.

You can use the requiresAuthorization setting to indicate which states require authorization before they can be invoked. For the states that require authorization, if the user hasn't authorized yet, the System.OAuth2AccountLink state is invoked, and then the flow invokes the state that required authorization. You can learn how to use this feature in User Authorization in Group Chats (it works for all types of chats, not just group chats).

If you need to obtain an access token of grant type Client Credentials to access client resources, see System.OAuth2Client.

Before you can use this component in a skill, you must do the following tasks:

1. If it hasn't been registered already, then register the client with the identity provider as described in Identity Provider Registration.
2. Add an authentication service for the identity provider, as described in Authentication Services.

Some identity providers issue refresh tokens. When you use this component, Digital Assistant stores the refresh token for the retention period that's specified for the authentication service. The Digital Assistant backend can use the refresh token, if available, to get a new access token without the user having to sign in again.

Tip:

In skills with platform version 21.04 and later, the default values for the cancelLabel, linkLabel, and prompt properties are stored in the skill's resource bundle. To change a default, open the skill's Resources Bundle page, click , select the Configuration tab, and change the message for the OAuth2AccountLink - <property name> key. If you use the skill's resource bundle to change the default, then you don't need to include the property in the component unless you want to override the default.

You also can change the Other - oauthCancelPrompt and the Other - oauthSuccessPrompt messages in the configuration bundle.

${(system.message.channelConversation.channelType=='twilio')?then('true','false')}

${(system.message.channelConversation.channelType=='twilio')?then('false','true')}

This component can return the following actions:

When the dialog engine encounters the component, the skill bot prompts the user with two links: Get an Access Token and Cancel (you can use linkLabel and cancelLabel to change the link text).

If the user clicks the link to get an access token, it displays the identity provider’s login page or authentication dialog as specified by the authentication service. After successful login, it obtains the access token, sets the values for the variables identified by accessTokenVariableName and authenticatedUserVariableName, and then flows to the state that's named by the pass action (or to the next state if there isn't a pass action). If the user cancels, the postback action is set to fail. If the user enters text, it returns the textReceived action.

As mentioned earlier, you can set requiresAuthorization for a state to ensure that the user is authorized before invoking the state's component. If the user hasn't authorized yet, the dialog invokes the system.authorizeUser action in defaultTransitions. Here's an example:

main: true
name: RequiresAuthorizationExample
context:
  variables:
    iResult: "nlpresult"

defaultTransitions:
  actions:
    system.authorizeUser: "login"

states:
  intent:
    component: "System.Intent"
    properties:
      variable: "iResult"
    transitions:
      actions:
        reg.general.showPasscode: "showPasscode"
        reg.general.showPhoneNumber: "showPhoneNumber"
        unresolvedIntent: "handleUnresolved"        

  showPasscode:
    component: "System.Output"
    requiresAuthorization: true
    properties:
      text: "XYZABC123"
    transitions:
      return: "done"          
       
  showPhoneNumber:
    component: "System.Output"
    requiresAuthorization: false
    properties:
      text: "555-1212"
    transitions:
      return: "done"
       
  handleUnresolved:
    component: "System.Output"
    requiresAuthorization: false
    properties:
      text: "You can ask for my phone number or ask for the passcode."
    transitions:
      return: "done"
         
  login:
    component: "System.OAuth2AccountLink"
    properties:
      prompt: "${profile.firstName}, please login"
      authenticationService: "MyAuthenticationService"
      accessTokenVariableName: "user.accessToken"
      authenticatedUserVariableName: "user.authenticatedUserId"
    transitions:
      actions:
        pass : "${system.requestedState}"
        fail : "handleFailedLogin"
        textReceived: "intent"       

  handleFailedLogin:
    component: "System.Output"
    requiresAuthorization: false
    properties:
      text: "Sorry, you aren't authorized to do that"
    transitions:
      return: "done"     

Use this component to revoke all the logged-in user's refresh and user access tokens from the identity provider that the authentication service represents. It also removes the refresh tokens from the database. To use this component, you must provide the identity provider's revoke refresh token URL in the Authentication Service UI.

The skill must include a state that uses the OAuth2AccountLink component for the same authentication service, and it must be invoked before the state that uses the System.OAuth2ResetTokens component.

This component can return the following action:

Use this component to obtain the authorization code for services that are secured by the authorization code grant flow, such as LinkedIn, Twitter, Google, or Microsoft. The skill’s custom components can exchange the authorization code for an access token, which they then use to invoke the end service.

The component first directs the user to the identity provider’s login page. After a successful login, the component returns the authorization code in a variable, which you use to pass the authorization code to the custom component. The custom component API must exchange the authorization code, client ID, and client secret for an OAuth2 user access token.

You can use the requiresAuthorization setting to indicate which states require authorization before they can be invoked. For the states that require authorization, if the user hasn't authorized yet, the System.OAuthAccountLink state is invoked, and then the flow invokes the state that required authorization. You can learn how to use this feature in User Authorization in Group Chats (it works for all types of chats, not just group chats).

Tip:

In skills with platform version 21.04 and later, the default values for the cancelLabel, linkLabel, and prompt properties are stored in the skill's resource bundle. To change a default, open the skill's Resources Bundle page, click , select the Configuration tab, and change the message for the OAuthAccountLink - <property name> key. If you use the skill's resource bundle to change the default, then you don't need to include the property in the component unless you want to override the default.

You also can change the Other - oauthCancelPrompt and the Other - oauthSuccessPrompt messages in the configuration bundle.

${(system.message.channelConversation.channelType=='twilio')?then('true','false')}

${(system.message.channelConversation.channelType=='twilio')?then('false','true')}

This component can return the following actions:

This example shows the required properties that you need to define for the System.OAuthAccountLink component: prompt, which specifies the login message, variable, which tells the component where to store the authorization code, and authorizeURL which defines both the provider’s OAuth URL and the redirect URL that receives the authorization code.

login:
  component: "System.OAuthAccountLink"
  properties:
    prompt: "Please login now."
    linkLabel: "login"
    cancelLabel: "cancel"
    authorizeURL: "https://www.linkedin.com/oauth/v2/authorization?response_type=code&client_id=75k0vq4&scope=r_basicprofile&redirect_uri=https%3A%2F%2FmyBotsinstance%2Fconnectors%2Fv2%2Fcallback"
    variable: "authCode"
  transitions:
      next: getBankUserProfile
      actions:
        textReceived: handleAuthTextResponse
        fail: authCancelled

When the dialog engine encounters this component, the skill bot prompts the user with two links — Login and Cancel.

There are several ways to transition from this component:

• The user clicks the cancel button and the component transitions to the state that's named by the fail action.

• The user doesn't click any buttons but enters text instead. The component transitions to the state that's named by the textReceived action.

• The user clicks the login link and the channel renders the identity provider’s login page or its authentication dialog as a webview, as shown in the example below. After successful authorization, the component transitions to the state that's named by the pass action (or to the next state if there isn't a pass action), which would typically call a custom component that exchanges the authorization code for an access token.

If the test window doesn’t render the webview, cut and paste the link text into your browser.