OpenMetadata SSO and identity integration guide

How OpenMetadata SSO changes login, access and ownership

Switching OpenMetadata from local accounts to your corporate identity provider changes three things at once: who can sign in, which roles they receive, and which teams they can be assigned to as owners. Treat the move as a planned cutover, not a settings change. OpenMetadata does not support combining SSO with basic authentication, so there is no period where both work side by side. Users who sign in with local passwords will need to sign in through the identity provider from the cutover date, and any integration or script that depends on a local login must be moved first.

OpenMetadata's security documentation lists SSO support for Auth0, Azure, Google, Okta, Amazon Cognito, OneLogin, Keycloak and custom OIDC providers. The choice of provider sets the configuration steps, but the harder questions are the same across all of them. Confirm with your identity team which group or claim the provider will send for each role you need, how those groups are named, and whether they are issued in the token or must be fetched separately. Ask the same question for every team that will own catalog assets. A mapping that works for a pilot group often breaks when it meets nested groups, renamed groups or users who belong to several teams.

Ingestion is the most common place where a clean SSO design fails. Connectors that pull metadata from warehouses, BI tools and pipelines typically authenticate as a bot account, not as a person. Decide before cutover which bot identities will exist, which roles they hold, and how their tokens are issued and rotated. Do not let a bot account depend on a human user who may leave the company. Test every scheduled ingestion run after the switch, because a bot that cannot authenticate will stop metadata updates silently until someone notices stale tables.

Existing users are the third risk. Ownership, comments and tasks in OpenMetadata are tied to user records, so the switch must preserve the link between an established account and the identity that now signs in to it. Before cutover, export a list of current owners and stewards, confirm the email address or identifier each one will use in the identity provider, and agree how orphaned ownership will be reassigned. Run a pilot with a small set of real owners and check that their assets, permissions and history look right before you open the catalog to wider rollout. Your identity team and the catalog owners should sign off on this list together.

Which identity components you configure

SSO for OpenMetadata touches several systems that must agree on the same identities. The cards below list each component you configure, where it lives, and what to check so that sign-in, group membership and automation keep working after you switch off basic authentication.

Identity provider application

In your identity provider, you register OpenMetadata as an OIDC client application. This registration issues the client identifier and client secret that the OpenMetadata server uses during sign-in, and it defines which users and groups may access the application. Confirm the provider type matches your chosen integration (Okta, Azure, Google, Keycloak or a custom OIDC provider) before you create the registration, because the required fields differ between them.

Client registration and secrets

The client registration fixes the grant type, the allowed scopes and the client authentication method that OpenMetadata will use. Record where the client secret is stored and who can read it, and plan a rotation date before go-live. Ask your identity team whether the provider can issue a confidential client with a secret or requires a different authentication method for your environment.

OIDC settings on the OpenMetadata server

The OpenMetadata server configuration holds the authentication provider type, the issuer or discovery endpoint, the client identifier, the expected audience and the scopes it requests. These values must match the identity provider exactly, including trailing slashes and tenant identifiers. Review them in the server configuration for each environment, not only in production.

Redirect and callback URLs

The callback URL registered with the identity provider must match the address that users reach OpenMetadata at, including scheme, host, port and path. A mismatch is one of the most common causes of failed sign-in after setup. Register a callback for each environment you run, such as test and production, and remove unused entries so that stale addresses cannot receive tokens.

Identity and group claims

Token claims carry the user's identity, usually an email address or username, and the group or role membership that OpenMetadata uses for team and role mapping. Decide which claim is the unique user identifier and which claim lists groups, then confirm with a test user that both appear in the issued token. Claim names differ across providers, so check them against your provider's token preview before configuring the mapping.

OpenMetadata users, teams and roles

OpenMetadata stores its own user, team and role records, and SSO sign-in links an identity to one of these records. Plan which provider groups become teams, which teams own data domains and glossaries, and which roles grant administrative or steward rights. Review who holds admin rights before you disable basic authentication, since that path is the usual fallback when SSO misbehaves.

Bot accounts for automation

Ingestion pipelines and API scripts authenticate as bot accounts rather than as people, so they do not depend on an interactive sign-in. Identify each bot your connectors and automation need, assign it the narrowest role that works, and document which system uses it. Token handling and connector credentials are covered in the security hardening topic, so this card only covers which bot accounts you create and what each one can reach.

