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 Scenes does not support them at this time.

There are two ways you can obtain an OAuth compliant Authentication system:

  1. You can use a commercial OAuth provider like Bubble or Auth0 (recommended)
  2. You can create your own authentication system that complies with the OAuth protocol (Consider this only if you have a tech/engineering team with the relevant experience)

How to Set up SSO on Scenes?​

Prerequisites for Using Scenes SSO​

  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).

Steps​

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 Scenes 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 Scenes 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"

  1. 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.


Response Type: 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 Scenes 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 Scenes 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": "mandatory",
    "first_name": "mandatory",
    "last_name": "mandatory",
    "profile_image": "optional",
    "uid/sub": "mandatory"
    }
    ```

  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.


Disabling Scenes 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 Scenes Login Toggle. This Toggle will allow you to switch ON or OFF, the default Scene’s Login options.

Disabling the Scenes Login will mean users attempting to Login will be redirected directly to your own Login page (specified in your SSO settings).

Enabling the Scenes 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 Scenes default login)