Third-party Authentication

Integrate a NativeChat chatbot with an existing authentication system directly within the conversation experience.

Authentication provides the ability to identify a user as a customer who already has an account with your business, so you can personalize the experience.

"settings": {
  ...
  "authentication": {
    "entity": "yourBusinessAuth",
    "messages": [
      "You will need to login to your account before you can proceed."
    ],
    "acknowledgements": [
      "You are now logged in YourBusiness."
    ],
    "display": {
      "type": "login",
      "template": {
        "title": "YourBusiness SignIn",
        "url": "https://your.business.com/login",
        "image": "https://your.business.com/logo.png"
      }
    }
  }
}

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 Facebook, Google, 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 and if not, it starts the authentication process, otherwise, continues with the conversation.
  2. A link or a button is provided to the user which navigates to a login page hosted in the browser. The link includes a state query parameter which stores information necessary for the proper account linking at a later stage.
  3. The user clicks the login link or a button and lands on your login page.
  4. The user signs in his account. He may sign in with username/password or via an external authentication provider, such as Facebook, Google, etc.
  5. You obtain an access token from your authentication provider, that you need to pass back to the conversation along with the state parameter so that NativeChat can persist your token in the conversation.
  6. Make a POST request to the account linking endpoint. Put the state parameter obtained earlier as a query parameter. Put the access token and any other information you may need in the body in JSON format.

     var url = "https://api.nativechat.com/v1/account-linking?state={{$encodeURI [the state parameter provided earlier]}}"
    
     var body = {
         "accessToken": "{{your access token}}",
         // other parameters you may want to use
     }
    
  7. NativeChat stores the whole body into your authentication entity and sends back a JSON containing the channel type and a verification token.
  8. Redirect the user back to the chat application and complete the authentication.
    1. Use a deep link for facebook and viber channels. Use the channel type and the verification token to construct the correct link.
      1. facebook - https://m.me/{{your-page-url}}?ref={{encodeURI verificationToken}} - use ‘progressnativechat’ as your page-url when testing via the proxy bot
      2. viber - viber://pa?chatURI={{encodeURI [your-public-account-url]}}?context={{encodeURI verificationToken}}
    2. For web post a message to the webchat HTML window with the verification token.
         parent.postMessage({ type: 'authentication', token: data.verificationToken }, 'https://webchat.nativechat.com');
      
  9. The user is redirected to the chat app and if the verification token is correct the authentication is completed.
  10. NativeChat sends a message to the user to acknowledge a successful login.
  11. NativeChat continues with the conversation and uses the stored access token to access protected resources.

How to setup

Open your bot’s Cognitive flow and within ‘settings’ sets the ‘authentication’:

"settings": {
  ...
  "authentication": {
    "entity": "yourBusinessAuth", // The entity name where to store the user's business account information. In most cases stores an access token.
    "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",
        "url": "https://your.business.com/login",
        "image": "https://your.business.com/logo.png"
      }
    }
  }
}

The ‘url’ parameter may contain query string parameters such as ‘client_id’, ‘redirect_uri’, etc. (except ‘state’), which may be required by the authentication protocol of your site.

How to use

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

The user will be prompted to log in only if he is not already logged in or the access token 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

Facebook

Make sure to enable the ‘messaging_referrals’ events in Facebook Developers -> your project -> Messenger -> Webhooks

Viber

If your bot is already configured to use Viber channel, just re-publish it

Web

Make sure the page that posts the verification token to the webchat is either the one that is configured in the authentication template URL setting or has its origin added to a trusted domain in settings.

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.