Which identity path fits your estate

This table compares the main identity decisions for OpenMetadata SSO: connecting directly to your identity provider or brokering through Keycloak, managing groups in the provider or in OpenMetadata, and cutting over in one step or group by group. Read each row for when the option fits and what it adds to daily operations. Confirm the supported provider list and token and scope requirements with the vendor and OpenMetadata's security documentation before choosing.

Decision	Direct to identity provider	Brokered through Keycloak
Best fit	Estate already runs a supported provider such as Okta, Azure, Google or Auth0	Several providers, or a provider OpenMetadata does not list, feeding one realm
Components to run	No extra identity component; OpenMetadata connects to the provider's OIDC endpoints	An extra Keycloak service to patch, back up, scale and monitor alongside OpenMetadata
Group and role mapping	Groups are maintained in the provider and mapped to OpenMetadata teams and roles	Groups are maintained in Keycloak, which must be kept in sync with the upstream provider
Operational upkeep	Changes to group claims in the provider must be verified against OpenMetadata roles	Two identity layers to troubleshoot when a login or claim mapping fails
Cutover to SSO	Single cutover is practical when all users share one provider	Staged moves are easier to run per realm or per group during transition
Custom OIDC provider	Viable if the provider meets OpenMetadata's OIDC requirements; confirm claims and scopes	Viable when Keycloak can federate the custom provider and normalize its claims
Basic authentication	Disable basic login once SSO is verified, since OpenMetadata does not run SSO and basic auth together	Same constraint applies; plan the switch-off date with the bot and admin accounts in mind

How to configure OpenMetadata SSO step by step

This sequence moves OpenMetadata from basic authentication to single sign-on in controlled stages. Each step ends with a check, so the team knows the login path, identity mapping and service access work before basic authentication is switched off.

Register the application in the identity provider
The identity team creates an OpenMetadata application in Okta, Azure, Google, Keycloak or your custom OIDC provider, using the non-production instance URL. They register the redirect URIs exactly as the current OpenMetadata security documentation for your version requires, including scheme, host, port and callback path. Confirm the grant type and client settings against the same documentation. Store the client secret in your secrets manager, not in configuration files. Done when the application appears in the provider, the client ID is recorded, and a test sign-in attempt reaches the provider's login page without a redirect error.
Agree the claim names for email and groups
Platform and identity engineers agree which claim carries the user's email address and which carries group membership. Confirm the exact claim names the provider emits in the ID token, and check whether group claims need an additional scope or a provider-side mapping before they appear. Record the agreed names in the configuration record so the OpenMetadata settings and the provider settings match. Done when a test user's token, inspected with a standard decoding tool, shows the email and group claims in the expected format.
Set the OIDC configuration on a non-production instance
The platform team enters the OIDC settings on a non-production OpenMetadata server: provider type, client ID, issuer or discovery endpoint, and the claim settings agreed in the previous step. Configuration keys differ between versions, so confirm each key name in the current OpenMetadata security documentation for the version you run before setting it. Keep the client secret in your secrets store and reference it, rather than typing it into a values file. Done when the server restarts cleanly, the sign-in page offers the SSO option, and the change is saved as a reviewed diff.
Sign in with a pilot group and confirm user records
Choose a small pilot group of named users that includes at least one administrator and one standard user. Each pilot user signs in through SSO and completes a full session, including sign-out and a second sign-in. Afterward, the platform team checks each user record: email, display name, group values and assigned roles should match the provider. Confirm that no one receives administrator rights by default. Done when every pilot user signs in successfully and a written table lists each user with the expected role next to the role actually assigned.
Map identity groups to teams and roles
Working with data owners, the team maps provider groups to OpenMetadata teams and roles according to the agreed ownership model. Grant the narrowest role that supports each job, and keep administrative roles to a named list. Confirm the mapping in the current documentation, since group handling depends on the version and the provider. Test one user who is outside every mapped group to confirm they cannot reach owned assets. Done when pilot users land in the correct teams, the out-of-group test user is denied, and the mapping table is signed off by the data owners.
Document the bot account used by ingestion
Ingestion pipelines authenticate with a bot account and token, which SSO does not replace for scheduled work. Document the bot's owner, purpose, the connectors and pipelines that use it, where its token is stored, and the steps to rotate it. Confirm with the current OpenMetadata security documentation how the bot authenticates once SSO is active, and test that behavior on the non-production instance. Done when the runbook entry is complete and a scheduled ingestion run completes successfully using the bot credentials on the non-production instance.
Set the cutover date and disable basic authentication
The steering group sets a cutover date and communicates it to pilot users, data owners and pipeline owners. Before the date, the production redirect URIs are registered, and the SSO sign-in path is tested on production with the pilot group. Basic authentication is disabled only after that path is proven, since OpenMetadata does not support combining SSO and basic authentication at the same time. Confirm the break-glass procedure before the switch. Done when a production SSO sign-in succeeds, the basic login path is shown as disabled, and the approver has signed the cutover record.
Record the configuration as code and in a change log
The platform team stores the OIDC settings, claim names, group mappings and bot account documentation in version control, with secrets referenced from the secrets manager instead of stored in the repository. Each later change, such as a new group, a rotated client secret or a version upgrade, goes through a change log entry that names the approver. Confirm the configuration can be reapplied to a fresh non-production instance. Done when the repository holds the reviewed configuration, the change log has the cutover entry, and a test rebuild of the non-production instance produces the same login behavior.

