Single sign on using an external identity provider

Overview

Please note: secure SSO is already enabled as part of Edge2Cloud and doesn’t require using this feature.

From FIN 5.1.1 onwards, single sign on (SSO) can be set up using OpenID Connect. This enables users to skip the standard FIN username and password and use an external identity provider (IdP).

• User tags are configured by mapping an external user in an IdP to a FIN group (user prototype).

• SSO is configured within the host app by a super user.

Most IdPs do require each client (FIN) uses https and has a registered domain name. It should be also noted the most IdPs do allow http and localhost for testing purposes.

Open

Logging in

1. After setting up OpenID Connect, navigating to a page in FIN will automatically redirect a user to log in via OpenID Connect. This skips the standard log in screen.

2. The standard local log in screen is still accessible if a user navigates directly to /user/login.

   • Also note that logging out of FIN will also log the user out of the IdP.

3. Once authenticated, a resultant user is transient and does not exist in FIN’s user database.

Implementation

Each time a user logs in via OpenID Connect, FIN receives a digitally signed user identity token. FIN cryptographically authenticates this token every time a user logs in.

FIN uses the authorization code flow + PKCE (proof key for code exchange). By default, FIN requests the openid, profile and email scopes.

Configuration

FIN’s OpenID Connect implementation has been tested with the following IdPs that support OpenID Connect…

• AWS Cognito

• Auth0

• Google

• Azure AD

It should be noted that each IdP is set up differently. To configure OpenID Connect in FIN, please navigate to Settings within FIN’s host application.

Redirection URI

When configuring an IdP, a redirection URI back to FIN needs to be added. This is used after a user has successfully authenticated with the IdP. The format of the redirection is as follow:

For instance, if we were testing this out with localhost, the redirect URI would be…

Discovery endpoint

The discovery endpoint URI is used by FIN to look other URIs and information required by OpenID Connect. Typically it’s in the form of…

For example, Google uses…

Client id and secret

A unique client identifier and secret is used by the authorization server.

Logout endpoint

The URI used to log a user out of an IdP.

The first version of OpenID Connect does not describe how a user can be logged out of a session so this can vary between IdPs.

Logout method

The HTTP method used to log a user out. By default an HTTP GET is used to log a user out.

Host URI

FIN’s own host URI. For example, for testing purposes this could be http://localhost:8080. In production this might be https://ilovefin.com.

Mapping users to groups (user prototypes)

When a user successfully authenticates using OpenID Connect, the user must be associated with a user group (user prototype) in FIN. This association happens by configuring the group attribute, group priority attribute, group default and apply tags function. A special oidcUserProtoAttrVal string tag also needs to be added to the group record.

To see how this happens, let’s take a look at the following scenario…

Open

A user is going to log in as Fred. Once authenticated, a user needs to be mapped to a group in FIN as either an operator or engineer. In order for this mapping to happen, the group attribute needs to be set to groups. Therefore FIN will look at the authenticated user’s group attribute. This will be matched against the group’s oidcUserProtoAttrVal value.

• If no group can be matched and a group default is configured this will act as the fallback value group for the user. If no group default is configured the user will be presented with an error screen in FIN.

• If multiple groups are matched, the group priority attribute can be used to identity the highest priority group to use. The group priority attribute is a comma separate list of group names (userProtoName).

In the above example, the user fred belongs to the eng group. FIN has the group attribute set to groups and will match it to the group with the oidcUserProtoAttrVal value of eng. Therefore when Fred logs on, he’s granted permission as an admin in the engineering group.

Customizing the user record

The user record can be optionally customized further through the use of an Axon function.

The apply tags function (applyTagsFunc) is used to modify a user record before a user session is created. Here’s an example…

Examples

Working out the configuration for an IdP can be quite tricky and time consuming. Although the data here is fictious, here are some examples of how each IdP can be configured with the sort of data that needs to be entered in the configuration. This is to give you an idea of what the configuration should look like for each IdP.

To get up and running, it’s recommended just to configure the group default to prove a user can log in using the selected IdP.

AWS Cognito

Discovery endpoint: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_Rare3IjEQ/.well-known/openid-configuration
Logout endpoint: https://testme.auth.us-east-1.amazoncognito.com/logout
Logout method: POST
Client id: 2vohui0m18il8iq2r0bov2qdos
Client secret: 92nl45ru2cgggs319d256b601rpjp1j7873s32omav32sn8arc8

Google

Discovery endpoint: https://accounts.google.com/.well-known/openid-configuration
Logout endpoint: https://www.google.com/accounts/logout
Logout method: GET
Client id: 74913405524-qb70jte6kpu5sg8m8t2djseusqa82fh7.apps.googleusercontent.com
Client secret: Fv_lqdObVwRgBZubnKx35YzH

Also add access_type=offline, prompt=consent to authorization options.

Azure AD

Discovery endpoint: https://login.microsoftonline.com/d4bf160c-d3cd-417d-9c10-2ed2dd8f021b/v2.0/.well-known/openid-configuration
Client id: b85d5fdb-9c9f-4d03-d07f-20cc19ff9bb9
Client secret: d0U3rI.L0rh.0BQk3AZ1UZ0Dp2-6QupNU-

Also add offline_access to the list of scopes.

Auth0

