What this integration involves and why it is harder than it looks
The Hyperswitch Control Center signs users in through OpenID Connect only. It does not support SAML, offers no just-in-time or SCIM provisioning, and requires users to be invited into Hyperswitch before they can sign in. Roles are assigned inside Hyperswitch rather than mapped from identity provider groups. Teams expecting the usual enterprise pattern, where the IdP is the single place that grants and removes access, will find that the IdP authenticates people but does not govern what they can do in the dashboard.
This matters most for organizations that must tie dashboard access to a corporate identity provider and a clear audit trail. Payments operations teams that can view transactions, refunds and disputes, and teams preparing for PCI DSS access reviews, usually need to show who had access, when it was granted and when it was removed. Confirm early whether your assessor expects evidence from the IdP, from Hyperswitch, or from both, because the answer determines where the review evidence must come from.
The harder parts are operational. Joiner, mover and leaver steps become manual in Hyperswitch: someone must invite each user, change their role when they move teams, and remove them when they leave, even after the IdP account is disabled. Role drift is likely over time, because nothing automatically reconciles Hyperswitch roles against IdP group membership. Service access through API keys also sits outside SSO, so integrations and automation need their own ownership, rotation and removal process.
Components and settings involved
The SSO integration spans the Control Center dashboard, the Hyperswitch router API, your identity provider and the access model inside Hyperswitch. Confirm exact field names and redirect URI formats against the official SSO guide for your Control Center version before configuring anything.
Control Center dashboard
The Control Center is the merchant dashboard users sign in to for connecting processors and viewing payments, refunds and disputes. It is the browser-facing client of the OIDC flow, so its public URL and the redirect URI registered with your identity provider must match exactly. Check the redirect format in the SSO guide for your version.
Hyperswitch router API
The Rust router serves the API the dashboard calls after sign-in, so SSO depends on it being reachable and correctly configured for the same environment. Confirm which router endpoints and base URLs the Control Center expects in your deployment, and keep dashboard and API hostnames consistent across environments.
Identity provider OIDC application
Your identity provider needs an OpenID Connect client for the Control Center with a registered redirect URI, a client secret or public client setting, the scopes requested and the token claims used to identify the user. Only OIDC is supported, so SAML applications cannot be substituted. Record each setting so it can be reviewed during audits.
Token claims and user matching
The claims in the ID token determine which account Hyperswitch treats as the signed-in user. Confirm which claim carries the email or subject identifier the Control Center expects, and test with a real user from each identity group. A mismatch here typically appears as a login that succeeds at the provider but lands on no Hyperswitch account.
Invitation flow and user provisioning
Hyperswitch does not provision users through JIT or SCIM, so every person must be invited inside Control Center before first sign-in. Plan who sends invitations, how leavers are removed, and how this manual step is recorded for access reviews, since offboarding in the identity provider alone does not remove Hyperswitch access.
Roles managed inside Hyperswitch
Roles are assigned in Hyperswitch rather than mapped from identity provider groups, so group membership in your directory does not grant permissions. Document which Hyperswitch roles correspond to each job function, assign them at invitation, and review them on a schedule. Confirm the current role list in the guide for your version.
API keys used by services
Services that call Hyperswitch use API keys, which sit outside the SSO path entirely. Decide which services need keys, scope them to the least access they need, store them in your secrets manager and set a rotation process. Confirm how keys are created and revoked in your Control Center version, since they are not governed by the identity provider.
Decisions and trade-offs
This table compares the main SSO, break-glass, invitation, role and API key decisions for the Control Center, with the operational work each option leaves to your team.
| Decision and option | When it fits | What it costs operationally |
|---|---|---|
| Workforce IdP as the OIDC provider | Staff already sign in through a corporate IdP with MFA and a joiner and leaver process | Your IdP admins register the client and rotate its secret, and leavers must still be removed in Hyperswitch by hand |
| Dedicated identity service as the OIDC provider | The workforce IdP cannot register a confidential client for internal tools, or payments access must be administered separately | One more identity system to patch, monitor and include in access reviews |
| Local Hyperswitch accounts kept as break-glass | An identity provider outage would otherwise block payments operations staff from the Control Center | Credentials to store and rotate, periodic login tests, and logged use with an alert on every sign-in |
| Central team sends all invitations | Security or platform engineering must control who gets access and when | Invitations queue behind one team, and that team owns the record of who was invited |
| Product or operations teams send their own invitations | Teams change often and each group knows who needs Control Center access | Access drifts unless each invitation has a named owner and a periodic review of active users |
| Roles assigned and reviewed by hand in Hyperswitch | Role mapping from the IdP is not supported, so this is the only option for role assignment | Every role change is a manual edit, and reviews require an exported or recorded list of users and roles |
| Shared API key for several services | A small number of services with one owner and one rotation window | One rotation breaks every consumer, and audit logs cannot show which service made a call |
| Per-service API keys | Each service needs separate revocation, ownership and audit trails | More keys to create, store in a secrets manager and rotate, with a register of which key belongs to which service |
Build sequence
This sequence takes the Control Center from a version-checked OIDC sign-in to a governed set of invited users, owned API keys and a tested leaver procedure.
Confirm Control Center and Hyperswitch versions
The platform team checks the compatibility matrix on the Hyperswitch releases page for the Control Center and web client versions that match the deployed Hyperswitch release. They record the chosen version pair in the change ticket. The step is done when the Control Center version in staging appears in that matrix row and the dashboard loads against the staging Hyperswitch API.
Register an OIDC client in the identity provider
The identity administrator creates an OpenID Connect client for the Control Center and sets the redirect URI and scopes listed in the official SSO guide. The client secret is stored in the organization's secrets manager. The step is done when the identity provider's discovery document loads and the client shows the agreed redirect URI and scopes.
Configure the OIDC connection and test with a pilot
The Hyperswitch administrator enters the issuer, client ID and client secret in the Control Center SSO settings, following the official SSO guide step by step. A pilot user who has already been invited signs in through the identity provider and reaches the dashboard with the expected role. The step is done when the pilot login succeeds and a test account that was never invited is refused.
Define the invitation procedure and role catalog
Security and operations leads document who may send invitations, who approves each access level, and which Hyperswitch roles exist along with what each role can do. Roles are managed inside Hyperswitch, so this catalog becomes the single reference for access levels. The step is done when the catalog is signed off and every role has a named owner.
Invite users and confirm their roles
Authorized administrators invite each user in Hyperswitch before that person first signs in, because the platform has no just-in-time or SCIM provisioning. After signing in, each user's role is checked against the approved catalog. The step is done when every invited user signs in with the expected role and no account holds a role outside the catalog.
Set up API keys and record owners
Each service account receives a Hyperswitch API key, and the access register records its owner, purpose and scope. Keys are stored in a secrets manager and used only by the service they were issued for. The step is done when a test call succeeds with an active key and the same call fails after that key is revoked in a test environment.
Document and rehearse leaver steps
The operations team writes the leaver procedure covering removal of the Hyperswitch user, disabling of the identity provider account and revocation of any API keys the person owned. The procedure names who performs each action and where evidence is kept. The step is done when a test leaver is walked through the procedure and both a rejected login and a failed API call are confirmed.
Access control and secrets handling
These controls decide who can change sign-in settings, who can create payment API keys, and how you prove both over time. Confirm each item against the Control Center version you deploy, because audit event coverage varies by release.
OIDC client secret storage
The OIDC client secret that connects the Control Center to your identity provider should live in a secrets manager or a sealed Kubernetes secret, never in Helm values committed to Git. Check who can read the secret at the cluster and secrets-store level, and record how it is rotated when your identity provider rotates it.
Restricting SSO settings changes
Changes to the OIDC issuer, client ID, redirect URIs and allowed domains alter who can sign in, so limit them to a small named group. Confirm in your version which Control Center role can edit these settings, and require a change record for each edit.
MFA at the identity provider
Because the Control Center relies on OIDC sign-in, multi-factor authentication must be enforced at the identity provider, not in the dashboard. Test that a password-only sign-in is refused for dashboard users and that conditional access policies cover the Control Center application.
Controlled recovery administrative path
Keep at least one local or break-glass administrative account, stored under dual control, so a broken identity provider configuration does not lock every operator out. Document when it may be used, who holds it, and how each use is logged and reviewed afterward.
API key creation rights
Restrict which dashboard roles can create live API keys, since a new key grants direct access to payment operations. Ask whether the Control Center records the creator and timestamp for each key, and confirm that key creation appears in your audit trail.
Least-privilege role assignment
Roles are managed inside Hyperswitch rather than mapped from identity provider groups, so each invited user needs a deliberate role. Review the role matrix against job duties, remove standing access for staff who change teams, and reconcile the dashboard user list with your identity provider each quarter.
API key rotation and revocation runbooks
Write runbooks for scheduled rotation and emergency revocation of each service key, including which services consume it and how they are restarted. Test revocation in a non-production environment so you know that a revoked key stops payment calls before you need it in an incident.
Separating dashboard users from service keys
Human dashboard users and machine service keys have different lifecycles, so do not share one identity or key between them. Give each service its own key scoped to the connector or workflow it needs, and never use a person's account to run automated payment jobs.
Logging invitations, role changes and sign-ins
Assessors typically ask for records of who was invited, who changed a role, and who signed in and when. Confirm which audit events the Control Center exposes in your version, and where identity provider sign-in logs and Hyperswitch application logs are retained if the dashboard does not record them all.
Verification and failure testing
Test the SSO path before any real merchant user depends on it, and test the failure cases as hard as the success cases. For the Control Center, that means running OIDC sign-in once for each Hyperswitch role you plan to grant, confirming that each role lands on the screens and actions it should and no others. Then run denial tests: an identity that was never invited must be refused, and an invited identity that is disabled at the identity provider must be refused on its next sign-in. Because the Control Center has no JIT or SCIM provisioning, the invitation list is the control, so check it against the identity provider's user list during the test.
Failure cases matter more. Test what happens when the identity provider is unreachable, when a session expires, and when a session is revoked at the IdP. Confirm the Control Center fails closed for new sign-ins and that existing sessions end within the lifetime you configured. Remove a test user at the IdP while their Hyperswitch account still exists, then confirm they cannot sign in and that the orphaned account is handled under your offboarding procedure. Revoke a service's API key and confirm calls using it fail, and check that the key is not accepted from cached credentials in downstream services.
Check the version after every upgrade. Compare the deployed Control Center and web client versions with the compatibility matrix published on the Hyperswitch releases page for that release, and rerun the SSO sign-in tests. Confirm the break-glass administrator account can sign in with the identity provider unavailable. Keep that account's credentials sealed, test it on a schedule, and record each test. Confirm which login method it uses, since SAML is not supported and OIDC depends on the provider.
Record every result as evidence: test ID, date, tester, Control Center and component versions, identity provider configuration reference, expected result, observed result and a link to logs or screenshots. Store records in the same system as your change tickets so reviewers can trace a control to a test run. Ask your assessor or internal audit team which evidence format they accept before the first test cycle.
Effort drivers and how to keep them down
This table lists the factors that change effort for Control Center SSO and identity work, how to reduce each one, and what to ask a partner to estimate.
| Driver | Why it changes effort | How to keep it down |
|---|---|---|
| Number of users and roles | Each user needs an invitation and a Hyperswitch role, and every role combination adds review and test work. | Define a small role catalog in Hyperswitch up front, map job functions to those roles, and keep exceptions documented. Ask the partner to estimate effort per role, not per user. |
| Environments needing separate OIDC clients | Sandbox, staging and production each need their own client registration, redirect URIs and test sign-ins, so setup and troubleshooting repeat per environment. | Use one standard OIDC client pattern with identical claim and redirect configuration in every environment, changing only hostnames and secrets. Ask the partner how many clients the quote assumes. |
| Identity provider complexity and governance | Existing group structures, MFA policies, conditional access and approval workflows must be understood before the OIDC integration can be designed and tested. | Confirm with the identity team which groups and policies apply to Control Center before build starts. Ask the partner to scope discovery and identify which provider settings they expect to change. |
| Services using API keys | Each service that calls Hyperswitch with an API key needs its own key, storage location, rotation process and owner, and each adds handling work. | Inventory services that need keys, issue one key per service with a named owner, and store them in your secrets platform. Ask the partner to estimate the rotation procedure and its testing. |
| Volume of manual invitations and role changes | Because Control Center has no JIT or SCIM provisioning, every joiner, mover and leaver is a manual action in Hyperswitch, and volume drives ongoing effort. | Assign one invitation owner, use a written request form with approval, and batch changes on a fixed schedule. Ask the partner what runbook and handover they include. |
| Evidence of access reviews | Assessors and internal audit may ask for periodic proof of who holds which Hyperswitch role, which requires exporting or recording data from the Control Center. | Where the Control Center exposes user and role data, script a periodic export and store the results with reviewer sign-off. Confirm with the vendor which data is available through the interface or API before designing the review. |
Frequently asked questions
Can I add SAML or SCIM provisioning to the Hyperswitch Control Center?
No. The Control Center supports single sign-on through OpenID Connect only, so SAML is not supported, and it has no just-in-time or SCIM provisioning. Plan manual processes for those gaps: users must be invited before they can sign in, a named owner sends every invitation, and a written offboarding checklist removes access when people leave. Roles are managed in Hyperswitch and are not mapped from your identity provider, so role changes also need a manual step. Confirm current behavior in the Control Center documentation before you commit to a design.
What drives the effort and cost of Control Center SSO integration?
The main drivers are user count, role design, environment count and governance. Each user needs an invitation and a role, so a large or frequently changing group adds ongoing administration. Roles must be decided early because they are set in Hyperswitch and are not mapped from the identity provider. Each environment, such as sandbox, staging and production, usually needs its own OIDC application registration and redirect settings. Governance adds approval steps, access reviews and offboarding procedures. Ask any quote to list these items separately and to show which work is one-time setup and which is recurring administration.
Can our internal team set up Control Center SSO without a partner?
Yes, if your team has working experience with OpenID Connect, administrator access to the identity provider, and enough Hyperswitch administration experience to manage invitations and roles. Start with the setup guide in a test environment, then confirm sign-in, invitation and role behavior with test accounts before changing production. Teams without OIDC experience, or without anyone who can change the identity provider's application settings, should plan for outside help. Whether that help is worth it depends on the number of environments and the approval steps your organization requires before production changes.
How long does Control Center SSO integration take to complete?
The duration depends mainly on how quickly your identity provider administrators can create the application and how many approvals your organization requires before production changes. Environment count, test cycles and the number of role decisions also add time. No single duration applies to every setup, so ask for a timeline in the written scope. The scope should list the environments, the identity provider, the approval steps and the test steps, and it should name dependencies outside the project team, such as change windows and account requests.
What does the SSO integration need from our team?
The work needs four things from your side. First, administrator access to the identity provider to register the OIDC application and set redirect addresses. Second, a named owner who approves and sends every invitation, since users must be invited before they can sign in. Third, decisions on which Hyperswitch roles each group should hold. Fourth, test accounts in each environment that cover the roles you plan to grant. Without these, testing stalls and access requests pile up, so agree on owners in writing before the work starts.
How should service API keys be handled alongside Control Center SSO?
Keep service API keys separate from SSO. Single sign-on covers people signing in to the Control Center, while each service needs its own credential. Create one key per service, store it in your secrets manager instead of in code or configuration files, limit it to the access the service needs, and record a named owner. Set a rotation schedule and test the rotation before you need it. Check the Hyperswitch documentation for how keys are created, scoped and revoked in your version, because these controls can change between releases.
How DeployOpen scopes, builds and hands over this work
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks. For Hyperswitch Control Center SSO and identity integration, the work starts with a written scope that fixes what your identity provider, Control Center users and service API keys will look like before any configuration changes.
How we scope
- Confirm your OIDC identity provider, its supported flows and the claims Control Center will receive at sign-in.
- Document the invite-first user model, who may invite users and how Hyperswitch roles are assigned by hand.
- Agree in writing which service accounts and API keys are in scope, and who owns their rotation after go-live.
How we build
- Configure the OIDC client, redirect URIs and Control Center SSO settings in a non-production environment first.
- Test sign-in, sign-out, session expiry and denied-access paths with pilot users before wider rollout.
- Define a repeatable process for adding users, changing roles and removing leavers, since no SCIM or JIT provisioning is available.
How we hand over
- Provide runbooks for SSO configuration, user invitations, role changes and identity provider certificate or secret rotation.
- Walk your administrators through the access review steps they will repeat on a schedule.
- Record configuration, decisions and open items so your team can reproduce the setup or audit it later.
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, including checks after Control Center version changes.
- Ask for a written quote tied to this scope so each item, and who carries it, is clear before you commit.