What drives SSO effort and cost

This table lists the factors that raise or lower the effort of connecting OpenMetadata to an identity provider, with the one-time and recurring costs each one creates. Read each row as a lever: the cost column names what to fix early, and the reduction column names what to agree before configuration starts. The main takeaway is that naming and group decisions made at the start of the project cost far less than changing them after users and bots are already mapped.

Driver	How it raises effort or cost	How to keep it down	One-time or recurring
Identity providers and tenants	Each provider or tenant needs its own OIDC client, redirect settings, claim checks and login testing. Multiple tenants multiply that work.	Confirm the number of providers and tenants in writing before scoping. Consolidate where the business allows.	One-time, with recurring testing when a tenant changes
User population and group model	Large or nested groups make claim mapping and role assignment harder to verify. Groups that exist only in the directory add mapping rules.	Use a small set of groups that map to OpenMetadata roles. Remove unused or duplicate groups before mapping starts.	One-time mapping, recurring group changes
Team ownership mapping	Every team that owns domains, glossary terms or data assets needs an agreed mapping from its directory group to an OpenMetadata team or owner.	Agree the team list and owner of each domain with data stewards before configuration. Keep ownership separate from access roles where possible.	One-time mapping, recurring on reorganization
Broker such as Keycloak	Adding a broker adds a second identity layer to configure, secure, back up and upgrade. Claim translation between broker and upstream provider needs testing.	Connect OpenMetadata directly to the provider when the provider supports OIDC well. Add a broker only for a clear federation need.	One-time build, recurring broker upgrades and maintenance
Number of environments	Development, test and production each need their own redirect URIs, client secrets and mapping checks. Drift between environments causes login failures.	Keep one configuration template and vary only URLs and secrets. Test the same login flows in each environment.	One-time per environment, recurring on each release
Ingestion and API bot accounts	Each pipeline or integration uses a bot identity with its own token and role. Without a plan, bots end up sharing personal logins or long-lived tokens.	Create one bot per integration with the narrowest role. Record owners and token rotation dates in the register.	One-time setup, recurring token rotation and review
Compliance evidence to keep	The identity team must show who can sign in, how roles are granted, how basic authentication was disabled and how changes were approved. Gathering this late takes extra effort.	Define the evidence list at the start, such as configuration exports, test results and access review records. Collect it as each step is completed.	One-time setup, recurring access reviews and evidence refresh
Upgrade regression of login	Each OpenMetadata release can change authentication behavior or configuration keys. Login, token and role checks must be repeated before each upgrade reaches production.	Keep an automated or scripted login test set covering each identity flow and each bot. Ask the team to confirm the release notes for auth changes.	Recurring with each upgrade cycle

How SSO differs by deployment model

