Skip to main content

Single Sign On - steps to set up

What is SSO?​

Single Sign-On (SSO) is a feature through which a user can sign in to all subdomains of an organization through one account. Suppose an organization has services like a digital game store (games.x.com), an OTT platform video.x.com, and a game streaming platform like Stadia play.x.com. Instead of maintaining separate accounts for all services a central account can be maintained to help users get access to all the services. Big tech giants like Google, Microsoft, Amazon, etc. already use SSO. Benefits of SSO

  • login process gets simplified, a user no longer needs to log in for every service
  • as the authentication server is decoupled from other services, and scalability increases.

What is OAuth and Why use it?​

Before understanding OAuth let's go back in time and understand how things worked before OAuth Suppose Netflix wants to access some info in your IMDB account to understand your taste and improve the recommendation engine. Earlier the way to do this was: you would share your email and password of IMDB to Netflix so that it can access data on your behalf. But that's insecure and no one would like to do it even if it is a trusted organization. OAuth tried to solve this problem of delegated access so that some service can access data on your behalf from another service with your consent. OAuth is a protocol by which one can implement SSO on their platform. It is by far the industry standard and widely used. There are other authentication protocols besides OAuth (such as JWT, SAML etc.) , however Graphy Community does not support them at this time. We provide support for three OAuth providers:

  1. Bubble
  2. Custom (Auth0)
  3. JSON Web Tokens (JWT) - Recommended
Custom SSO

Prerequisites:​

  1. Your own login and authentication system that meets two conditions:
    1. complies with the OAuth protocol
    2. Makes use of a user’s phone number AND/OR email address
  2. Your own login page (with forgot password etc.)
  3. Response Type: Code or Token The response type. Must be code or token. Indicates whether the client wants an authorization code for the user (authorization code grant flow), or directly issues tokens for the user (implicit flow).

Response Type​

