Third-party Authentication

Learn how to authenticate chatbot end-user during a conversation. Integrate with an existing authentication provider.

Overview

Authentication provides the ability to identify a user as a customer who already has an account with your business, so you can personalize and secure the experience. NativeChat supports OpenID Connect compliant login providers and Facebook Connect. See How to setup for details about configuring your bot.

Important: Use this type of authentication only if you want your chatbot to allow users to authenticate directly within the chat session. If you are placing your chatbot in a website or mobile app where the user is already authenticated, you can simply pass the authorization tokens to the chatbot when initializing the chat widget and then use them as headers to make authenticated requests from the Cognitive Flow.

How it works

User’s perspective

The user is prompted to log in.
The user is redirected to a login page on his browser.
The user enters his credentials (or signs in with an external provider such as OAuth0, Google, Facebook, etc.).
After successful login, the user is redirected back to the chat application.
The user is now authenticated with his account and the conversation continues

Developer’s perspective

Authentication flow

When the chatbot reaches a protected step it checks whether the user is already authenticated. If this is the case the bot skips the next steps and continues with the protected part of the Cognitive Flow.
A link or a button (depending on the communication channel) leading to the login page is displayed. The link includes a state query parameter which stores the information necessary for the proper account linking.
The user clicks the login link/button and lands on the login page.
The user signs in to their account. They may sign in with a username/password or via an external authentication provider, such as OAuth0, Google, Facebook, etc.
NativeChat receives the authentication parameters, issues a valid access token with the provider, and stores it in the configured Cognitive Flow entity.
NativeChat either redirects back to the chat app or returns a confirmation page that notifies the user that he has successfully authenticated with NativeChat. This step’s behavior can be customized using the settings parameters described in authentication settings.
When the user goes back to the chat application, NativeChat continues with the conversation.

Important: When the user is already logged in and has an access token which has expired, he will be prompted to authenticate again.

How to setup

OpenID Connect

Open your OIDC application’s settings and add https://api.nativechat.com/v1/account-linking as a login redirect URI
Open your bot’s Cognitive flow and within settings set the authentication property:

"settings": {
  ...
  "authentication": {
    "entity": "yourBusinessAuth", // This entity will be set to an object with an `access_token` property upon successful authentication
    "messages": [
      "You will need to login to your account before you can proceed." // This is the message sent to the user when prompted to authenticate
    ],
    "acknowledgements": [
      "You are now logged in YourBusiness." // This is the message that will be sent to the user after successful authentication
    ],
    "display": {
      "type": "login",
      "template": {
        "title": "YourBusiness SignIn",
        "image": "https://your.business.com/logo.png"
      }
    },
    "oidc": { // OpenID Connect configuration for the "Authorization code" flow
      "issuer": "https://some-openid-connect-provider/oauth2",
      "client-id": "client-id",
      "client-secret": "client-secret",
      "authorization-params": { // An optional parameter specifying parameters to the authorization endpoint
        "claims": "some-claims", // See your login provider's documentation for possible fields and values
        "resources": ["resource1", "resource2"]
      }
    },
    "ms-teams": { // Optional configuration that if specified will be used for user authentication in your bot in the MS Teams channel. Supports Single Sign-On in MS Teams.
      "connection-name": "AzureConnectionName", // The name of the OAuth connection on your Azure bot resource in Azure
      "strategy": "oidc"
    },
    "confirmation-page-auto-redirect": true, // Optional, true by default
    "confirmation-page-contents": { // Optional customization of the displayed page
      "title": "Login successful!",
      "text": "You can now close this tab and continue your conversation.",
      "attempt-close": true
    },
    "confirmation-page-redirect-url-web": "https://chat-bot-hosted-url/" // Optional URL to redirect upon successful login in the Web, Mobile and Rest channels
  }
}

OpenID Connect configuration settings

NativeChat supports the Authorization code flow of OIDC specification. You need to obtain and set the following parameters from your provider:

issuer - The base URL of the OIDC provider. E.g. https://dev-NNN.okta.com/oauth2/default
client-id - The client ID that you have issued for your bot
client-secret - The client secret that you have issued for your bot
authorization-params - an optional object containing any additional parameters that you need to pass to the authorization endpoint of the OIDC provider.

MS Teams configuration settings (OIDC)

NativeChat supports authentication providers set up directly on your Azure Bot resource in Azure. By specifying the authentication settings on your Azure Bot resource you will get a smoother authentication flow in your NativeChat bot in MS Teams. After a successful authentication, the bot will continue with the next step from the Cognitive Flow. This is also how you set up Single Sign-On (SSO) authentication in MS Teams. You need to obtain and set the following parameters from the connection setting on your Azure Bot resource:

connection-name - The name of the OAuth connection on your Azure bot resource in Azure
strategy - oidc

Facebook Connect

Enable Facebook Login on your Facebook app
Open your Facebook app’s Facebook Login settings and add https://api.nativechat.com/v1/account-linking as a Valid OAuth Redirect URI
Open your bot’s Cognitive flow and within settings set the authentication property:

