Identity Providers

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

Requirements

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

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/ 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
  1. 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 LinkedIn 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 see 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
    }
  }
}

Questions?

We are always happy to help with any questions you may have.