Configuring OAuth v2 Authorization

Prerequisites

You must first register an account with the web application as you will need to enroll DRUID as a trusted application inside the Authorization Server of the web application, from where you will receive Client Id and Client Secret for your enrollment. You will use these values to configure OAuth v2 in DRUID.
Make sure that you provide scopes to the DRUID application if the target application allows grating privileges (scopes).

To define authorization for your assistant, using OAuth v2, open the assistant for which you want to configure an Authorization profile and follow the steps described below.

Step 1. Create OAuth 2 app and enroll DRUID as a trusted application inside the Authorization Server of the web application

You must first register an account with the target application and enroll DRUID as a trusted application inside the Authorization Server of the target application, from where you will receive the sign in credentials (Client ID and Client Secret) for that application to configure the settings for the OAuth v2 Authorization Mechanism in DRUID.

Creating an OAuth app and enrolling DRUID as a trusted application inside the Authorization Server of the web application should be done simultaneously as you need information from both to set them up:

In Druid, on the main menu, click Apps and at the top-right corner of the page, click Create App and select Oauth2.

The New App page appears. Set the parameters described in the table below.

Parameter	Description
Code	Unique name to identify the App. You will reference in each method you call from this App. This field is mandatory.
Type	Automatically set to REST. This is a non-editable field.
Icon	By default, the REST icon will be shown in the apps list. In a future release, the OAuth icon will be available and you will be able to select it from the field.
Bot	Automatically set to the current bot. This is a non-editable filed.
Execution Time	The maximum number of seconds a request is allowed to execute. By default, the timeout for all connector integrations is 60 seconds. This setting will apply to all connector tasks that use this app.
Encryption Type	Enables data encryption on the connector using the AES CGM encryption algorithm and allows bot authors to encrypt specific data before sending it to external REST apps, by using the Encrypt Data integration task as first task in the desired connector action. When you select AES CGM encryption algorithm (the only one currently available), two new options are available: Encryption Key – click the Generate button to generate the key, which will be used by the Encrypt Data task to encrypt the data and by the client / 3rd party application to decrypt the data and use it further. Secure encryption with salt – adds a random 64-bits salt to the data before encrypting it. Please note that using this feature requires the client to develop code for data decryption. For more information, see Encrypt Data.
Base URL	Base URL for all future method calls.
Callback URL	Also known as Redirect URI. Copy this URL and use it as Authorized redirect URL. Important! This is mandatory to enroll DRUID as a trusted application inside the Authorization Server of the web application.

Before using OAuth with DRUID, you must register DRUID with the web API service. This is done through a registration form in the developer or API section of the service’s website, where you will provide the following information (other information might be required):

Application Name
Application Website
Redirect URI or Callback URL – Provide the Callback URL you copied from DRUID (OAuth2 app). It is the URL where the service will redirect the user after granting an authorization code or access token.

Note: The redirect URI must be accessible by the end user; therefore, it might require whitelisting when used in environments like MS Teams tabs or web iFrames.

Example: Enrolling DRUID to Google Cloud API Services

Once your application (for DRUID) is registered, the service will issue client credentials (Client ID and Client Secret).
In DRUID Portal, in the OAuth2 app configuration page, enter the Client ID and Client Secret you got from the web application.

Example: Get credentials for DRUID from Google Cloud API Services

Save the OAuth2 app.

Step 2. Define Sign In integration

The Sign in action is mandatory for authentication and authorization when calling external API services on user’s behalf.

Define the Sign in action

To create a sign in action, follow these steps:

In the OAuth2 app configuration page, click the add icon () next to the Sign in Connector Action field.

The Connector Action page appears on the ConnectorGeneral tab.

Provide a Name, Description and Category and select Is Active.

Click Save. The page refreshes and displays on the ConnectorSteps tab.
At the top-right corner of the page, click the Create Task button and select Sign In.

The Edit Connector Action page appears on the General tab.

Define the Sign in integration task

Enter a Description and from the Connection Code drop-down, select the OAuth2 app you created at Step 1.

Click the Authorization tab and configure the authorization request.

Note: This call is always a GET method, with request data sent as query parameters, according to the industry standard. It cannot be modified to a POST, or configured with request data in the body section.

In the Authorization URL enter the auth_uri used to obtain end-user authorization for DRUID to access the web application or web service using the access token. The web application generated this auth_uri when you registered your DRUID application.

DRUID adds by default the following standard parameters (key/value pair) in the authorization request: client_id, redirect_uri and response_type. You can remove from standard parameters or add others to meet with the requirements of the web application you’re using to be granted with the authorization code.

Note: When mapping parameter values do not use “” or ‘, enter the values in clear.

Important! If the OAuth system you’re integrating with uses scopes, make sure to add the scopes in the mapping table to let the target application know for which privileges the call is requesting access. The scopes you provide should be in the list of scopes granted to DRUID when enrolling DRUID as a trusted application inside the Authorization Server of the web application.

Example: Authorization request for Google Calendar API

Click the Access Token Request tab and configure the authorization grant request.

