How to set up a generic Identity Provider for SSO

 Step-by-step guide for configuring SSO (Single Sign-On) authentication using your preferred Identity Provider.
access
accounts
realms

In this article, we’ll walk you through the entire process of adding an Identity Provider using either OpenID Connect or OAuth 2.0. If you’re looking to set up authorization with Google or GitLab, please check out their respective guides.

Note: SSO user authentication is tied to the Realms concept, so we recommend this article as a starting point as long as you need to set up at least one realm.

Prerequisites

  1. You have a third-party Identity Provider that operates via OpenID Connect or OAuth 2.0.

  2. You have the necessary access rights to create or manage applications (clients) in this Identproviderity Provider.

  3. You have access to the documentation, how-tos, and developer guides provided by this Identity Provider.

If you’re unsure whether your provider uses OpenID Connect and/or OAuth 2.0, simply review the provider documentation. If your provider supports both protocols, we recommend using OpenID Connect as it is slightly easier to configure. Since OpenID Connect is built on top of OAuth 2.0, some Identity Providers may support OpenID Connect while still using 'OAuth' in their configuration parameter names. This Wikipedia page is a good starting point if you use a well-known Identity Provider.

Configure Identity Provider application

The first action you need to take is to create an application in your Identity Provider. 'Application' is the most common word for this entity, also it's referred to as a 'client' in OAuth 2.0 and OpenID Connect terminology.

In order to integrate the Identity Provider in flespi you should specify the following parameters for a new application on the Identity Provider side:

  • scopes (can be called in a singular form);

    • for OpenID Connect providers set 'openid' and 'email';

    • for OAuth 2.0 there aren’t standard scope names, therefore you need to find in the documentation scopes which are responsible for providing these two points:

      • basic user information (we need just user ID here);

      • user email address;

  • redirect_uri (“Redirect URI”, “Redirect URIs”, etc). Set it to 'https://flespi.io/auth/callback'. Bear in mind that many Identity Providers display this redirect URI or at least its domain part to a user during the authentication process and it cannot be disabled. Also, after successful login with this redirect URI, a user will be redirected into a flespi panel. If either of these two points doesn’t suit your needs, you can resolve it with a custom redirect URI. But you can use 'http://flespi.io/auth/callback' at the start to see how everything works and then modify it later.

We use the so-called Authorization Code Flow or Authorization Code Grant to log in with an Identity Provider. It might be needed if your Identity Provider requires some granular protocol-specific configuration.

After or during the application configuration you will be provided with 'client id' and 'client secret'. Both those values are needed for Identity Provider integration in flespi. Keep in mind, that some Identity Providers do not allow you to see client secrets at any other time except right after application creation.

Configure Identity Provider in flespi

Regardless of Identity Provider type, there are some parameters common for any: 

  • Name - a unique Identity Provider name that is used for its identification in your flespi account

  • Client ID and Client secret. Put the corresponding values you obtained after the application is created in your Identity Provider.

  • Public Information - Name. This name is available via public API and displayed on the default realm login screen.

OpenID Connect (auto)

This is the recommended way to configure the new provider. Some OpenID Connect providers support configuration discovery. If you can find 'OpenID Connect Discovery' or '.well-known/openid-configuration' strings somewhere in your provider documentation, then most likely it does support configuration discovery. Even if you cannot find any clue regarding this feature, you may try to see how it goes. Manual configuration is always available as a fallback option.

Autodetect configuration mode is chosen by default in the Identity Provider creation form. You need to set 'Provider URL' in order to enable the mode, so here are several ways to know its value:

  • Find out in the identity provider documentation. If the documentation contains '.well-known/openid-configuration' string, then the string with such a suffix is the value you are looking for. You can use it as a provider URL either with or without this suffix.

  • Try the domain part of the Identity Provider API URL, if it does not contain any customer-specific information in the path part. For example, for the API URL 'https://openid.example.com/token' you should peek just 'https://openid.example.com'.

  • Try a customer-specific part of the API URL, if your provider API contains some per-customer unique parts in the part path. For example, for the API URL 'https://openid.example.com/CUSTOMER7777/token' you should peek at 'https://openid.example.com/CUSTOMER7777'.

  • Try to search in our list of known Identity Providers.

OpenID Connect (manual)

If your Identity Provider does not support configuration discovery or it does not follow to flespi requirements (e.g., configuration discovery might not provide some specific parameters), you can always configure the provider in manual mode. In manual configuration mode, you need to set Authorization, Token, and UserInfo endpoints. For these URLs, you have to look up the Identity Provider documentation.

OAuth 2.0 (manual)

