Single Sign-On (OIDC)

Starter Single Sign-On (OIDC) requires the Starter tier or above.

Single Sign-On (SSO) allows users to authenticate to Legend using your organization’s existing identity provider. Instead of creating separate credentials for Legend, users log in with their corporate accounts, and Legend automatically provisions and synchronizes user accounts and group memberships.

What Is OIDC?

OpenID Connect (OIDC) is an authentication protocol built on top of OAuth 2.0. It allows applications like Legend to verify a user’s identity using an external identity provider (IdP) without handling passwords directly.

When a user logs in to Legend with OIDC:

1. Legend redirects the user to your identity provider
2. The user authenticates with their corporate credentials
3. The identity provider sends authentication information back to Legend
4. Legend creates or updates the user account based on the received information
5. The user is logged in to Legend

OIDC is widely supported by enterprise identity providers including Google Workspace, Microsoft Azure AD, Okta, Keycloak, Auth0, and many others.

Prerequisites

Before configuring OIDC in Legend, you need:

An identity provider with OIDC support. Common options include:

• Google Workspace (formerly G Suite)
• Microsoft Azure Active Directory
• Okta
• Keycloak (self-hosted)
• Auth0
• OneLogin

OIDC configuration details from your identity provider:

• Issuer URL: The base URL of your identity provider (e.g., https://accounts.google.com, https://login.microsoftonline.com/{tenant-id}/v2.0)
• Client ID: A unique identifier for your Legend application
• Client Secret: A secret key used to authenticate Legend to your identity provider

Redirect URI: Your identity provider needs to know where to send users back after authentication. The redirect URI for Legend is:

https://your-legend-domain.com/api/auth/oidc/callback

Replace your-legend-domain.com with your actual Legend domain.

Accessing OIDC Settings

To access OIDC configuration:

1. Click your user menu in the top-right corner
2. Select Admin Panel from the dropdown
3. Click Single Sign-On (OIDC) in the admin sidebar

Only users in the Admins group can access OIDC settings.

Configuring OIDC

1. Enable OIDC: Toggle the Enable OIDC switch to enable single sign-on

2. Enter the Issuer URL: Paste the issuer URL from your identity provider. This is typically found in your IdP’s OIDC configuration documentation or discovery endpoint.

3. Enter the Client ID: Paste the client ID you obtained when registering Legend with your identity provider.

4. Enter the Client Secret: Paste the client secret. This is a sensitive credential that authenticates Legend to your identity provider.

5. Configure Scopes: Specify the OIDC scopes to request from your identity provider. Common scopes include:

   • openid: Required for OIDC authentication
   • profile: Provides user profile information (name, email)
   • email: Provides the user’s email address
   • groups: Provides group membership information (if supported by your IdP)

6. Set the Groups Claim: If your identity provider includes group membership in the OIDC token, specify the claim name that contains group information. Common claim names include groups, roles, or memberOf. This field is optional but required for automatic group synchronization.

7. Configure Allowed Groups: Optionally restrict Legend access to specific groups. If you specify allowed groups, only users who are members of at least one of these groups can log in to Legend. Leave this field empty to allow all authenticated users.

8. Set Default Groups: Specify which Legend groups new users should be automatically added to when they first log in. This is useful for assigning baseline permissions to all new users.

9. Enable Auto-Create Person Cards: Toggle this option to automatically create person entities for users when they first log in. This populates your Legend instance with organizational data as users authenticate.

10. Test the Connection: Click Test Connection to verify that Legend can communicate with your identity provider. The test validates the issuer URL, client credentials, and OIDC discovery endpoint.

11. Save Configuration: Click Save to apply the OIDC configuration.

Client Secret Security

The client secret is a sensitive credential that authenticates Legend to your identity provider. Never share it publicly or commit it to version control. If the client secret is compromised, regenerate it in your identity provider and update the configuration in Legend immediately.

Test Before Enabling

Always test the OIDC connection before enabling it for production use. The test connection feature validates your configuration without affecting existing users. If the test fails, review your identity provider settings and ensure the redirect URI is correctly configured.

Group Synchronization Modes

Professional Group synchronization requires the Professional tier or above.

When OIDC is configured with group claims, Legend can synchronize group memberships from your identity provider. Three synchronization modes are available:

Import Mode

In import mode, Legend reads group memberships from the OIDC token and adds users to the corresponding Legend groups. If a user is removed from a group in the identity provider, they are also removed from the group in Legend on their next login.

When to use:

• You want Legend groups to mirror your identity provider groups
• You manage group memberships centrally in your identity provider
• You want automatic group updates without manual intervention

Force Mode

In force mode, Legend enforces group memberships from the OIDC token. If a user is not in a group in the identity provider, they are removed from that group in Legend, even if they were manually added by an administrator.

When to use:

• You want strict enforcement of group memberships
• You don’t want administrators to override identity provider group assignments
• You need compliance with centralized access control policies

Ignore Mode

In ignore mode, Legend ignores group information from the OIDC token. Group memberships are managed manually in Legend and are not affected by identity provider group changes.

When to use:

• You want to manage Legend groups independently of your identity provider
• Your identity provider doesn’t support group claims
• You need fine-grained control over Legend group memberships

Auto-Creating Person Cards

When the auto-create person cards option is enabled, Legend automatically creates a person entity for each user when they first log in through OIDC. The person entity is populated with:

• Name: From the OIDC name or preferred_username claim
• Email: From the OIDC email claim
• Title: From the OIDC job_title or title claim (if available)
• Teams: Based on the user’s group memberships (if group synchronization is enabled)

Auto-created person cards help populate your Legend instance with organizational data as users authenticate, reducing manual data entry.

Manual Person Cards

Even with auto-creation enabled, administrators can manually create or edit person cards. Auto-created cards can be enhanced with additional information like avatars, documentation, and relationships.

Testing the OIDC Configuration

After configuring OIDC, test the integration to ensure it works correctly:

Test the connection:

1. Navigate to Admin Panel > Single Sign-On (OIDC)
2. Click Test Connection
3. Review the test results:
   • Success: The configuration is valid and Legend can communicate with your identity provider
   • Failure: The test displays an error message explaining the issue

Test user login:

1. Log out of Legend
2. Click Sign in with OIDC on the login page
3. Authenticate with your identity provider
4. Verify that you’re redirected back to Legend and logged in successfully
5. Check that your user account was created or updated correctly
6. Verify that group memberships were synchronized (if enabled)

Test group synchronization:

1. Add or remove a user from a group in your identity provider
2. Have the user log in to Legend
3. Verify that their Legend group memberships were updated accordingly

Troubleshooting

OIDC login fails:

• Verify the issuer URL is correct and accessible from your Legend instance
• Check that the client ID and client secret are correct
• Ensure the redirect URI is configured correctly in your identity provider
• Review the Legend logs for detailed error messages

Groups not synchronizing:

• Verify the groups claim name matches your identity provider’s configuration
• Check that your identity provider includes group information in the OIDC token
• Ensure the synchronization mode is set correctly (import or force)
• Review the Legend logs for group synchronization errors

Users cannot log in:

• Verify that the user is a member of an allowed group (if allowed groups are configured)
• Check that the user’s account is active in Legend
• Ensure the OIDC configuration is saved and enabled
• Test the OIDC connection to verify the configuration is valid

Person cards not auto-created:

• Verify the auto-create person cards option is enabled
• Check that the OIDC token includes the necessary claims (name, email)
• Ensure the user has logged in at least once through OIDC
• Review the Legend logs for person card creation errors

Best Practices

Security:

• Use HTTPS for your Legend instance to protect OIDC credentials in transit
• Rotate client secrets periodically
• Restrict allowed groups to limit access to authorized users
• Monitor OIDC login attempts for suspicious activity

Group Management:

• Use import mode for most organizations to keep groups synchronized
• Use force mode only when strict enforcement is required
• Use ignore mode when you need independent group management
• Test group synchronization with a few users before enabling it organization-wide

User Experience:

• Enable auto-create person cards to populate organizational data
• Set default groups to provide baseline permissions for new users
• Configure allowed groups to restrict access if needed
• Provide clear documentation to users about how to log in with OIDC

Maintenance:

• Test the OIDC connection periodically to ensure it remains functional
• Monitor Legend logs for OIDC-related errors
• Update the OIDC configuration when your identity provider settings change
• Review group synchronization settings as your organization evolves

Next Steps

After configuring OIDC, proceed to License Management to manage your Legend license, or Audit Logs to monitor authentication activity.