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.

What you should provide to Beat

A Client ID - the public identifier that the auth service issues to an app: something like "yourservicename-mobile-app” (we don’t need client secret)
the metadata url, that also called “well-known” endpoint, should be something similar to: "https://yourwebsitedomain/.well-known/openid-configuration”. It returns a JSON document containing essential configuration details for OpenID Connect, such as authorization, token, and user info endpoints, as well as signing key locations
OpenID Connect (OIDC) scopes are used by an application during authentication to authorize access to a user’s details. It can be: “openid_offline”, or “offline_access” for example.