On bare metal, OpenMetadata runs as a service on hosts you manage. The callback URL resolves through whatever reverse proxy or load balancer you place in front of the server, so the public HTTPS address users see must match the redirect URI you register with your identity provider. OIDC settings live in the server configuration on the host, and a change takes effect after the service restarts.

Key points for this model:

Prerequisites: Java 21, MySQL 8.0.42 or later or PostgreSQL 15 or later, and Elasticsearch 9.x or OpenSearch 3.x.
Callback URL: register the external HTTPS address of your proxy, not the internal host name of the server.
Settings: edit the configuration files under change control, and record who changed them and when.
Restarts: restarting the server process ends active sessions, so users sign in again once it returns. Confirm session handling for your version in the security documentation.
Single host: without redundancy, a restart is a full outage for every user.

Before choosing a proxy, confirm the ingress and TLS requirements for your chosen identity provider, including certificate chain trust and any required redirect rules.

How to test that OpenMetadata SSO works and fails safely

Before you switch OpenMetadata to single sign-on, write a test set that proves the identity integration grants the right access and removes it when it should. The minimum set covers five checks. First, a successful login for at least one user from each pilot group, confirming the identity provider returns the claims OpenMetadata expects and the user lands in the workspace. Second, a denied login for a user outside the permitted groups, so you know access is limited by group membership and not by the mere existence of an account at your identity provider. Third, confirmation that a removed user loses access, tested by disabling a test account in the identity provider and attempting a fresh login and an existing session. Record how long the existing session survives, because that is the window your offboarding process has to account for.

The fourth and fifth checks test the mapping and the data. On first login, confirm the role and team assignments match the mapping you agreed with your data owners, using a user from each mapped group. Mismatches usually come from group claim names, group ID formats or claims that are only sent for some token types, so compare the identity provider's token contents with what OpenMetadata shows on the user profile. Then check ownership on existing assets. Pick a sample of tables, dashboards and glossary terms owned by people before the switch and confirm the owner still resolves to the correct user account after cutover. A user who was re-created with a new identifier can leave assets pointing at a stale or empty owner, which breaks stewardship workflows without any visible error.

The failure test matters as much as the success test. OpenMetadata does not support combining SSO with basic authentication, so once you switch, the local login path is gone for normal users. Confirm that basic login is disabled after cutover by attempting it with a known local account and recording the result. Then confirm you have a recovery path that works without the normal login. Decide in advance who can perform recovery, where the procedure is stored, and how credentials for an administrative account are held outside the SSO flow. Rehearse that path on a non-production instance before the switch, and confirm it still works after your identity provider changes, such as a certificate rotation or a new client secret. Ask your OpenMetadata vendor or implementation partner to confirm the supported recovery steps for your deployment version, because the exact procedure depends on how authentication is configured.

Record every test as evidence. For each check, capture the test date, the tester, the account or group used, the expected result, the actual result and a reference to the screenshot, log line or token inspection output. Keep the failed attempts too, since they show the controls worked. Store the record with your change ticket so an auditor or internal reviewer can trace the access decision back to a tested outcome. Re-run the full set after any identity provider change, OpenMetadata upgrade or group restructuring, because each of these can change claims, mappings or session behavior without changing the login page.

Keeping OpenMetadata SSO scoped to identity controls

These controls limit who can sign in to OpenMetadata, who can change how sign-in works, and how long access lasts after someone leaves a team. They sit at the boundary between your identity provider and OpenMetadata, so they can be reviewed without reading the wider hardening plan. Wider hardening is covered in the security hardening topic.

Restrict the provider application to needed groups

In the identity provider, assign the OpenMetadata application only to the groups that need catalog access, rather than to every user in the tenant. Confirm how your provider handles unassigned users who attempt sign-in, and whether it blocks them before a token is issued. Record which groups are assigned and who approved each one, so the assignment can be reviewed later.

Validate audience and signing settings

Check that the tokens OpenMetadata accepts were issued for its own client ID and expected audience, and that the signing keys and issuer URL match the values your provider publishes. Confirm these settings in the OpenMetadata security configuration after every provider change, including key rotation. A mismatch here is a common cause of sign-in failures that teams sometimes fix by loosening validation, which should not happen.

Store the client secret in your secret manager