Discovery endpoint: https://dev-ohet457q.us.auth0.com/.well-known/openid-configuration
Client id: SVO1qfUthb5tm2k0vjPJQvMyJcwE9pej
Client secret: _Zm2Kl5jhJxTQlTWJ-qGe8QtUwbTMotSZNaYqViFBq8zehqpp6Z4QgUeXFpiMOEd
Logout endpoint: https://dev-ohet457q.us.auth0.com/v2/logout?returnTo=http://localhost:8080&client_id=SVO1qfUthb5tm2k0vjPJQvMyJcwE9pej

Single sign on using FIN

Overview

Please note: secure SSO is already enabled as part of Edge2Cloud and doesn’t require using this feature.

This feature is available to use from FIN 5.1.1 onwards.

If there are multiple FIN instances being used (and Edge2Cloud isn’t being used), a single FIN instance can be used to managed users and provide single sign on (SSO) to all other instances of FIN. This uses a technology called OpenID Connect whereby FIN can act as both a server and a client.

In the following example, a user navigates to FIN B and is redirected to FIN A to log in as Fred. After logging in, the user is seamlessly redirected back to FIN B as Fred.

Getting started

In this example, we’re going to set up SSO between two FIN instances. When a user attempts to navigate to FIN in FIN B, they will be redirected to FIN A to log in. Therefore FIN A will be the identity provider to FIN B.

• HTTPS should be used for secure communication.

• Host URI setting needs to be set on each FIN instance.

• FIN B needs to use FIN A’s OIDC server details.

  • Go to FIN A and log in as a super user.

  • Click on Settings.

  • Scroll down to the OpenID Connect (SSO) section.

  • Click Yes for server enabled setting.

  • Click on OIDC Server Details.

  • Record the Discovery endpoint, client id and client secret information.

  • Navigate to FIN B and log in as a super user. Again navigate to the OpenID Connect (SSO) settings.

  • Enter the recorded information into the Discovery endpoint, client id and client secret settings and save.
    Navigating to FIN B should now redirect the user to FIN A to log in. After logging in, the user should be navigated back to FIN A.

  • Under Host go to Crypto. Add FIN A’s address (i.e. https://fina) as a trusted URI.

    • Although not ideal, FIN A is most likely using a self signed certificate hence we need to explicitly trust it.

Advanced

By default, SSO between different FIN instances will use the user set up in the identity provider. However, the advanced features of SSO using an external identity provider are still available to use. As this section specifies, users can still be mapped to a group (user prototype).

Additional security can also be enforced by the user of the server callback URLs. By default * is used to allow any client. It can be restricted further by using a comma separate list of callback URLs.

Configuration

• Server enabled: enables the FIN instance as an SSO server. By default, this is disabled.

• Server HTTP only: by default HTTPS has to be used for all FIN clients. Changing this to no means HTTP can also be used. Please note, it’s always best practice to use HTTPS so the system is secure by default.

• Server callback URLs: a list of URLs the FIN server will accept as clients. By default this is * which means any client with the client id and secret will be accepted.

  • If the server callback URLs setting does not contain a *…

    • A comma separated list of URLs will be used to validate the clients (i.e. https://finB/finOidc/redirect).

    • Any project in FIN A that has a haystack connector will be checked to see if the client acceptable (i.e. FIN A has a haystack connector with a valid URI to FIN B).

• OIDC server details: clicking this button will display this server’s discovery endpoint, client id and secret. As per the getting started section, this information is used by other FIN instances to set up SSO.

All other settings are described in using single sign on using an external identity provider.

Example set up process using Azure

This example is using Azure. The steps and info is similar to other providers but where the info is found in the UI of each provider will be different.

1. In Microsoft Azure dashboard search for "Azure AD B2C"

2. Go to App Registration in the AD B2C page

3. Click on the Endpoints tab and copy the "OpenID Connect metadata document" field and paste to "Discovery Endpoint" property in FIN

   1. Looks something like this but with your endpoint:

4. Then click on New registration tab in the dashboard to create a new registration if you don’t already have one.

   1. Name it whatever you want.

   2. We typically select the first option for the API access.

   3. The Redirect URI should be set to "Web" with the value being what is in the doc under the "Redirection URI" section. You can use your domain name here. Something like this:

   4. Register it once done.

5. Then paste that URI host in the Host URI property in FIN

   1. Should look something like this:

6. Then open that new or existing registration to copy the "Application (client) ID" and paste it to "Client ID" property in FIN.

   1. Should look something like this but with your client ID:

7. Then create a client secret by clicking on the "Client Credentials" link in the dashboard or by clicking on “Certificates & secrets” option in the left menu.

   1. Then click on "New client secret", add description, and then Add

8. Once client secret is created, copy the "Value" not "Secret ID" and paste that in the "Client Secret" in FIN.

   1. Should look like something below but with yours:

9. Go back to the Azure dashboard to the "Token configuration" tab on the left side still under the registration view.

   1. Select "Add groups claim", tick all the boxes and Save.

10. Then in FIN add "offline_access" to the list for the Scope property.

11. Go to the Users → Groups in FIN to set up a default group. Create a Group called "default" (recommended). This is so that if the Azure user doesn’t belong to an existing Azure group, their permissions will default to this.

12. Once done, add the default FIN group name in the "Group Default" property.
    Note: To add reference other groups, look at the Mapping users to groups section above.

13. That is it, try it now.

14. If you want to use the normal login without the Microsoft login redirect, the URL should be something like this: host:port/user/login