Legend

Authentication and SSO

Legend supports local accounts out of the box and, on plans that include it, single sign-on through OpenID Connect (OIDC). SSO lets people sign in with your existing identity provider so you manage access in one place. This page covers both, with a complete OIDC procedure written against the standard so it applies to any compliant provider such as Okta, Microsoft Entra ID, Google Workspace, Auth0, or Keycloak.

Local accounts

Local accounts are the default. The first administrator is created on first run, and further users can be invited from the admin area. Local accounts are a good fit for small teams or for an initial rollout before you connect an identity provider.

  • Require strong passwords and, where available, a second factor.
  • Invite users rather than sharing a single account, so ownership and activity stay meaningful.
  • Keep at least one local administrator account even after enabling SSO, as a recovery path.

What OIDC gives you

With OIDC, people sign in through your identity provider and are returned to Legend already authenticated. You control who can sign in from the provider, and you can map provider groups to roles inside Legend so access follows your existing structure.

Before you start: gather these values

Configuring OIDC is mostly a matter of exchanging a handful of values between your identity provider and Legend. Have these ready:

  • Issuer URL: the base URL of your provider, from which its OIDC discovery document is served.
  • Client ID: the identifier your provider assigns to the Legend application.
  • Client secret: the confidential secret paired with the client ID.
  • Redirect URI (also called the callback URL): the Legend URL your provider sends users back to after login.
  • Scopes: at minimum openid, plus profile and email so Legend can read the user’s name and address.

Step 1: Register Legend with your identity provider

  1. In your identity provider, create a new application, choosing the web application or confidential client type.
  2. Set the redirect URI to your Legend callback URL. A conventional form is https://legend.example.com/api/auth/callback, but use the exact path your release documents.
  3. Request the openid, profile, and email scopes.
  4. Save the application and copy the issuer URL, client ID, and client secret.

The redirect URI must match exactly on both sides, including https and any trailing path. A mismatch here is the most common reason an OIDC login fails, so copy it rather than typing it.

Step 2: Configure OIDC in Legend

Provide the values you gathered to Legend. Depending on your release, these are set as environment variables at deploy time, in the admin settings, or both. As environment variables they typically look like this:

  • OIDC_ISSUER_URL=https://id.example.com/
  • OIDC_CLIENT_ID=legend-web
  • OIDC_CLIENT_SECRET=replace-with-the-client-secret
  • OIDC_REDIRECT_URI=https://legend.example.com/api/auth/callback
  • OIDC_SCOPES=openid profile email
  1. Set the issuer, client ID, client secret, redirect URI, and scopes to the values from your provider.
  2. Keep the client secret in your secret store, never in a committed file.
  3. Apply the configuration and restart the instance if it reads these values at startup.

Step 3: Map users and roles

When someone signs in through OIDC, Legend identifies them from the token your provider returns and matches or creates a corresponding user. To keep permissions aligned with your organization, map provider groups or claims to Legend roles.

  1. Decide which Legend role each group of people should get, for example administrators versus regular members.
  2. Configure your provider to include a groups or roles claim in the token it issues to Legend.
  3. In Legend, map those claim values to roles so, for example, members of your platform-admins group become administrators.
  4. Confirm that people without a mapped group get a sensible default, such as a read-and-contribute member role.

Step 4: Test the login

  1. Open Legend in a private browser window and choose the single sign-on option.
  2. Complete authentication at your identity provider.
  3. Confirm you are returned to Legend, signed in, with the role your group mapping should grant.
  4. Test with a non-admin account as well, to confirm the default role is correct.

Screenshot: the sign-in screen showing the single sign-on option alongside local login.

Troubleshooting OIDC

  • Redirect URI mismatch: confirm the URI is identical in the provider and in Legend, including scheme and path.
  • Invalid client: recheck the client ID and secret, and that the secret has not been rotated.
  • Missing name or email: ensure the profile and email scopes are requested and released by the provider.
  • Wrong role after login: verify the groups or roles claim is present in the token and that your mapping matches its values.