Keep the OIDC client secret in the secret manager your team already operates, and have the OpenMetadata deployment read it at runtime instead of writing it into configuration files or Helm values. Confirm who can read the secret, how it rotates, and what happens to sign-in when rotation occurs. Verify that the secret does not appear in logs, ingestion configurations or version-controlled manifests.

Limit who can change SSO settings

Identify which OpenMetadata roles can view or edit authentication configuration, and restrict that permission to a small named group of platform administrators. Changes to the provider, issuer or allowed domains alter who can sign in, so they should follow the same change control as other identity changes. Test the restriction with an ordinary data steward account to confirm it cannot reach these settings.

Review group membership on a schedule

Set a recurring review, at an interval your security policy defines, that compares the members of the groups mapped to OpenMetadata teams and roles against current HR records. Remove access for leavers and for people who changed roles, and check that team ownership in the catalog still matches the groups. Keep the review record as evidence for access reviews.

What to monitor, keep and re-test after SSO goes live

Once OpenMetadata is behind SSO and basic authentication is switched off, the work shifts from building the integration to keeping it working. Monitor three things continuously: failed logins, group sync problems and the expiry dates of credentials held at the identity provider. Failed logins usually show up first as a spike of users who cannot reach the portal, so review the OpenMetadata server logs and your identity provider's sign-in logs side by side. Group sync problems are quieter. If a group membership change in Okta, Azure, Google, Keycloak or your custom OIDC provider no longer reaches OpenMetadata, a user keeps the access they had before, or loses access they need. Check a sample of known users after each directory change.

Client secrets and signing certificates at the identity provider expire on dates that nobody remembers unless someone records them. Put each expiry date in your calendar or ticketing system with an owner, and plan the rotation window before the date arrives. Confirm with your identity provider how it notifies administrators of expiring secrets and whether that notice goes to a shared mailbox that someone reads. An expired secret typically locks every user out at once, and the bot accounts used for ingestion may fail silently in the background, so check their token status as part of the same review.

Three artifacts need to be backed up so the integration can be rebuilt without guesswork: the exported identity configuration, the group-to-role mapping and the inventory of bot accounts and their associated tokens. Store the identity configuration export and the mapping in version control or a controlled repository, not on an administrator's workstation. Record which bot accounts exist, which connector or automation uses each one and who owns it. Do not store secret values in the inventory. Record where each secret is held and when it was last rotated. Test a restore in a non-production environment at least once, because a backup that has never been restored is an assumption.

Re-test after every OpenMetadata upgrade, because login behavior can change between releases. Before upgrading, read the OpenMetadata 2.0 release notes for breaking changes that touch authentication, ingestion credentials or configuration blocks, and handle those in a staging copy first. Confirm the current release line on the OpenMetadata releases page before you schedule the upgrade, since maintenance releases arrive frequently. The regression set should cover SSO sign-in for each identity provider you use, group-to-role assignment for a test user in each group, that basic authentication remains disabled, bot token access for ingestion, and logout and session expiry behavior.

Hand over four documents with the integration. The configuration record lists the identity provider, client registration settings, redirect URLs, the OpenMetadata authentication settings and the owner of each. The mapping table lists each identity provider group, the OpenMetadata role or team it maps to and the approver for changes. The recovery procedure describes how to restore sign-in if the identity provider is unavailable or a secret expires, including who can make the change and how to confirm access afterward. The test evidence records each regression run, the release tested, the date and the results. Ask your implementation partner to list these deliverables in the written scope so that acceptance is measurable.

What does OpenMetadata SSO integration cost and take?

What drives the cost of an OpenMetadata SSO integration?

The cost is driven mainly by how many identity providers, environments and user populations are involved, and by how much the identity team and data owners must be engaged. Most of the work is configuration, testing and coordination rather than custom code, but each identity provider (Okta, Azure, Google, Keycloak or a custom OIDC provider) has its own app registration, claim mapping and group rules. Costs also rise if you need team and role mapping to ownership, staged rollout across environments, or a rollback plan. A written scope should list each provider, each environment, the group or claim mapping rules, and the testing expected before cutover. Ask any partner to separate one-time setup from any recurring support or retainer.

Can our own team implement OpenMetadata SSO without outside help?

