SSO / OpenID Connect
How to setup Marble to use your OpenID Connect-compliant identity provider
Marble supports, from version .54 onwards, for users with a license, authentication through an identity provider that is compliant with OpenID Connect, in order to centralize user management, observe your organization's compliance requirements (including multiple factor authentication) and single sign-on.
Configuring your Marble instance to use OpenID Connect will completely replace Firebase as the authentication provider. It means from then on, only Marble accounts whose email address match one on your identity provider will be able to log in.
If you were used to create aliases, such as
[email protected]for users to authenticate through different user accounts, those alias will now have no way to connect to your Marble instance.
As of now, the OpenID Connect configuration is instance-wide, so all your organizations will use the same OpenID Connect issuer and user pool. As such, there is still the requirement that Marble users are created beforehand in the Settings page before they can log in, so we can map them to their organization.
The permissions from existing users will remain as they were previously.
Supported providers
Even though OIDC-compliant providers should all work as expected, we tested functionality with the following provider:
- Google Workspace
- Microsoft Entra ID
- Auth0
- Okta
- WorkOS
- Keycloak
If you would like another identity provider to be included in our testing suite, or if your identity provider does not work with Marble, please reach out to support.
Configuration
Configuring a Marble instance to use OpenID Connect requires adding four required environment variables on your backend instance. A few other variables are optional and can be added to customize the integration.
| Variable | Req. | Description |
|---|---|---|
| AUTH_PROVIDER | ✔️ | Set to oidc to enable OpenID Connect. |
| AUTH_OIDC_ISSUER | ✔️ | Issuer URL for your provider. Must match exactly (watch out for trailing slashes, for example) [1]. |
| AUTH_OIDC_CLIENT_ID | ✔️ | Application's client ID. |
| AUTH_OIDC_CLIENT_SECRET | ✔️ | Application's client secret. |
| AUTH_OIDC_SCOPE | Scopes to request, defaults to openid,profile,email,offline_access. Must be a valid OIDC scope set, and grant access to the required claims. The openid scope is always required. | |
| AUTH_OIDC_ALLOWED_DOMAINS | Comma-separated list of domains whose users will be allowed to log in. Defaults to allowing any user that has a valid and authorized account on the identity provider. | |
| AUTH_EXTRA_PARAMS | Additional query string parameters to append to the authorize request. |
[1]: The provided URL must expose a discovery endpoint for your provider. You can check by visiting <issuer>/.well-known/openid-configuration.
Required claims
Any authenticated principal must present some claims that are required for the authentication to go through. The following table lists which claims are supported, whether they are required, and the usual scope that give access to them.
Depending on your provider's configuration, claims might be released when requesting different scopes than presented here.
| Claim | Req. | Scope | Usage |
|---|---|---|---|
| ✔️ | email | Identify a user canonical identifier | |
| email_verified | ✔️ | email | Identify a user canonical identifie |
| given_name | profile | Update the user's name in Marble | |
| family_name | profile | Update the user's name in Marbl |
Also, a refresh token should be emited by your identity provider in order to maintain a user's session. Usually, a refresh token is generated when adding the offline_access scope (might not be true depending on the provider, such as Google Workspace).
Provider-specific configuration
Marble needs an OAuth2 client that supports the authorization_code flow, which are typically denoted as "Web clients" or "Secure clients" on a lot of providers.
For all providers, when creating the application / client in their administration interface, you should use a Redirect URI of https://<marble_frontend_public_url>/oidc/callback.
The rest of this section will list some providers that have peculiarities that might deviate from the standard of the obvious configuration path.
Google Workspace
The identity provider used with Google Workspace does not use the offline_access scope to generate a refresh token. Instead, if requires a custom query parameter on the authorize request in order to do so. Thus, to use Google Workspace as your identity provider, the configuration should look thus:
AUTH_OIDC_ISSUER='https://accounts.google.com'
AUTH_OIDC_CLIENT_ID='<client id>'
AUTH_OIDC_CLIENT_SECRET='<client secret>'
AUTH_OIDC_SCOPE='openid,profile,email'
AUTH_OIDC_EXTRA_PARAMS='prompt=consent&access_type=offline'You can obtain a client ID / client secret pair by creating an OAuth2 client in the Developers Console.
Microsoft Entra ID
To use your Microsoft Azure AD / Microsoft Entra ID directory as an identity provider, you must create a "Web" App Registration in your Azure Portal and create a Client Secret in the Certificates & secrets section.
In order for the required claims to be released, you grant the appropriate permissions to the client, in the API permissions section. The required permissions are the following:
- Microsoft Graph ->
email - Microsoft Graph ->
profile - Microsoft Graph ->
User.Read
Finally, you must add the following optional claims in the Token configuration section:
emailgiven_name(optional)family_name(optional)
You must use the modern endpoint for your issuer URL, so that your configuration looks like this:
AUTH_OIDC_ISSUER='https://login.microsoftonline.com/<tenant id>/v2.0'
AUTH_OIDC_CLIENT_ID='<client id>'
AUTH_OIDC_CLIENT_SECRET='<client secret>'
AUTH_OIDC_SCOPE='openid,profile,email,offline_access'Updated 11 days ago