Identity Providers - Single Sign On (SSO)

This guide will help you understand generic steps of configuring third party identity providers like Facebook login, Auth0 etc.

The integration allows you to:

• Connect a User from an external service with a User in your Instance via email
• Connect currently logged in User with a User from an external service
• Register new User with data (name, email) provided by an external service

This is how identity providers work:

1. If the user tries to use an identity provider with [email protected] and such a user does not exist an account is created.
2. If the user tries to use an identity provider with [email protected] and such a user exists but is not connected to the identity provider this is what happens:
   • If the user is logged in as [email protected], connecting the accounts is allowed, next time the user will be able to log in using the identity provider.
   • If the user is not logged in, an error message is displayed saying such an account exists and is not connected to the identity provider.
   • If the user is logged in to a different account, they are notified that they are logged in to a different account and need to log out.
3. If the user tries to use the identity provider with [email protected] and such a user is connected to the identity provider then they are allowed to log in.
   • If the user is not logged in, they are allowed to log in.
   • If the user is logged in with a different email, an error message is displayed saying they need to log out.

Requirements

To follow the steps in this tutorial, you should be familiar with users. This guide builds on previous tutorials in the Developer Guide: Users section.

• Users

Steps

All identity provider integrations work the same way and consist of a few simple steps:

Step 1: Create application on the Identity Provider's website

You have to go to the third party website to create an application.

Step 2: Configure the application

On the Identity Provider's website, configure the application by setting the whitelist of the valid callback URL, which is https://<YOUR_DOMAIN>/auth/<PROVIDER>/callback.

Step 3: Partner Portal configuration

Go to the Partner Portal https://partners.platformos.com/instances/<YOUR INSTANCE ID>/edit and add Client ID, Client Secret and other parameters required by the specific provider to configuration -> integrations JSON.

Step 4: Use the /auth/<PROVIDER> endpoint on your Instance

After following the previous steps, everything is up and running. For example, you can add a Log In / Sign Up link on your instance pointing to /auth/<PROVIDER>. It will redirect the User to the provider's website and ask for login and password. Then it will redirect the User to the /auth/<PROVIDER>/callback and verify the request to ensure that the user has successfully logged in on the provider's site. platformOS will receive the token, along with some extra parameters like the User's email, first name etc. What happens next depends on the state:

1. If the user is not logged in yet:

• If Authentication for this provider does not exist yet, but the User with given email does - display error message to avoid potential account hijack.
• If Authentication does not exist and the User with given email address does not exist - create a new User email and Authentication for chosen provider.
• If Authentication exists, it logs the User in - that's the most common scenario, the User just wants to Log In to existing account using Identity Provider

2. If user is logged in:

• If Authentication does not exist, create Authentication - this allows to add multiple Identity Providers to one User, for example, the User can connect Facebook, Twitter and Google accounts
• If Authentication exists and is associated with the current user - do nothing
• If Authentication exists and is associated with a different user - re-log User to the one associated with Authentication

After success, platformOS redirects User to path provided in return_to parameter (i.e. your Log In page can be /auth/<PROVIDER>?return_to=/my-page) or homepage (default).

Listing all configured Identity Providers on the Instance

In graphQL, we have an endpoint which lists configured providers login_providers

{
  login_providers
}

You can also use the admin_third_party_integrations query to learn about the current configuration of any third party integration:

{
  admin_third_party_integrations {
    results {
      id
      type
    }
  }
}

Authentications

Authentication consists of a unique pair: user_id and provider. The first one stores the reference to a particular User and provider contains information about which Identity Provider was used. You can use GraphQL to get all of the User's authentications and tokens returned by the authentication provider, for example:

query {
  current_user {
    authentications {
      id
      token
      provider
    }
  }
}

Deleting Authentications

You can also remove authentication from the user by sending a DELETE request to /api/authentications/:id.

For the user, you can fetch created authentications:

{
  current_user {
    authentications {
      id
      token_expires_at
      provider
    }
  }
}