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
Here are explanations to the diagram:
A user logins in your Backend and receives a token.
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>
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).
Get user verification confirmation from your Backend.
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.
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:
Go to your Dashboard >> Your App >> Overview page.
Scroll to the bottom of your app's Overview page and enable Custom Identity Provider feature:
In the fields that appear configure your API URL to verify user and parameters mapping settings and click Update button:
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:
- API URL: https://yourserver.co/user/verify
Request params:
{"token": "#{login}"}
Response params:
{"uid": "#{user.id}"}
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