Setting Up Authentication for Action Tasks

Depending on the Bot action task, you may need to define how a user must authenticate to initiate the task. For example, Twitter can have an action task using web services that require an end-user to authenticate, usually with a log on username and password, to allow Kore to access the end-user account for data before executing the task.

After you describe your Bot task on the General Information page, the Authentication Setup page is displayed as shown in the following illustration.

If you have previously defined authentication for this task, you can select it in the Authorization provider drop-down list. If your task does not require authentication, you can select None in the Authorization provider drop-down list.

To define a new authorization provider, click Create New to display the New Authorization Mechanism dialog.

In the Authentication Type drop-down list, select the type of authorization used by your Bot as shown in the following illustration.

You can choose one of the following types of authorization:

  • Basic Auth - A standard protocol to collect username and password information. Kore uses SSL encryption in combination with basic authentication to help secure end-user information.
  • OAuth v1 - Enables web applications or web services to access protected resources using an API without end-users having to disclose their log on credentials to Kore. 
  • OAuth v2 - The newest version of OAuth protocol focusing on specific authorization flows for web applications and web services.
  • API Key - An identification and authorization token generated or provided by a web application or web service used to identify the incoming application request, and in some cases, also provides authentication for secure access.

Setting Up Authorization using Basic Auth

The following illustration is an example of the Basic Auth fields that you must define to enable basic authorization for your task. 

To define basic authorization, select Basic Auth in the Authorization Type field. Then specify a Name for the authorization to be displayed in the Bot builder user interface. If required, in the Subdomains section, select This authorization has subdomains if the base URL for a web application or user interface the uses the tenant name in the URL, for example, http://www.kore.zendesk.com

Adding Authorization Fields

By default, authorization fields are configured as part of the header of the task request message. If your task request requires additional authorization fields or the expected authorization is not part of the header, for example, social security number or PIN, click Add Authorization Field and then define the fields as shown in the following illustration.

In the Field Type field, you can select one of the following depending on where in the task request message and the type of authorization fields that are required.

  • Header - The Bot expects the authorization fields as part of the header of the request.
  • Payload - The Bot expects the authorization fields as part of the content of the body of the request.
  • Query String - The Bot expects the authorization fields as a query in the body of the request.
  • Path Param - The Bot expects the authorization fields as part of the URL path for the request.

Add Fields to the Authorization Form

If the default username and password fields do not meet your needs, you can add new fields displayed to the end-user by adding authorization form fields. To add or on the authorization form, click Add Authorization Form Fields. The following illustration is an example of a definition to add a PIN text box to the authorization dialog.

The following table describes the field used to define an authorization form field.

Field NameDescription
Title of Field Specify the name of the field displayed to the end-user in the authentication dialog.
Field Key The field key represents the end-user input value to the authenticating service.
Help Hint The help text displayed in the field to describe what should be entered into the field.
Field Type When Advanced Options is selected, specify the type of field displayed in the end-user interface to collect the user input assigned as the value for the Field Key, one of:
  • Textbox
  • Password
Mandatory When Advanced Options is selected, specify if the end-user must define this field to complete authentication.
Data Type When Advanced Options is selected, specify the type of data expected as input from the end-user.
Visibility  When Advanced Options is selected, specify if the authentication field should be visible, hidden, or displayed as read-only.

In the Authorization Check URL section, you can optionally define a URL that can be used to test the authentication settings from Bot Builder before you deploy the task with the authorization mechanism. You can use dynamic fields, path parameter fields, query fields, and so forth, to define the test URL, for example, https://www.{authfield1 key}.com/{authfield2 key}.

Click Save Auth to save the authorization settings and close the New Authorization Mechanism dialog.

Testing the Authorization

After you save the authentication, you can test your authorization definition on the Authentication page when you click Test Authorization before continuing to develop the remain steps of your task.

When you click Test Authorization, the Test Authorization dialog is displayed and populated with the URL you specified in the Authorization Check URL section, as shown in the following illustration.

When the validation of authentication is complete, the Test Authorization dialog is closed and the results of the validation, either success or failed, is displayed to the immediate right of the Test Authorization button. 

How it all Works

When basic authorization is used for a task, the Kore application automatically prompts the user for log on credentials to access the web application or web service as shown in the following illustration.

After the end-user authenticates, the settings are saved using the following naming syntax:

<First Name> <Last Name>'s <Bot Name> Account # <Sequence #>

For example, John Smith's Twitter Account #1.

