This page describes the requirements for connecting an existing OpenID Connect solution to allow for single sign-on using Beat’s APIs. We have a different guide about how to authenticate towards Beat’s APIs using OpenID Connect.

</aside>

Beat supports OpenID Connect (OIDC) as the authentication mechanism. This allows interoperation between a user database on your end, with the user database in Beat’s systems.

In short, when the users authenticate using OIDC, the end user is redirected to the external OIDC system, where the user authenticates themselves, and information is sent back to Beat containing the user details necessary.

Initial setup

OpenID Connect relies on providing a JWKS file in a well-known location, on a URL that does not change. The JWKS file contains enough information to set up a secure connection between Beat and the OIDC solution. The file is usually published at /.well-known/openid-configuration, and outlines the cryptographic solutions supported.

Beat currently only supports RS256 encryption.

</aside>

An agreement is made on which scopes should be requested alongside the token. Beat recommends the following scopes: openid offline_access.

Once this setup is in place, authentication between the systems should be possible using the authentication guide, and it will automatically work in any apps or websites built by Beat.

Data minimization and GDPR

In the cases where Beat does not “own” the user database, it makes sense to minimize the amount of private data that gets sent to Beat. We therefore recommend that the minimal amount of data is transferred.

The JWT should contain at minimum the following claims:

iss — Issuer Identifier
sub — Subject (user) Identifier
aud — Audience; matching a predefined value, likely https://api.prod.$TENANT.beat.no

These ID tokens are documented here: https://openid.net/specs/openid-connect-core-1_0.html#IDToken

We recommend leaving out any name and email claims from the JWT, as Beat has no need for this information.

Communicating region or locale

In some cases, beat might need to know about the region or locale of the user. For instance to show different layouts or other curated content in the apps depending on this value. For more on layouts see:

Layouts Explained