Yes, if you have engineers who can administer your identity provider and operate OpenMetadata's server configuration, and enough time to test it properly. OpenMetadata documents SSO support for Auth0, Azure, Google, Okta, Amazon Cognito, OneLogin, Keycloak and custom OIDC providers, so the pattern is well documented. The usual risk is not the configuration itself but the edge cases: group claims that do not match expected roles, users locked out during cutover, service accounts and bots that need their own access path, and a rollback plan that works. An internal team should be honest about whether it has someone who can own those decisions after go-live.

What does the identity team need to provide for the integration?

The identity team typically owns the application registration with your provider, the redirect and callback settings, the claims or groups that carry user identity and roles, and the decision on which users and groups can sign in. Expect to share the target OpenMetadata URL for each environment, the claim names and group structure, and the account that will be used for administrative recovery. You should also agree on session lifetimes, multi-factor requirements and who approves changes to the mapping. Confirm these needs with your identity team early, because waiting for group design or application approvals is a common source of delay.

What do data owners need to do during an SSO rollout?

Data owners need to confirm which teams and domains should map to which owners, and who is accountable for approving access changes after sign-in works. OpenMetadata ownership is only useful if the people listed as owners recognize their responsibilities and can be reached. Before cutover, ask the owners of key domains to review the team and role mapping, and to confirm that the users they expect can see and edit the right assets. This review is often the slowest part of the work because it depends on people outside IT, so schedule it early in the plan.

Can basic authentication stay enabled while we roll out SSO?

No. OpenMetadata does not support using multiple authentication mechanisms at once, such as combining SSO and basic authentication, according to its security documentation. That means you cannot keep email and password login available as a fallback during the SSO rollout on the same deployment. Plan the cutover so that you have a documented way to recover administrative access if SSO fails, such as a break-glass procedure agreed with your security team. Test that procedure in a non-production environment before you switch production over.

How long does an OpenMetadata SSO integration take?

The timeline depends on the drivers rather than a fixed number: the identity provider and how quickly its application registration can be approved, how many environments need configuring, how complex the group and role mapping is, and how many user populations must be tested. Organizations with a single provider, clear groups and a non-production environment already running usually finish faster than those that must redesign group structures or coordinate multiple identity sources. Ask for a timeline in the written scope that lists the approval steps, testing phases and cutover window, and identify which steps depend on people outside the project.

What should we ask for in a written quote for SSO integration?

Ask the quote to state the scope in concrete terms: the identity provider and version you are integrating, the number of environments, the group and claim mapping rules, the teams and owners involved, and the testing and cutover plan. It should list the deliverables, such as configuration documentation, test results, a break-glass procedure and handover notes. Confirm what is excluded, what assumptions the timeline depends on, who is responsible for each dependency, and how changes to scope are priced. Ask whether any ongoing support or upgrades are included or offered separately as a retainer.

How DeployOpen works on this

DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside the client's own infrastructure. For OpenMetadata SSO, that means agreeing a written scope for the identity provider, the login path and the team-to-role mapping before any configuration changes, then delivering and documenting the result in your environment.

How we scope

Confirm which identity provider you use, such as Okta, Azure, Google, Keycloak or a custom OIDC provider
Record where OpenMetadata is deployed and which users and bots need access during cutover
Agree in writing how basic authentication will be retired and who approves the switch-off date
Define how teams and roles from your directory map to OpenMetadata ownership and access

How we build

Configure the OpenMetadata authentication settings against your identity provider in a non-production environment first
Test sign-in, token renewal, logout and role assignment with named test accounts from each team
Verify that service accounts and ingestion bots keep working without relying on interactive login
Apply the agreed changes to production only after the test results are reviewed with your team

How we hand over

Deliver a written record of the identity provider settings, redirect addresses and claim mappings used
Document the group-to-role mapping, including who owns each rule and how exceptions are requested
Provide a runbook covering provider certificate or secret rotation and a basic authentication rollback check
Walk your platform and security staff through the configuration and the verification steps

How we support

Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts
Ongoing support, upgrades and continuous testing are available as a retainer
Review SSO settings when OpenMetadata releases change authentication behavior or your identity provider changes
Confirm the current support options and release timing with DeployOpen before planning a version change

OpenMetadata SSO and identity integration