The Kore application can access the web application or web service for all future task requests using this account. In addition, the end-user can reuse the account for other tasks for the same Bot.

Setting Up Authorization using OAuth v1

OAuth is an open protocol to allow secure authorization in a simple and standard method from web, mobile, and desktop applications.

To use OAuth, you must first register an account with the web application as you will need the log on credentials for that application to configure the settings for the authorization mechanism.

How OAuth v1 Works

  1. The Kore application obtains an unauthorized request token from the web application.
  2. The Kore application redirects the user to a login dialog at the web application.
  3. The user authorizes the request token, associating it with their account.
  4. The web application redirects the user back to the Kore application.
  5. The Kore application exchanges the request token for an access token.
  6. The access token allows the Kore application to access a protected resource at the provider, on behalf of the user.

To define OAuth v1, define the fields described in the following table.

Field NameChild Field NameDescription
Authorization Type   Set to OAuth v1.
Bots Callback Link   The URL used by the web application or web service to redirect the end-user after end-user authorization is complete. This value is provided as a read-only value by the Kore application when you define OAuth v1 settings.
Identity Provider Name   The name of the web application or web service, for example, Twitter. This field is required.
Request Token Link   The URL used by the Kore application to obtain an unauthorized request token. A request token is the value used by the Kore application to obtain authorization from the end-user to obtain an access token. After end-user authorization, an access token can be requested by the Kore application. This field is required.
Access Token Link   The URL used to exchange the end-user authorized request token for an access token. The access token is the value used by the Kore application to gain access to the web application or web service on behalf of the end-user, instead of using the end-users log on credentials. This field is required.
User Authorization Link   The URL used to obtain end-user authorization for the Kore application to access the web application or web service using the access token. This field is required.
Consumer Key   The value provided as the Kore application identification to the web application. This field is required.
Consumer Secret   The secret value provided by the Kore application to establish ownership of the Consumer Key. This field is required.
Subdomains   Select to enable use of tenancy, for example, as a subdomain of the Bot such as www.kore.zendesk.com.
Add new Key & Value pair   If the Bot requires additional values for authorization, add one or more Key/Value pairs. For example, some Bots support using a scope key using read-only, write, or both as the value.
Field Key The name of the custom field to specify for authorization.
Value The value for the custom field for authorization.

Add Authorization Field
If your authorization requires additional end-user authorization fields, for example, social security number or PIN, click Add Authorization Field and then define the fields shown in the following illustration.In the Field Type field, you can select one of the following depending on where in the task request message and the type of authorization fields are required for your task.
  • Header - The Bot expects the authorization fields as part of the header of the request.
  • Payload - The Bot expects the authorization fields as part of the content of the body of the request.
  • Query String - The Bot expects the authorization fields as a query in the body of the request.
  • Path Param - The Bot expects the authorization fields as part of the URL path for the request.

Click Save Auth to save the authorization settings and close the New Authorization Mechanism dialog.

Setting Up Authorization using OAuth v2

OAuth v2 is the new version of the open protocol to allow secure authorization in a simple and standard method from web, mobile, and desktop applications.

To use OAuth v2, you must first register an account with the web application as you will need the log on credentials for that application to configure the settings for the Authorization Mechanism.

How OAuth v2 Works

  1. The Kore application redirects the user to a login dialog at the web application.
  2. The user authenticates.
  3. The web application redirects the user back to the Kore application with an access token.
  4. The Kore application validates the access token.
  5. The access token allows the Kore application to access a protected resource at the provider, on behalf of the user.

The following illustration shows the fields to define for the OAuth v2 Authorization Type

To configure OAuth v2, define the fields described in the following table.

Field NameChild Field NameDescription
Authorization Type   Set to OAuth v2.
Bots Callback Link   The URL used by the web application or web service to redirect the end-user after end-user authorization is complete. This value is provided as a read-only value by the Kore application when you define OAuth v2 settings.
Identity Provider Name   The name of the web application or web service, for example, Zendesk. This field is required.
Client ID   The ID of the Kore client.
Client Secret Key   The value provided as the Kore application authentication based on the Client ID to the web application. 
Authorization URL   The URL used to obtain end-user authorization for the Kore application to access the web application or web service using the access token. This field is required.
Subdomains   Select to enable use of tenancy, for example, as a subdomain of the Bot such as www.kore.zendesk.com.
Token Request URL   The URL used by the Kore application to obtain an unauthorized request token. A request token is the value used by the Kore application to obtain authorization from the end-user to obtain an access token. After end-user authorization, an access token can be requested by the Kore application. This field is required.
Scope   The secret value provided by the Kore application to establish ownership of the Consumer Key. This field is required.
Add new Key & Value pair   If the Bot requires additional values for authorization, add one or more Key/Value pairs. For example, some Bots support using a scope key using read-only, write, or both as the value.
Field Key The name of the custom field to specify for authorization.
Value The value for the custom field for authorization.