Code
  1. Provider Name: We'll use this name as the suffix of the Continue button. For example, type "Cognito" if you want the button to say "Continue with Cognito". Untitled
  1. Client ID: It is a unique ID for your community that is shared by the OAuth provider (Bubble, Auth0, etc. ) to enable a handshake mechanism for authorization of users. (See the “Getting your Client ID & Client Secret” section)
  1. Client Secret: While the client ID is visible to users and relatively public, the Client secret, is like a hidden password that will be used during the handshake method (between your community & OAuth provider) for user verification. (See the “Getting your Client ID & Client Secret” section)
  1. Login URL: This is your own login page. Please ensure that it is able to accept query params such as
    1. client_id= Example : r7r070bta8t0b2qo5nagq4593
    2. redirect_uri=Example : https://anubhav.avalonmeta.com/oauth2/callback
    3. response_type= code As an example, this would look something like this:
    {YOUR_LOGIN_URL}?client_id=r7r070bta8t0b2qo5nagq4593&redirect_uri=[https://anubhav.avalonmeta.com/oauth2/callback&response_type=](https://anubhav.avalonmeta.com/oauth2/callback&response_type=token)code
    You would copy and paste something similar to the above block into the Login URL field. After successful Login, you will need to redirect the user to the “Callback URL/ Redirect URI” . This URL will depend on the response type; if the response type is Code, then the URL would look something like this:
    https://anubhav.avalonmeta.com/oauth2/callback?code=AUTHORIZATION_CODE
    Note: All these above URLs are examples and for illustration purposes only. You will be able to get your “Callback URL/ Redirect URI” from your community settings in the ‘Single Sign-on’ Section: Untitled
  1. Token API / Fetch URL: In this field you need to provide your complete token API endpoint. An example of this would be: https://dev-rafkjfjwwnad.us.auth0.com/oauth/token The token endpoint only supports HTTPS POST. We will be making this call (HTTPS POST) from our backend server to get the access token for the user info API call. An example API request using the above example endpoint would look something like this:
curl --location --request POST '[https://dev-rafkjfjwwnad.us.auth0.com/oauth/token](https://dev-rafkjfjwwnad.us.auth0.com/oauth/token)' \
--header 'Authorization: Basic dW1QbVh5UG92UFZjSkhjbmliZExBTzk0bE1tM3NhaEU6djVJWW13TFVyZXVZV1NqM0Qw' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=umPmXyPovPVcJHcnibd' \
--data-urlencode 'code=KukmnDwicwdfG0lP2FSERsc7wUbUkTG' \
--data-urlencode 'redirect_uri=https://anubhav.scenes.social/oauth2/callback'

Request params in body:

  • grant_type : Must be authorization_codeor refresh_token. You can request an access token for a custom scope from the token endpoint when, in the app client, the requested scope is enabled.
  • client_id : It is a unique ID for your community that is shared by the OAuth provider (Bubble, Auth0, etc. ) to enable a handshake mechanism for authorization of users. (See the “Getting your Client ID & Client Secret” section)
  • code : This is the value returned by your authentication system after a successful login and the user is redirected to our “CALLBACK URL / REDIRECT URI”.
  • redirect_uri : This is the same as your callback URL. After successful Login, you will need to redirect the user to the “Callback URL/ Redirect URI” . Sample Response for the Token API request: HTTP/1.1 200 OK
                       Content-Type: application/json
                       {
                        "access_token":"eyJz9sdfsdfsdfsd",
                        "id_token":"dmcxd329ujdmkemkd349r",
                        "token_type":"Bearer",
                        "expires_in":3600
                       }
  1. User info API URL: In this field you need to provide your complete user info API endpoint. An example of this would be: https://dev-rafkjfjwwnad.us.auth0.com/oauth/userinfo We use this endpoint to obtain user details that are mandatory and required for a community. This is an example of a User info API request using the above example endpoint:
    ```jsx
    GET https: https://dev-rafkjfjwwnad.us.auth0.com/oauth/userInfo
    Authorization: Bearer <access_token>
    ```
    The ‘access_token’ field in the above example can be obtained from the response of the token endpoint (see point 5, above)
    The response for this endpoint would look like this:
{
    "email": "optional",
   "first_name": "mandatory",
   "last_name": "mandatory",
   "profile_image": "optional",
   "uid/sub": "mandatory",
   "phone_number": "optional",
   "phone_country_code": "optional"
}

Note: either email or phone_number and phone_country_code is required to be there. If sending phone_number and country code in phone_number field then format to be phone_number: +918273749485 ; If sending the fields separately then it to be phone_number: "8273749485", phone_country_code: "+91" 7. Scope(Optional) If you are setting up your SSO with Auth0, it is mandatory to fill the 'SCOPE' field with appropriate parameters. This is a mandatory prerequisite for Auth0 SSO to work with our system.

Token
  1. Provider Name: We'll use this name as the suffix of the Continue button. For example, type "Cognito" if you want the button to say "Continue with Cognito". Untitled
  1. Client ID: It is a unique ID for your community that is shared by the OAuth provider (Bubble, Auth0, etc. ) to enable a handshake mechanism for authorization of users. (See the “Getting your Client ID & Client Secret” section)
  1. Client Secret: While the client ID is visible to users and relatively public, the Client secret, is like a hidden password that will be used during the handshake method (between your community & OAuth provider) for user verification. (See the “Getting your Client ID & Client Secret” section)
  1. Login URL: This is your own login page. Please ensure that it is able to accept query params such as
    1. client_id= Example : r7r070bta8t0b2qo5nagq4593
    2. redirect_uri=Example : https://anubhav.avalonmeta.com/oauth2/callback
    3. response_type= token As an example, this would look something like this:
    {YOUR_LOGIN_URL}?client_id=r7r070bta8t0b2qo5nagq4593&redirect_uri=[https://anubhav.avalonmeta.com/oauth2/callback&response_type=token](https://anubhav.avalonmeta.com/oauth2/callback&response_type=token)
    You would copy and paste something similar to the above block into the Login URL field. After successful Login, you will need to redirect the user to the “Callback URL/ Redirect URI” . This URL will depend on the response type; if the response type is Token, then the URL would look something like this:
    https://anubhav.avalonmeta.com/oauth2/callback#access_token={ACCESS_TOKEN}
    Note: All these above URLs are examples and for illustration purposes only. You will be able to get your “Callback URL/ Redirect URI” from your community settings in the ‘Single Sign-on’ Section: Untitled

  1. User info API URL: In this field you need to provide your complete user info API endpoint. An example of this would be: https://dev-rafkjfjwwnad.us.auth0.com/oauth/userinfo We use this endpoint to obtain user details that are mandatory and required for a community. This is an example of a User info API request using the above example endpoint:

     ```jsx
     GET https: https://dev-rafkjfjwwnad.us.auth0.com/oauth/userInfo
     Authorization: Bearer <access_token>
     ```
     The ‘access_token’ field in the above example can be obtained from the query params of the Login URL (see point 4, above).
     The response for this endpoint would look like this:
     ```
     {
            "email": "optional",
         "first_name": "mandatory",
         "last_name": "mandatory",
         "profile_image": "optional",
         "uid/sub": "mandatory",
         "phone_number": "optional",
         "phone_country_code": "optional"
         “others” : {“source” : “website” , “gender” : “male”, ...}
     }
     ```

    Note 1: either email or phone_number and phone_country_code is required to be there. Note 2: The above mentioned value in ‘others’ parameter is just an example. You can pass any useful user data in json format.

    If sending phone_number and country code in phone_number field then format to be phone_number: +918273749485 ; If sending the fields separately then it to be phone_number: "8273749485", phone_country_code: "+91"

  2. Scope(Optional) If you are setting up your SSO with Auth0, it is mandatory to fill the 'SCOPE' field with appropriate parameters. This is a mandatory prerequisite for Auth0 SSO to work with our system.

Getting your Client ID & Client Secret​

Here’s a great document explaining these concepts in detail: https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/ There are two cases here, depending on your OAuth provider:

  1. 3rd Party Commercial OAuth Provider: they will provide you with the client ID & secret directly
  2. Your own OAuth implementation:
    1. Client ID: You will need a randomly generated (typically a 32 character hex string). Some examples of the Client IDs of popular services that support OAuth:
      • Foursquare: ZYDPLLBWSK3MVQJSIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q
      • Github: 6779ef20e75817b79602
      • Google: 292085223830.apps.googleusercontent.com
      • Instagram: f2a1ed52710d4533bde25be6da03b6e3
    2. Client Secret: Similarly you will need to randomly generate a string for this. The more secure and complex the better. While your Client ID will be visible and mostly public, the Client Secret will need to be kept secure and hidden, for this purpose we recommend using some form of encryption. For example in Ruby: You can use the “securerandom” library to generate an encrypted secret.
JWT SSO

Single Sign-On is a feature that allows a user to sign into an external platform and Graphy Community in a single login. Users will sign into your external platform. Once they successfully log in, your application will construct a token (JWT) and redirect to Graphy Community Platform URL with JWT token as a parameter. From this token, we find the user and signs them in, or if they haven't registered, we create an account and signs them in.

Graphy SSO Url Format​

https://community.medha.com/oauth2/callback?jwt_token=AUTHENTICATION_TOKEN

You will find the callback url in your community SSO settings. JWT SSO JSON Web Tokens () consist of three parts separated by dots (.), which are: Header Payload Signature Therefore, a JWT typically looks like the following. xxxxx.yyyyy.zzzzz

The header consists of two parts: the type of the token, which is JWT, and the signing algorithm being used, such as HMAC SHA256. For example : { "alg": "HS256", "typ": "JWT" } Then, this JSON is Base64Url encoded to form the first part of the JWT. In our case, the first part of the token is - eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Payload​

The payload is the Base64Url encoded form of payload data. Payload Data format :

{
   "email": "optional",
   "first_name": "mandatory",
   "last_name": "mandatory",
   "profile_image": "optional",
   "uid/sub": "mandatory",
   "phone_number": "optional",
   "phone_country_code": "optional"
   “others” : {“source” : “website” , “gender” : “male”, ...}
}

Note 1: either email or phone_number and phone_country_code is required to be there.

Note 2: The above mentioned value in ‘others’ parameter is just an example. You can pass any useful user data in json format.

If sending phone_number and country code in phone_number field then format to be phone_number: +918273749485 ;

If sending the fields separately then it to be phone_number: "8273749485", phone_country_code: "+91"

Signature​

To create the signature part you have to take the encoded header, the encoded payload, api-token, the algorithm specified in the header, and sign that. You will find your client secret after you complete the steps mentioned below.

Steps to Set Up SSO​

  1. Log in to your Graphy Community account by going to your community url.
  2. Go to Settings -> Single Sign-on.
  3. Select JWT as the OAuth Provider.
  4. Select authentication mode as Email, Phone number or Email or Phone number.
  5. Provider Name: Specify the name of the JWT provider or service that you will be using for authentication. This name will be displayed on the login button.
  6. Authorization or Login URL: Provide the URL where users will be redirected to authenticate using the JWT provider. Users will need to enter their credentials and authenticate on this page.
  7. Logout URI: Specify the URI where users will be redirected when they log out of your platform. This can be a specific page or endpoint.
  8. Logout Redirect URI: Set the URL to which the JWT provider will redirect users after they have been logged out. It should be a valid URL within your platform.
  9. Logout Redirect Param: It will be the variable name in which you'll pass the logout url. For e.g. In oauth2, the Logout Redirect Param is 'returnto'.
  10. Switch on the toggle from the top and 'Save settings' to enable SSO. Click on Save Settings to save the JWT-based SSO configuration.

Note: The Save Settings action will generate a secret key. Make sure to securely store this secret key as it will be used to validate the JWT tokens received from the provider during the authentication process. After successful Login, you will need to redirect the user to the “Callback URL/ Redirect URI” .

Disabling Graphy Community Platform Login​

After setting up your SSO, you will get access to a section called “Advanced Settings” on your SSO settings page. Clicking on Advanced Settings will give you access to the Graphy Community Platform Login Toggle. This Toggle will allow you to switch ON or OFF, the default Graphy community’s Login options. By default it will be disabled. That means,users attempting to Login will be redirected directly to your own Login page (specified in your SSO settings). Enabling the Graphy Community Platform Login will mean users attempting to Login will first be redirected to an intermediary screen asking whether the user would like to sign-in via SSO or via “Others” (which is the Graphy Community Platform's default login)