"settings": {
  ...
  "authentication": {
    "entity": "yourBusinessAuth", // This entity will be set to an object with an `access_token` property upon successful authentication
    "messages": [
      "You will need to login to your account before you can proceed." // This is the message sent to the user when prompted to authenticate
    ],
    "acknowledgements": [
      "You are now logged in YourBusiness." // This is the message that will be sent to the user after successful authentication
    ],
    "display": {
      "type": "login",
      "template": {
        "title": "YourBusiness SignIn",
        "image": "https://your.business.com/logo.png"
      }
    },
    "facebook": { // Facebook Connect configuration for the "Authorization code" flow
      "app-id": "app-id",
      "app-secret": "app-secret"
    },
    "ms-teams": { // Optional configuration that if specified will be used for user authentication in your bot in the MS Teams channel.
      "connection-name": "FacebookConnectionName", // The name of the Facebook connection on your Azure bot resource in Azure
      "strategy": "facebook"
    },
    "confirmation-page-auto-redirect": true, // Optional, true by default
    "confirmation-page-contents": { // Optional customization of the displayed page
      "title": "Login successful!",
      "text": "You can now close this tab and continue your conversation.",
      "attempt-close": true
    },
    "confirmation-page-redirect-url-web": "https://chat-bot-hosted-url/" // Optional URL to redirect upon successful login in the Web, Mobile and Rest channels
  }
}

Facebook Connect configuration settings

NativeChat supports the Authorization code flow of the Facebook Connect specification. You need to obtain and set the following parameters from your Facebook app:

app-id - The app ID of your Facebook app
app-secret - The app secret of your Facebook app

MS Teams configuration settings (Facebook)

NativeChat supports Facebook authentication providers set up directly on your Azure Bot resource in Azure. By specifying the authentication settings on your Azure Bot resource you will get a smoother authentication flow in your NativeChat bot in MS Teams. After a successful authentication, the bot will continue with the next step from the Cognitive Flow. You need to obtain and set the following parameters from the connection setting on your Azure Bot resource:

connection-name - The name of the OAuth connection on your Azure bot resource in Azure
strategy - facebook

After successful login NativeChat will attempt to redirect the user back to the chat application. In case the channel does not support this, the user will see a simple confirmation page briefly before it closes automatically. You can adjust this behavior and the confirmation page itself so that they fit your specific case better using the following parameters:

confirmation-page-auto-redirect - The default value of this property is true. In case the channel supports this, after a successful login NativeChat will redirect the user back to the chat application. This is usually the correct behavior, but in some cases, it could be better to use the confirmation page. One such case is Facebook Messenger in the browser. With confirmation-page-auto-redirect set to true, the user will end up with two browser tabs showing the same chat window. This property applies to the following channels:
- Facebook Messenger - via https://m.me/... links,
- Viber - via viber://pa?chatURI=... links,
- Line - via the https://line.me/R/ link.
confirmation-page-redirect-url-web - an optional string which if configured will be used as a redirect URL. In case this is not provided, the user will see the confirmation page. This property applies to the following channels:
- Web
- Mobile
- Rest
confirmation-page-contents - an optional object which overrides the default look of the confirmation page:
- title - A string specifying the title of the page, the default value is "Login successful!"
- text - A string specifying the body of the page, the default value is "You can now close this tab and continue your conversation."
- attempt-close - A boolean flag specifying whether the page should close automatically.

How to use

On any step of the conversation that requires the user to be authenticated, you set the "protected": true property.

The user will be prompted to log in only if the entity specified in the settings is uninitialized, has a value which is falsy (null, undefined, false, …), or contains an access_token property set to a valid JSON Web Token which has expired.

"conversations": {
  "bookDoctor": {
    "type": "goal",
    "display-name": "book a doctor",
    "steps": [
      {
        "protected": true, // you can set the protected attribute on any step
        "type": "webhook",
        "data-source": {
          "endpoint": "https://your.business.com/api/bookDoctor",
          "method": "GET",
          "headers": {
            "Content-Type": "application/json",
            "Authorization": "Bearer {{yourBusinessAuth.accessToken}}"
          }
        }
      }
    ]
  }
}

Requirements & Implementation Notes

Alexa

After authorization the conversation with the Alexa skill must be restarted.

When end-users reach a step in the Cognitive Flow that requires account linking, Alexa will send a notification to their mobile phone. Via the Alexa app on their phone, they’ll enter their account details (username, password etc.) and complete the account linking. When the authorization is complete, their session with the chatbot is ended. Users need to start a new conversation with the Alexa skill with its invocation name.

Tip: Warn the users that after successfully authenticating, they’ll need to restart the conversation with your skill.

MS Teams

The MS Teams channel can’t send an asynchronous message (i.e. bot initiated message without it being a reply to the user). If you have not set the authentication provider on your Azure Bot resource in Azure, after a successful authentication the bot will not continue the conversation. To continue with the conversation after authenticating, users will have to send a message.

If you have set the authentication provider on your Azure Bot resource in Azure and added the ms-teams configuration to the Cognitive Flow of your bot, then after a successful authentication the bot will automatically continue the conversation.

Supported Channels

NativeChat supports authentication with OpenID Connect for the following channels:

Web
Mobile
REST
Facebook Messenger
Viber
Line
Alexa
MS Teams

Single Sign-On (SSO) Support

NativeChat supports Single Sign-On authentication for MS Teams only.

Somethings missing or not clear?

Ask a question in our community forums or submit a support ticket.