undefined

External authentication via Custom Identity Provider (CIdP)

Overview

Custom Identity Provider (CIdP) feature is necessary if you need to use an external database to authenticate your application users instead of database on your ConnectyCube server. It allows you to integrate your user base with ConnectyCube easily and works the same way as Facebook/Twitter SSO.

With Custom Identity Provider feature you can continue using your user database instead of storing/copying user data to ConnectyCube database.

Login flow diagram

Custom Identity Provider login flow

Here are explanations to the diagram:

  1. A user logins in your Backend and receives a token.

  2. The user logins to ConnectyCube with data received from your Backend:

    POST https://api.connectycube.com/login
    login=<IP-user-token>
    password=<any-random-value-to-pass-the-validation>
  3. ConnectyCube backend sends a request to your Backend to verify the user:

    GET https://yourserver.co/user/verify?token={token}

    Note: This URL can be configured in your ConnectyCube Dashboard (check the instrucitons below).

  4. Get user verification confirmation from your Backend.

  5. If ConnectyCube server gets successful verification in the result on the previous stage, a ConnectyCube user will be created (during first login) and ConnectyCube session token will be returned to access ConnectyCube API.

  6. Next step is login to Chat. Use user_id and ConnectyCube session token retrieved at the previous stage (as password) to log in to Chat.

Setup

In order to use Custom Identity Provider feature you need to configure it in your ConnectyCube Dashboard as follows:

  1. Go to your Dashboard >> Your App >> Overview page.

    Open your app's Overview page in Dashboard

  2. Scroll to the bottom of your app's Overview page and enable Custom Identity Provider feature:

    Check mark Enable custom Identity Provider authentication option

  3. In the fields that appear configure your API URL to verify user and parameters mapping settings and click Update button:

    Cofigure your API URL to verify user and parameters mapping settings

    Important note: Allow reuse ConnectyCube user option is required if some users had been created in ordinary manner (with login and password, for example) earlier and then you switched to Custom Identity Provider (CIdP) authentication. When check marked, this option allows you to update existing users when they log in via your CIdP and the usernames (the old user and the new user) coincide. After this merger the old user will be able to log in via your CIdP.

Example

Let's assume your API URL to verify users is as follows:

GET
 https://yourserver.co/user/verify?token={token}

And it returns the following JSON response in case of successfully verification:

{"user": {"id": 2345, "login": "simon371", "fill_name": "Simon Davis"}}

In this case you need to set the following parameters in your ConnectyCube Dashboard:

After that you can login to ConnectyCube with the following login method:

POST https://api.connectycube.com/login
login=IP_user_token

Your login parameter will be translated into token parameter then.

Starter Kit

There is ready starter demo project for using Custom identity provider service for ConnectyCube:

https://github.com/ConnectyCube/custom-idp-starter-kit

Have any issues?

Raise an issue https://github.com/ConnectyCube/custom-idp-starter-kit/issues