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.

How it works

User’s perspective

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

Developer’s perspective

Authentication flow

  1. 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.
  2. 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.
  3. The user clicks the login link/button and lands on the login page.
  4. 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.
  5. NativeChat receives the authentication parameters, issues a valid access token with the provider, and stores it in the configured Cognitive Flow entity.
  6. 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.
  7. When the user goes back to the chat application, NativeChat continues with the conversation.

How to setup

OpenID Connect

  1. Open your OIDC application’s settings and add https://api.nativechat.com/v1/account-linking as a login redirect URI
  2. 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

  1. Enable Facebook Login on your Facebook app
  2. Open your Facebook app’s Facebook Login settings and add https://api.nativechat.com/v1/account-linking as a Valid OAuth Redirect URI
  3. 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

Customization of the login confirmation page

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.

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.