Add Authorization Field
If your authorization requires additional end-user authorization fields, for example, social security number or PIN, click Add Authorization Field and then define the fields shown in the following illustration.In the Field Type field, you can select one of the following depending on where in the task request message and the type of authorization fields are required for your task.
  • Header - The Bot expects the authorization fields as part of the header of the request.
  • Payload - The Bot expects the authorization fields as part of the content of the body of the request.
  • Query String - The Bot expects the authorization fields as a query in the body of the request.
  • Path Param - The Bot expects the authorization fields as part of the URL path for the request. 

Click Save Auth to save the authorization settings and close the New Authorization Mechanism dialog.

Setting Up Authorization using an API Key

An API key can act as both a unique identifier and a secret token for identification as well as authentication to provide a set of access rights on the associated API. Instead of prompting the end-user for both a username and password for access, the user is prompted only for an API key when configuring the task.

To use the API Key Authorization Type, you must first register an account with the web application and then generate an API Key for that application to configure the settings for the Kore authorization mechanism.

The following illustration shows the fields to define for the API Key Authorization Type

To configure the API Key Authorization Type, define the fields described in the following table.

Field NameDescription
Authorization Type Set to API Key.
Name The name of the API Key displayed in Bot Builder.
Subdomains Select to enable use of tenancy, for example, as a subdomain of the Bot such as www.kore.zendesk.com.

Adding Authorization Fields

By default, authorization fields are configured as part of the header of the task request message. If your task request requires additional authorization fields or the expected authorization is not part of the header, for example, social security number or PIN, click Add Authorization Field and then define the fields as shown in the following illustration.

In the Field Type field, you can select one of the following depending on where in the task request message and the type of authorization fields that are required.

  • Header - The Bot expects the authorization fields as part of the header of the request.
  • Payload - The Bot expects the authorization fields as part of the content of the body of the request.
  • Query String - The Bot expects the authorization fields as a query in the body of the request.
  • Path Param - The Bot expects the authorization fields as part of the URL path for the request.

Add Fields to the Authorization Form

If the default username and password fields do not meet your needs, you can add new fields displayed to the end-user by adding authorization form fields. To add or on the authorization form, click Add Authorization Form Fields. The following illustration is an example of a definition to add a PIN text box to the authorization dialog.

The following table describes the field used to define an authorization form field.

Field NameDescription
Title of Field Specify the name of the field displayed to the end-user in the authentication dialog.
Field Key The field key represents the end-user input value to the authenticating service.
Help Hint The help text displayed in the field to describe what should be entered into the field.
Field Type When Advanced Options is selected, specify the type of field displayed in the end-user interface to collect the user input assigned as the value for the Field Key, one of:
  • Textbox
  • Password
Mandatory When Advanced Options is selected, specify if the end-user must define this field to complete authentication.
Data Type When Advanced Options is selected, specify the type of data expected as input from the end-user.
Visibility  When Advanced Options is selected, specify if the authentication field should be visible, hidden, or displayed as read-only.

In the Authorization Check URL section, you can optionally define a URL that can be used to test the authentication settings from Bot Builder before you deploy the task with the authorization mechanism. You can use dynamic fields, path parameter fields, query fields, and so forth, to define the test URL, for example, https://www.{authfield1 key}.com/{authfield2 key}.

Click Save Auth to save the authorization settings and close the New Authorization Mechanism dialog.

Testing the Authorization

After you save the authentication, you can test your authorization definition on the Authentication page when you click Test Authorization before continuing to develop the remain steps of your task.

When you click Test Authorization, the Test Authorization dialog is displayed and populated with the URL you specified in the Authorization Check URL section, as shown in the following illustration.

When the validation of authentication is complete, the Test Authorization dialog is closed and the results of the validation, either success or failed, is displayed to the immediate right of the Test Authorization button.

Next Steps

After testing is complete, click Continue to open the Configure the Action Task Request page. For more information, see Configuring the Task Request.

Comments