In the Token request URL field, enter the token_uri DRUID will use to obtain authorization from the end-user to obtain an access token. The value of the token_urI is generated when you register DRUID in the web application.

Hint: The values for {{client_id}}, {{client_secre}}, etc., will automatically be replaced at runtime with the ones set on the OAuth App.

Example:

If the response from the API service provides a refresh token as well, you can also set up refresh token in the access token request. To do so, click Request Returns Refresh Token. A new tab appears, Refresh Token Request. Click on it and in the Refresh token request URL provide the endpoint of the web application, which handles refresh tokens. The Body contains by default the standard parameters necessary to obtain a refresh token.

Note: By default, the Request type is set to WwwFormURLEncoded, the method is POST and request data is set in the body of the call, according to the industry standard practices. However, the configurations can be modified to meet the Authorization Server specific.

You can test the Sign in action. Click the Authorization test tab and click the Test button.

Hint: You might need to meet specific web application prerequisites in order to test authorization (e.g., have at least one test user defined).

If the testing passes, you will get Success. In a future release, further passed/failed details will be provided.

Click Save & Close twice to go to the Integrations page. Publish the integration by clicking the Publish button () at the top-right corner of the page.

Step 3. Select Sign in action on the OAuth2 app

Go to the OAuth2 app configuration page and from the Sign in Connector Action field, select the integration you defined at Step 2.

By default, the access token is configured as part of the header of the request message. If your request requires authorization fields or the expected authorization is not part of the header, add them in the Authorization Fields table as shown in the following figure.

In the Key field, enter the name of the custom field to specify for authorization.
In the Value field, enter the value for the Key specified for the authorization.
From the Type field, select one of the following depending on where in the request message and the type of authorization fields that are required:

Header – The assistant expects the authorization field as part of the header of the request.
Parameter – The assistant expects the authorization field as part of the URL path for the request.

Click the Save icon displayed inline to save the additional authorization field.

Note: All integrations which use this OAuth App will automatically inherit this header key(s). The option, however, can be modified for each integration, specifically. An example is shown in the figure below.

Hint: In DRUID 7.11 onwards, you can add variables (e.g., username, password) to OAuth apps, in addition to the authorization fields. These variables can be kept secret throughout the integrations, enhancing security and flexibility.

Save the app.

You are now ready to design your flow.

Step 4. Design the flow for signing in users with OAuth v2

To sign in users with OAuth v2, from the Flow Palette, Dialog section, drag the Oauth 2.0 Sign in step and drop it within the flow where you want to perform the OAuth v2 sign in.

Configure the Oauth 2.0 Sign in flow step as follows:

Provide a flow step name.
From the Connection Code field, select the connector app you created for OAuth v2 authorization.
Tap on Get user identity only if you want to authenticate user within the conversation and if you have configured the second special action, Get User Identity, on the OAuth app. This will be called by the flow step, if the option is true.

For more information, see Authenticating User within the Conversation using OAuth v2.

In the Step message field, enter a message and include [[ChatUser]].OauthAccessURL, which stores the authorization URL.

Important! Including [[ChatUser]].OauthAccessURL in the Step message field is mandatory; otherwise, the users will be unable to authorize the assistant to perform further actions on their behalf.

Hint: You can use the link syntax in the Step message to provide the user with the authorization URL. E.g.: “Please click [here]([[ChatUser]].OauthAccessURL) to authenticate:”.

Save the step. Continue designing your flow with actions the assistant should perform on user’s behalf after getting user’s authorization.

Note: You can use the authorization URL in any other application and channel; this is why you might need to white list the domain of this application (the domain of the Redirect URL set on the OAuth2 app).

When the Sign in flow step is executed, DRUID assistant provides the user with the authorization link in the chat. Example:

If the user clicks the link, DRUID redirects the user to a DRUID hosted page (the login/consent page at the WEB API service). Example:

After the user confirms the authorization, the first special action in the OAuth App is automatically invoked and the authorization process completes, meaning that the access token will be saved in the conversation context and used on any integration which consumes that specific OAuth App. DRUID virtual assistant will further perform the actions on user’s behalf as set in the conversational flow.

Note: The first special action (Sign In Connector Action) will ONLY provide an access token (with the permissions set according to the requested scopes, if any) which can be used to authorize server-to-server API calls. To further authenticate the user in the conversation (from anonymous state), you should use the second special action, Get User Identity Connector Action as described in section Authenticating user within the conversation using OAuth v2.

Authoring flow for signing in users with OAuth v2 best practices

Use these best practices for authoring the flow where you want to perform the OAuth v2 sign in to ensure that the access token used to authorize server-to-server API calls is generated after expiry:

Set condition to execute the Oauth 2.0 Sign in flow step (the one you configured at step 4 above) only if [[ChatUser]].SSOToken == null.
After executing the Oauth 2.0 Sign in flow step, run the integration.
Handle the exceptions when the access token expires. For that, on the integration step, in the Metadata section, tap on Exception handler.

Add an action step for integration exception that is executed if [[SystemError]].IsException == true. The Oauth 2.0 Sign in flow step is executed if [[SystemError]].Code=="401".
Continue the conversation if no exceptions are thrown during the integration execution.