OAuth 2.0 Identity Providers are supported in manual configuration mode only. It is necessary to provide Authorization, Token, and UserInfo endpoints which (can be found in the Provider documentation) and a set of scopes (the same values you specified during application creation on the Identity Provider side).

How to use Identity Providers in flespi

After the successful creation of an Identity Provider in flespi, you can link it to any of your realms. To do that navigate to 'Access Management > Realms > 'Your realm' > Providers', then click the ‘+’ button, and select Identity Provider from the list.

The 'power' button enables and disables a specific Identity Provider for the realm it is linked to (so that users can or can not log in). An Identity Provider disabled in one realm does not affect the identical one linked to another realm.

The 'shield' button enables and disables registration of new users. A new user is registered when the realm does not have a user that is linked to the specific Identity Provider user. Email address is used as a new username, so if there is another user with the same name, then registration fails.

If you need to link an Identity Provider account to an already existing user, then click the 'key' icon on the user tile and then select one of the Identity Providers linked to the realm. This button will copy a link which should be passed to the user. After successful authentication by this link, the user will link the Identity Provider account to the realm account.

To provide users with a login/registration link, click on the 'Login' in the top-right or use https://flespi.io/#/realm/{public_realm_id}. Now, if the user follows the link, the realm authentication page will show up - users can authenticate using the configured Identity Provider and save the realm for future use.

Custom redirection in the authorization flow

Sometimes it might be necessary to use a custom redirect URI/URL for the Identity Provider. The most common reasons are:

  • redirect users to a custom webpage instead of the flespi panel after successful login;

  • hide flespi usage from a user (since the Identity Provider may reveal the redirection page address in the authorization screen).

This can be done by the following steps:

  1. Host an intermediate handler on your own server.

  1. Specify the intermediate handler URL as a 'redirect_uri' parameter in the application configuration in the Identity Provider.

  1. Specify the intermediate handler URL as a 'Redirect URL' parameter in the Identity Provider configuration in flespi.

  1. Customize your intermediate handler so that it accepts GET requests, proxies them with all the received parameters to https://flespi.io/auth/callback/proxy, and handles the response from flespi as a general REST response. In case of successful login, this proxy callback returns a user token value that can be used by your need.

For example, if you hosted an intermediate handler at 'https://your.domain/app1/login', you should set a 'redirect_uri' parameter to 'https://your.domain/app1/login' instead of 'https://flespi.io/auth/callback' (more details here). In flespi, you should set a 'Redirect URL' to 'https://your.domain/app1/login'. Now you can write all the necessary logic in the language of your choice.

Known OpenID Connect providers 

Here’s a list of public OpenID Connect Identity Providers that support the configuration discovery option. Additionally, we’ve included notes for each specific case where this feature may not be entirely applicable for flespi.

Please note: this list may become outdated over time as we do not continuously monitor every Identity Provider’s documentation.

  • Apple

    • Provider URL: https://appleid.apple.com 

    • Not ok: configuration discovery does not provide the userinfo_endpoint parameter.

  • Facebook

    • Provider URL: https://www.facebook.com 

    • Not ok: configuration discovery does not provide token_endpoint and userinfo_endpoint parameters.

  • Gitlab

    • Provider URL: https://gitlab.com

  • Google

    • Provider URL: https://accounts.google.com

  • Kakao

    • Provider URL: https://kauth.kakao.com

  • Keykloak

    • Provider URL: https://{your-keykloak-server}/realms/{keykloak-realm}

  • LinkedIn

    • Provider URL: https://www.linkedin.com/oauth

  • Microsoft Online 

    • Common tenant Provider URL: https://login.microsoftonline.com/common/v2.0

    • Private tenant Provider URL: https://login.microsoftonline.com/{tenant}/v2.0

  • Microsoft Live

    • Provider URL: https://login.live.com

    • Not ok: configuration discovery does not provide the userinfo_endpoint parameter.

  • NetIQ

    • Provider URL: https://{your-netiq-server}/nidp/oauth/nam

  • Okta

    • Provider URL: https://{your-okta-domain}

  • PayPal

    • Provider URL: https://www.paypalobjects.com

  • Salesforce

    • Public Provider URL: https://login.salesforce.com

    • Private Provider URL: https://{your-salesforce-domain}.my.salesforce.com

  • Twitch

    • Provider URL: https://id.twitch.tv/oauth2

  • WSO2 Identity Server

    • Provider URL: https://{your-wso2-server}/oauth2/oidcdiscovery

  • Xero

    • Provider URL: https://identity.xero.com

See also
How to set up SSO authentication with GitLab as Identity Provider?
How to set up SSO (Single Sign-On) user authentication using GitLab as a custom Identity Provider.
access
accounts
realms