Apache APISIX SSO and identity integration starts with who calls each API
Many organizations run APIs that trust each service or application differently. Some check a token issued by a central identity provider, some accept a static API key, some call a directory bind, and some rely on network position. Identity ends up handled in several places, and no single person can say which caller is allowed on which route. SSO on Apache APISIX means the gateway validates identity from your provider before traffic reaches upstreams, so the upstream services receive requests that have already been authenticated against one agreed source. Before choosing any plugin, list every caller type your APIs serve: people signing in through a browser or app, backend services calling each other, partners, scripts and batch jobs.
The openid-connect plugin is the usual choice for interactive users and for clients that obtain tokens from an OpenID Connect provider such as Keycloak, Auth0, Microsoft Entra ID, Google or Okta. The APISIX documentation describes support for authorization code, client credentials, token introspection and PKCE flows, but the exact options differ by release. Token introspection is the path to consider for machine clients and opaque tokens, where the gateway asks the provider whether a token is active instead of verifying a signature locally. The jwt-auth plugin suits callers that present self-issued or pre-shared signed tokens, key-auth fits simple consumer keys for partners or internal tools, and ldap-auth covers applications that still authenticate against a directory. Each of these answers a different question about the caller, so mixing them is a design decision, not a default.
The harder part is mapping an authenticated identity to an APISIX consumer and keeping policy consistent across routes. A token that proves who the caller is does not, by itself, say which routes, rate limits or upstream headers that caller should receive. You need a rule for how claims, client IDs or directory groups become consumers, and a single place where that mapping is maintained. Decide whether each route declares its own authentication plugin or whether shared plugin configuration is applied through groups or templates, and confirm how your chosen release handles conflicts when a route has more than one authentication plugin. Inconsistent choices here are the most common reason two APIs owned by the same team behave differently for the same user.
Before you rely on any of these flows, confirm the plugin names, configuration fields, supported providers and introspection behavior against the APISIX documentation for the release line you intend to run. The current release listed on the downloads page is 3.19.0, but the page does not mark any release as long-term support, so your upgrade policy should be settled before you commit to a version. The plugin behavior described here comes from the APISIX documentation, including the openid-connect plugin reference, and should be checked against your identity provider's own settings for redirect URIs, client types, token lifetimes and scopes.
Which APISIX components and plugins handle identity
Identity in Apache APISIX is spread across a few plugins and two configuration surfaces, and each one validates something different. The cards below separate the authentication plugins from the places where routes and plugin settings are defined, so you can choose the components that match your identity provider and your client types. Confirm each plugin against the APISIX version you plan to run before you design around it.
The openid-connect plugin
The openid-connect plugin is the main route to an OpenID Connect identity provider such as Keycloak, Auth0, Microsoft Entra ID, Google or Okta. It supports authorization code and PKCE flows for browser and user-facing clients, client credentials for service callers, and token introspection for opaque tokens. It validates tokens against the provider's configuration, but it does not manage users, issue tokens or replace the provider's session and consent logic. Check the provider-specific settings against the plugin documentation for your version.
The jwt-auth plugin
The jwt-auth plugin checks JSON Web Tokens that carry a key identifier matched to a consumer defined in APISIX. It validates the signature and the consumer binding at the gateway, which suits tokens issued by a system you already trust. It does not perform the interactive login, and it does not check revocation or token state by itself. Confirm which signing algorithms and claim checks your version supports before you rely on it for a given token format.
The key-auth and basic-auth plugins
The key-auth and basic-auth plugins authenticate callers with a static API key or a username and password stored against a consumer. They are simple to operate for machine clients and legacy integrations, but they validate only possession of a secret, not a user's identity or current authorization. Secrets must be rotated and stored outside route definitions, and transport security must be in place because these credentials travel with each request. Plan key issuance and rotation before go-live.
The ldap-auth plugin
The ldap-auth plugin checks HTTP Basic credentials against an LDAP directory, which can be useful where applications must keep using directory accounts. It validates that the bind succeeds for the supplied user, but it does not evaluate group membership or attributes for authorization unless you build that logic elsewhere. Confirm the directory connection security, bind account handling and failure behavior with your directory team and the plugin documentation for your version.
SAML and multi-auth
APISIX documents a SAML plugin and a multi-auth plugin. Multi-auth lets a route accept several authentication plugins in sequence, which helps when browser users and machine clients reach the same API. SAML is relevant where your identity provider speaks SAML rather than OpenID Connect. Before you choose either, confirm that the SAML plugin is present and supported in your chosen release, and test how multi-auth orders and reports failures, because a permissive ordering can widen access.
Admin API and client listener
In traditional mode, the Admin API on port 9180 is where routes, consumers and plugin settings are created, and the client listener on port 9080 is where API traffic is served. Authentication configuration lives in those definitions, so access to the Admin API controls which identity rules apply. Restrict the Admin API to administrators and automation, change default keys, and confirm the listener ports and TLS settings in your environment before you map identity rules to routes.
Which identity method fits each caller and what it costs to run
This table maps each type of caller to the identity method that usually fits it on Apache APISIX, and notes the ongoing cost of running that method. Read each row for when the method applies and what your team must keep operating after go-live. The main takeaway is that every extra method adds a second identity path to test, rotate and monitor, so keep the number of methods as small as your callers allow.
| Caller or decision | When it fits | Operational cost to run |
|---|---|---|
| Browser users | Staff or customers signing in through a web application, using the openid-connect plugin with authorization code and PKCE flows against your identity provider | Session and refresh token lifetimes must be set and reviewed, redirect URIs and client secrets need rotation, and the identity provider becomes a runtime dependency for every new login |
| Machine clients with client credentials | Backend services or scheduled jobs that call APIs without a user, obtaining tokens from the identity provider with the client credentials flow | Client secrets or certificates need a rotation schedule, token expiry drives request volume to the identity provider, and each client needs an owner for revocation |
| Third-party callers | Partners or external developers who need API access under a contract, usually issued tokens or consumer credentials that map to a consumer record | Onboarding and offboarding are manual unless automated, scopes must be reviewed as partners change, and you must confirm which token format and claims each partner expects |
| Service accounts that need LDAP | Legacy internal applications that authenticate against a directory through the ldap-auth plugin because they cannot use OIDC | Directory availability and bind account credentials become gateway dependencies, LDAP connectivity and TLS settings need testing, and the directory team must agree on account lifecycle |
| Legacy callers using static keys | Older clients that send a fixed key through key-auth and cannot be changed in the short term | Keys are long-lived unless you rotate them, leaked keys are hard to trace without per-consumer logging, and every key is a separate credential to inventory and retire |
| Introspection at the gateway | Opaque or reference tokens where the gateway must confirm token state with the identity provider on each call, using openid-connect introspection | Each request may add a call to the identity provider, so latency and provider capacity must be measured, and caching settings need a documented trade-off against revocation speed |
| Local JWT verification | Signed JWTs where the gateway checks signature, issuer, audience and expiry locally, using the openid-connect or jwt-auth approach with keys fetched from the provider | Signing key rotation must be handled and tested, revoked tokens remain valid until expiry unless you add a revocation check, and claim mapping rules must be maintained |
| Plugin chaining through multi-auth | Routes that must accept more than one credential type, such as a browser session and a machine token, by chaining authentication plugins with multi-auth | Each chained plugin is a separate failure path to test, error responses can be hard for clients to interpret, and every new method adds configuration and monitoring work |
How to wire the openid-connect plugin to your identity provider
This sequence takes the gateway from a reachable Admin API to a protected test route that accepts identity provider tokens and rejects anonymous calls. Each step closes with a check, so you know the integration works before any production API depends on it.
Confirm deployment mode and Admin API access
Your platform or security team confirms which APISIX deployment mode runs in your environment: traditional, decoupled or standalone. In traditional mode, client traffic arrives on port 9080 and the Admin API listens on port 9180, so the team checks which network segments can reach that port and records the answer. In standalone mode, route configuration lives in a YAML or JSON file and the Admin API behaves differently, so confirm how changes will be applied. Done means the team can write a test route through the chosen path from a designated administration host, and anonymous access to the Admin API is confirmed as blocked.
Register the gateway as a client in your identity provider
Your identity administrator creates a confidential client for the gateway in your identity provider, such as Keycloak, Auth0, Microsoft Entra ID, Google or Okta. The registration needs the redirect URI for the gateway callback path, the scopes your APIs expect, and a client secret stored in your secrets manager, not in route files. Confirm the exact redirect and scope settings against the openid-connect plugin documentation and your provider's guide, since requirements differ by provider. Done means the provider's discovery document (the OpenID configuration endpoint) loads from the gateway host and returns the issuer and endpoint URLs you expect.
Configure openid-connect on one non-critical route
A platform engineer adds the openid-connect plugin to a single low-risk test route, using the discovery URL, client ID, secret and the authentication flow your design requires, such as authorization code for browser users or bearer token validation for API callers. Keep the route off production traffic and document the rollback step, which is removing the plugin from the route. Done means a request to the test route with no token is rejected, and a browser or test client completes login and receives access to the upstream.
Verify token validation and expected claims
The test team obtains a token from the identity provider for a test user and calls the test route with it. The gateway should accept the token and pass the expected claims upstream, which the upstream echo or logging endpoint can confirm. The team also tests an expired or tampered token and confirms the gateway rejects it. Done means the accepted request shows the claims your authorization logic depends on, and the rejected requests return an authentication error without reaching the upstream.
Add introspection for machine clients
For machine clients whose tokens must be checked against the identity provider on each call, the team enables token introspection in the openid-connect configuration and confirms the identity provider's introspection endpoint is reachable and that the gateway client is allowed to call it. Ask the provider whether the introspection response carries the claims you need and how revocation is reflected. Done means a client credentials token is accepted, and a revoked or inactive token is refused by the gateway.
Attach jwt-auth or key-auth for non-browser callers
Where a partner system or service cannot run an OIDC flow, the team attaches jwt-auth or key-auth to the consumer or route that needs it, and maps those callers to consumers in APISIX. Confirm with your security team which credential type is acceptable and how keys are issued, rotated and revoked. Done means a request with a valid key or JWT from a registered consumer is accepted, and the same request with a missing or unknown credential is rejected.
Record the test results and plan the rollout
The team documents the discovery URL, client registration settings, plugin configuration, each check result and the rollback procedure in your change record. Your security and operations owners review the list of routes and consumers before any production route receives the same configuration. Done means the record shows a passing result for every check above and a named owner approves moving the pattern to production routes.
How identity maps to APISIX consumers without duplicate accounts
The core problem is that two systems hold two different pieces of truth. The identity provider holds the users, groups and registered clients, and it authenticates them. APISIX holds the routes, consumers and plugin configuration, and it makes the authorization decision on each request. Once the openid-connect plugin has validated a token, APISIX still has to decide which consumer object, if any, that caller corresponds to and which routes that consumer may reach. Get that mapping wrong and you get either blocked legitimate users or, worse, callers who inherit access meant for someone else. Decide the mapping before you write any route configuration, because it determines how every later access rule is written.
Start by choosing one stable identifier per caller type and writing it down. For human users, the subject claim (sub) issued by the identity provider is the safest key because it does not change when someone changes an email address or username. For machine clients using the client credentials or introspection flows, the client ID is the natural key. Test this with real tokens from your own identity provider. Decode a sample access token, confirm which claims are present, and check whether the values are stable across logins. Email and preferred_username are convenient for humans but often editable, so use them for display or logging rather than as the consumer key. Confirm with your platform team how each claim is named in your tenant, since providers differ in claim naming and in whether they include the client ID in the token.
Duplicate accounts usually come from two sources: a human who logs in through more than one path (for example a browser session and a service account created for the same person), or a consumer created by hand in the Admin API for someone who later signs in through SSO. To prevent this, define a single rule for who gets a consumer object and create consumers from the identity provider's records, not from ad hoc requests. Keep a documented register that maps each consumer name to its identity provider subject or client ID. Run a periodic reconciliation that lists consumers without a matching identity and identities without a consumer. Review any consumer that has no owner. The register also gives your auditors a clear trail from a logged request back to a person or system.
Group and role claims are where access decisions usually live, and they need the most careful testing. The openid-connect plugin can pass claims upstream or be configured to check them, but whether a given group claim can be used directly to select a consumer or to gate a route depends on the plugin version and your configuration. Do not assume the behavior from documentation alone. Build a test matrix with at least one token per group or role, call each route with each token, and record which requests are allowed, denied and logged with which identity. Include a token with no groups and a token with groups that should match nothing. Repeat the test after every APISIX upgrade and after any change to the plugin configuration, because the claim-to-consumer behavior is not something to rely on without verification.
Plan for the cases where the identity provider changes a claim, removes a user, or rotates a client secret. Map each of these to an action: disable the consumer, rotate the credential, or update the register. Ask your APISIX implementation partner or internal team to document which claim is authoritative for each route group, who approves changes to group-to-route rules, and how a removed employee's access ends in both systems. A consistent process here does more to prevent stale or duplicate access than any single plugin setting.
What drives Apache APISIX SSO integration effort and how to reduce it
This table lists the factors that change how much work an APISIX identity integration takes and how to keep each one contained. Read each row as a question to answer before asking for a quote, since most scope changes come from these drivers. The main takeaway is that standardizing providers, grouping routes by policy and reusing one tested plugin template usually reduce effort more than any single technical choice.
| Driver | Why it changes effort | How to keep it down |
|---|---|---|
| Identity providers and client applications | Each provider needs its own openid-connect configuration, redirect URIs, client secrets and claim mapping, and each client application needs its own test cases. | Standardize on one provider per API class, such as workforce or partner, and register clients from a single template. |
| Protected routes and policy variety | Every route with a distinct scope, role or claim rule adds configuration and test cases, and unusual exceptions multiply review work. | Group routes by policy in a small set of route templates or service definitions, and keep exceptions documented and few. |
| Browser users and machine clients sharing APIs | Browser flows use authorization code with PKCE, while machine clients use client credentials or token introspection, so one API may need two validation paths. | Split APIs by caller type where possible, or confirm early which token type each route must accept and test both paths together. |
| LDAP directory complexity | Nested groups, multiple directory domains, inconsistent attributes and slow lookups affect how consumers and roles are mapped in APISIX. | Confirm the directory structure, agree on the attributes APISIX needs, and limit mapping to a short, documented list of groups. |
| Number of environments | Development, test, staging and production each need their own redirect URIs, issuers, keys and secrets, and each must be verified separately. | Keep one configuration template with environment variables, and automate promotion so identical settings move between environments. |
| Compliance evidence for identity controls | Assessors may ask for records of access decisions, token lifetimes, key rotation and change approvals, which requires logging and documentation work. | Agree on the evidence list at scoping, such as configuration records and test results, and confirm which controls an independent auditor will examine. |
| Plugin reuse and testing | Each custom or hand-tuned authentication configuration needs its own verification, so inconsistent setups raise both build and retest effort. | Reuse one tested plugin template for each authentication pattern and ask the quote to name the test cases each pattern covers. |
How the deployment mode changes identity wiring
In traditional mode, the control plane and data plane run in the same APISIX deployment. Identity settings for the openid-connect plugin are written through the Admin API, which listens on port 9180, and persisted in etcd. Gateway nodes read that stored configuration and apply it to live routes, so an identity change takes effect without a file deployment.
- Where settings live: Plugin configuration attached to routes, services or consumers, stored in etcd and changed through the Admin API on port 9180.
- How changes roll out: The cluster applies a change once the Admin API accepts it. Test changes on a non-production cluster first, and save the previous route definition so you can restore it quickly.
- How secrets reach the gateway: Client secrets are included in the plugin configuration and then stored in etcd. Confirm whether your APISIX version supports secret references to an external secret store or environment variables, and confirm who can read the Admin API and etcd.
- Discovery reachability: Each gateway node must reach the identity provider's discovery document and its token and JWKS endpoints from the network segment where that node runs.
Before approving a route change, confirm that the Admin API is reachable only from management networks and that every gateway node can fetch the discovery document.
In decoupled mode, data plane nodes and control plane nodes are separate deployments that share one etcd cluster. Administrators write identity configuration through the control plane, and data plane nodes read the same etcd state to enforce it. This split lets you limit the Admin API to the control plane network while gateway nodes sit closer to clients.
- Where settings live: Still in etcd, but authored through control plane Admin API endpoints. Data plane nodes do not offer a separate place to write identity settings.
- How changes roll out: Changes reach data plane nodes through the shared etcd cluster, so etcd health and latency determine how quickly a new client secret or scope is enforced. Verify on each data plane node after a change.
- How secrets reach the gateway: Client secrets are stored in etcd and read by data plane nodes. Confirm access controls on etcd, since it is the shared store for both planes, and confirm how secret references resolve on the data plane network.
- Discovery reachability: Data plane nodes call the identity provider during token validation, so firewall rules must allow that path from each data plane subnet, in addition to any control plane access.
- Failure scope: An etcd outage affects both planes at once, so monitoring and backups for etcd belong in the design from the start.
Before go-live, confirm that each data plane subnet can reach the discovery and JWKS endpoints and that etcd access is restricted to the nodes of both planes.
In standalone mode, APISIX runs without etcd and loads routes, plugins and identity settings from conf/apisix.yaml or conf/apisix.json. The file on each node is the source of truth for that node. APISIX checks the file for changes every second and hot-reloads it without a restart, so configuration changes become a file distribution task.
- Where settings live: In the configuration file on each node, including openid-connect settings within route definitions.
- How changes roll out: Distribute the same file to every node through your configuration management or deployment pipeline. Because no central store keeps nodes aligned, compare file checksums on every node after each change.
- How secrets reach the gateway: The client secret appears in the file in clear form unless your pipeline injects it at deploy time. Confirm the injection method your pipeline supports and restrict read access to the file.
- Discovery reachability: Each node validates tokens against the identity provider from its own network, so confirm that the discovery and JWKS endpoints respond from every node.
- Admin API use: Confirm whether your standalone design uses the Admin API at all, and if it does, how it is locked down.
Before approving a rollout, confirm that every node has loaded the same file version and that the identity provider's endpoints resolve and respond from each node's network.
The APISIX Ingress Controller is a separate project from the gateway. It lets APISIX act as a Kubernetes ingress controller and translates Kubernetes resources into gateway routes. Its identity configuration follows the controller's own resource model and release line, so confirm it separately from the gateway modes above, even when the same identity provider is used.
- Where settings live: In Kubernetes resources that the controller translates. Confirm which resource types carry openid-connect settings in the release you plan to deploy.
- How changes roll out: Changes follow your cluster's deployment process. Confirm how the controller reconciles resources and the order in which controller and gateway updates should happen.
- How secrets reach the gateway: Confirm how client secrets are referenced from Kubernetes Secrets, and which namespaces are allowed to read them.
- Discovery reachability: Confirm that gateway pods, not only controller pods, can reach the discovery and JWKS endpoints under your cluster egress policy.
- Version alignment: Check compatibility between the Ingress Controller release and the gateway release using the project's published guidance.
Before writing any manifests, confirm the identity resource format, secret references and reconciliation behavior with the project documentation for the release you plan to deploy.
Securing tokens, client secrets and callback paths during SSO
When APISIX brokers sign-in through the openid-connect plugin, the gateway holds the client credentials, validates tokens and decides where users are sent after login. The controls below cover the identity-specific settings that determine whether those roles stay contained, and the hardening topic covers the gateway and Admin API beneath them.
Client secret storage and rotation
The openid-connect plugin needs the client ID and client secret for each registered application, and those values should never sit in plain text in route definitions that many people can read. Confirm where the secret is stored, who can read it, and how it is replaced without downtime. Agree a rotation procedure with the identity provider team before go-live, and test that a rotated secret takes effect on every gateway node.
Allowed redirect URIs and scopes
Register the exact callback URLs APISIX will use and nothing broader, because overly permissive redirect URI patterns are a common route to token theft. Limit requested scopes to what each API actually needs, and confirm the identity provider rejects authorization requests that name other scopes or callback paths. Review this list whenever a new route or hostname is added.
Token lifetime and refresh behavior
Set access token lifetimes and refresh token policies in the identity provider, then confirm how the openid-connect plugin handles expiry, renewal and session cookies. Short access tokens limit the damage from a leaked token, but they also increase refresh traffic, so test the balance under expected load. Decide whether refresh tokens are rotated on use and how logout invalidates sessions held at the gateway.
Signing keys and introspection credentials
JWT signing keys, introspection client secrets and private keys belong in a secrets store or environment injection, not inside route or plugin JSON that is exported, versioned or copied between environments. Check how the plugin fetches the identity provider's public keys and how it caches them. Use separate introspection credentials for each gateway environment so that one compromised value does not reach every route.
Who can change identity plugin settings
Changes to the openid-connect or jwt-auth configuration alter who is allowed through, so they need a narrower permission model than ordinary route edits. Map which administrators, pipelines and service accounts can write identity plugin settings through the Admin API, and remove shared admin keys from routine use. Keep the Admin API lockdown itself, including key changes and network exposure, in the separate security hardening topic.
Logging authentication failures
Failed logins, rejected tokens, expired sessions and redirect URI mismatches are the earliest signals of misconfiguration or abuse, so they should reach your log platform with enough context to investigate. Confirm which events the plugin records, which fields are masked so tokens and secrets are not written to logs, and how long records are retained. Agree an alert threshold for spikes in failures with the security operations team.
How to test Apache APISIX SSO and confirm it fails closed
The point of this section is to prove that the gateway denies access whenever identity cannot be established, and to keep that proof repeatable. A working login flow is not enough. The test set should cover the paths where an error would silently grant access: requests with no credentials, sessions that should have ended, tokens that have been changed or have expired, an identity provider that cannot be reached, and accounts or consumers that have been turned off. Each of these should be a named test with an expected result, so a failure is obvious and not a matter of opinion. Start with the basic cases. An unauthenticated request to a protected route should be refused, and the test should confirm that the upstream service receives nothing. Then test a valid browser session against a protected route and confirm that the request reaches the upstream with the identity headers your design defines, and that those headers carry the expected subject and nothing the client could have supplied itself. Next, present an expired token, a token with a modified payload or signature, and a token issued for a different audience. Each should be rejected. For the openid-connect plugin, confirm the behavior of token introspection for machine clients by stopping or blocking the identity provider's introspection endpoint and checking that the gateway denies the request rather than passing it through. Confirm the exact fallback behavior in the plugin documentation for your version. For LDAP-backed flows, create a test account, confirm it can authenticate, disable it in the directory, and confirm that the gateway denies it on the next attempt within the cache window you have configured. Then remove a consumer or revoke its key in the APISIX Admin API on port 9180, and confirm that requests using it are refused. Use test identities and a non-production route with a dummy upstream that logs every request it receives. Keep the Admin API restricted to the test network, and make sure test secrets are not reused from production. Record each test with the date, the APISIX version and plugin configuration hash, the identity provider configuration, the request and response status, and a copy of the upstream log showing whether the request arrived. Store the results with your change records. Repeat the full set after any change to a plugin, a route, a consumer, the identity provider or the etcd or deployment configuration. A partner can help write the test scripts and evidence template, but your team should confirm the expected results against your own identity provider settings and any compliance control you are mapping to.
What to monitor, back up and document after go-live
Once the openid-connect integration serves real traffic, the gateway, the identity provider and the client records all change over time. The cards below cover the signals to watch, the configuration that must be recoverable, the credentials that expire on schedule and the mapping knowledge that otherwise lives only in one engineer's head.
Authentication error rates and provider latency
Track the share of requests that fail authentication at the gateway, split by route and by identity provider response. Measure the time APISIX waits on the provider for discovery, token and introspection calls, since slow provider responses often look like gateway failures to users. Set baselines during the pilot period so that alerts reflect your normal traffic rather than a guessed threshold.
Alerts on rejected token spikes
Alert on sudden increases in rejected tokens, not only on absolute counts. A sharp rise can point to an expired signing key at the provider, a changed audience or issuer value, a misconfigured client after a deployment, or a client that has started retrying with stale credentials. Route these alerts to the team that owns the identity provider as well as the gateway team, so the first responder can check both sides.
Route and plugin configuration backups
Back up the route, upstream, consumer and plugin configuration in the form that matches your deployment mode. In traditional or decoupled mode that means snapshotting the etcd data, with its own backup and restore test. In standalone mode it means version controlling the YAML or JSON file that holds the configuration. Confirm with your own environment how a restore is performed and time-boxed in a rehearsal.
Identity provider certificate and secret expiry
Keep a register of every certificate, signing key and client secret the integration depends on, with its expiry date and the step needed to rotate it. Client secrets and provider certificates expire on their own schedules, and a missed rotation causes a hard outage at the gateway. Schedule reminders well ahead of each expiry and rehearse the rotation in a non-production environment before it is due.
Retesting after each release line update
Rerun the authentication test suite after every APISIX release line update, every openid-connect plugin change and every identity provider configuration change. Include valid and invalid tokens, expired tokens, the PKCE and client credentials flows where used, and the introspection path for machine clients. Confirm release notes for each version you adopt before applying it to production, since plugin behavior can change between versions.
Claim-to-consumer mapping and client ownership
Document which token claims map to which APISIX consumers or headers, and which values grant which access. Record the named owner of each identity provider client, its redirect URIs, its scopes and the team to contact when it changes. Without this record, a provider-side change can break routes silently, and nobody can say whether a client is still needed or who may approve its removal.
Questions teams ask before bringing in help with APISIX SSO
How much effort does APISIX SSO integration take?
Effort depends mostly on how many identity providers you connect, how many routes need protection, and whether machine clients are involved. The factors that move it most:
- Number of identity providers and their setup (for example, Keycloak, Microsoft Entra ID, Okta or Google), since each needs its own client registration, redirect URIs and claim mapping.
- Route count and how many distinct access rules apply to them.
- Machine clients that use client credentials or token introspection, which need a separate test path from browser users.
- LDAP directories, which need bind accounts, group lookups and network access from the gateway.
- Number of environments (development, staging, production), each with its own identity configuration.
Ask any partner to break the quote down by these factors so you can see what drives the price.
How long does an APISIX SSO project take?
The schedule is usually set by access to the identity provider and test accounts, not by gateway configuration itself. Work can stall while waiting for an administrator to create a client registration, approve a redirect URI, or provide a test tenant with users in the right groups.
Order the work so that identity access is confirmed first. Then plan the route-by-route rollout, testing each application in staging before it moves to production. Ask for a phased timeline in the written scope, with named dependencies on your side and a clear change window for production cutover. Any duration in a proposal should be tied to those dependencies rather than presented as a fixed number.
What do we need to provide for an APISIX SSO engagement?
Before work starts, the team typically needs the following from your side:
- Administrator access to the identity provider, or a named administrator who can create and change client registrations.
- A test tenant or non-production identity environment with representative users and groups.
- A route inventory listing each API or application, its upstream, and the access it needs.
- A named owner for each application who can confirm expected behavior and sign off on testing.
- A change window for production cutover, agreed with operations and the application owners.
Missing items are the most common cause of delay, so confirm them in the scope document before the schedule is fixed.
Can our internal team set up APISIX SSO without outside help?
Yes, if your team has skills in both identity and API gateway operations and enough time to test properly. The work combines OpenID Connect configuration on the identity side, plugin configuration and routing on the gateway side, and testing of browser flows, token handling and machine clients.
The usual gaps are not the initial configuration but the testing: expired tokens, group-based access, failure behavior when the identity provider is unreachable, and how audit logs record identity. Assess whether your team can cover those cases for each application. If it cannot, an external partner can take on defined parts of the work while your staff keep ownership of the result.
Is Apache APISIX free to use?
The APISIX software is licensed under the Apache License 2.0 (SPDX identifier Apache-2.0), so there is no license fee for the open-source gateway. The total cost of running it comes from other places:
- People: engineers to deploy, configure, test, upgrade and operate the gateway.
- Infrastructure: compute, networking and the etcd cluster used for configuration storage in traditional and decoupled modes.
- Support: whether you rely on internal expertise or a support or maintenance agreement.
Commercial products built on APISIX, such as API7 Enterprise from API7.ai, add vendor support and features on top of the open-source base. Its pricing is not published on the vendor page, so request a quote directly.
What should a fixed-scope APISIX SSO quote include?
A fixed-scope quote should state exactly what is in and out of the work so that both sides can check the result. Look for these items in writing:
- The identity providers and protocols covered, and whether LDAP or machine clients are included.
- The list of routes or applications in scope, with the route inventory used to define them.
- Environments covered and where production cutover happens.
- Deliverables, such as configuration as code, test results, runbooks and handover notes.
- Your dependencies, including the access and owners listed above.
- Assumptions about the identity provider version and any items excluded, such as custom identity features.
- How changes to scope are requested, reviewed and priced.
The quote should itemize the work so that you can compare it with an internal estimate line by line.
Which identity provider setup details should we check first?
Confirm the identity provider's OpenID Connect settings before the gateway work begins, because most failures trace back to them. Check that the provider supports the authorization code flow with PKCE for browser users and client credentials for services, and confirm the issuer URL, discovery endpoint and token signing settings.
Also verify which claims carry user identity and group membership, and whether the provider issues tokens that the gateway can validate. Check the redirect URIs and allowed origins for each application, and confirm how sessions expire and refresh. Refer to the APISIX openid-connect plugin documentation and your provider's own documentation to confirm which flows and options apply to your version.
How DeployOpen scopes, builds and hands over APISIX identity work
DeployOpen plans, implements, integrates, documents and supports self-hosted open-source platforms inside your own infrastructure, and APISIX identity work follows the same path. Each engagement starts from a written, fixed scope that names the identity provider, the routes to protect and the handover deliverables before any configuration changes are made.
How we scope
- Inventory the routes, upstreams and APIs that need authentication, and which clients call each one.
- Confirm the identity provider, the OpenID Connect flows required and whether PKCE or client credentials apply.
- Record in the written scope which machine clients, JWT or LDAP options and consumer mappings are included.
How we build
- Configure the openid-connect plugin in a non-production APISIX environment against your identity provider.
- Test authorization code, client credentials and token introspection paths, including expired and revoked tokens.
- Map identity claims to APISIX consumers and document each mapping rule alongside the route configuration.
How we hand over
- Deliver versioned route and plugin configuration, with the identity provider settings kept out of plain text files.
- Provide test evidence for each protected route, including negative tests for unauthenticated requests.
- Write runbooks for rotating client secrets, adding consumers and troubleshooting token validation failures.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Retainers can cover reviews when APISIX or your identity provider changes its supported flows or settings.
- Confirm during scoping whether support includes the Admin API access controls and etcd upkeep.
