Set up OIDC SSO and RBAC for your enterprise API gateway management platform

Enlarge

Most enterprise API gateway deployments have a shared admin problem. The management interface ships with a single admin account, platform engineers share the credential, and nobody changes the access model until something goes wrong: a contractor rotates off the project and their login still works three months later; a compliance audit asks who changed a proxy configuration and the honest answer is "the admin account"; a production API product gets misconfigured and there is no way to attribute the change.

Configuring enterprise API gateway OIDC SSO solves the structural problem. Every operator authenticates with their own identity from your existing identity provider, inherits exactly the permissions their IdP group entitles them to, and leaves a named, timestamped record on every management action. Access revocation is live — remove someone from the IdP group and their gateway access disappears on the next token refresh, without touching the gateway configuration.

This guide walks through exactly how to configure OIDC and four-tier RBAC for the Zerq management platform, using the actual environment variable names the backend and frontend read at startup.

Why bolt-on access control breaks

Teams usually patch this with one of three workarounds. Some create multiple admin accounts — one per team — and try to rotate credentials manually when people leave. This produces orphaned accounts and no separation of duties. Others put HTTP Basic Auth in front of the management API. This adds a component to maintain and still does not connect to the organization's real identity source. Others write scripts that sync group memberships from the IdP into a static role list in the gateway config, then discover six months later that the sync broke quietly and nobody noticed.

The structural problem none of these solve: authorization needs to live in the IdP, not be copied from it. When someone leaves the org, revoking their SSO access should be the only step required. It should not also require a platform engineer to remember to clean up a gateway credential.

Kong's RBAC plugin manages roles in Kong's own database, separate from your IdP, and requires the Enterprise license. AWS API Gateway's IAM-based access governs the AWS console, not API management operations. Apigee's org-level access control is scoped to its hosted control plane — on-premises deployments need custom auth middleware. Zerq's management RBAC uses OIDC natively. Every request to the management API is validated against your IdP's JWKS endpoint. Roles are extracted from the bearer token's claims. There is no separate role database to maintain or sync.

The four management role tiers

Zerq defines four role tiers for management access. Each maps directly to a group in your identity provider:

The critical separation is auditor versus modifier. Compliance teams get auditor — they see everything in the audit trail but cannot change configuration. Platform engineers get modifier. The CISO or platform lead gets admin. Nobody who should not be touching production configuration can do so, even if they have full log visibility.

Authorization is enforced at the backend. The management UI reflects the same role state in the UX, hiding actions the user cannot take. That is a UX convenience, not an enforcement boundary. A backend 403 is the real enforcement.

Backend OIDC configuration

Set these environment variables on the backend service before startup:

# Management OIDC
OIDC_ENABLED=true
OIDC_ISSUER_URL=https://idp.example.com/oauth2/default  # your IdP discovery base URL
OIDC_AUDIENCE=zerq-management                            # must match 'aud' in issued tokens
OIDC_ROLE_CLAIM_PATH=roles                               # dot-notation path to roles in the JWT
OIDC_CACHE_TTL=300                                       # seconds to cache JWKS responses

# Map IdP group names to Zerq role tiers
OIDC_VIEWER_ROLES=platform-viewers,devops-readonly
OIDC_MODIFIER_ROLES=platform-engineers,api-ops
OIDC_AUDITOR_ROLES=compliance-team,security-analysts
OIDC_ADMIN_ROLES=platform-leads

OIDC_ROLE_CLAIM_PATH accepts a dot-notated path into the JWT claims object. If your IdP puts roles at resource_access.zerq.roles (common in Keycloak), use that full path. If roles are at the top-level roles claim, use roles. The backend extracts the list of role values at that path and matches each against the configured role sets.

OIDC_AUDIENCE must match the aud claim in the tokens your IdP issues for this application. This prevents tokens issued for other services in your IdP from being accepted by the management API.

OIDC_CACHE_TTL controls JWKS caching. Three hundred seconds is a reasonable default. Lower it if you need faster key rotation propagation; raise it if your IdP rate-limits the JWKS endpoint.

Each role env var accepts comma-separated group names. A token carrying any of the listed values for a given tier is granted that tier's access. This lets you map multiple IdP groups to a single Zerq role — useful when separate teams within your org should share the same gateway access level.

Frontend role configuration

The management UI reads role information from the same OIDC session and renders navigation and actions accordingly. Configure these variables on the frontend service:

# NextAuth / OIDC for the management UI
OIDC_ISSUER_URL=https://idp.example.com/oauth2/default
OIDC_CLIENT_ID=zerq-management-ui
OIDC_CLIENT_SECRET=<client-secret-from-idp>
ROLE_CLAIM_PATH=roles                        # must match backend OIDC_ROLE_CLAIM_PATH exactly
NEXTAUTH_SECRET=<random-64-character-string>

# Role name sets — must be identical to backend OIDC_*_ROLES values
NEXT_PUBLIC_VIEWER_ROLES=platform-viewers,devops-readonly
NEXT_PUBLIC_MODIFIER_ROLES=platform-engineers,api-ops
NEXT_PUBLIC_AUDITOR_ROLES=compliance-team,security-analysts
NEXT_PUBLIC_ADMIN_ROLES=platform-leads

The NEXT_PUBLIC_*_ROLES values must be identical to the backend OIDC_*_ROLES values. A mismatch produces a confusing state where the UI hides a button the backend would allow, or shows an action the backend will reject. Set both together, in the same change, and re-validate after any modification.

Step-by-step: configure OIDC and RBAC

1. Register the management UI in your IdP

Create an OIDC application in your identity provider:

• Grant type: Authorization Code with PKCE
• Redirect URI: https://your-management-ui.example.com/api/auth/callback/oidc
• Token claims: configure your IdP to include the roles claim at the path you will set for OIDC_ROLE_CLAIM_PATH

For Okta, add a custom groups claim to the access token using an Okta expression. For Azure AD, configure app roles or group membership claims in the application manifest. For Keycloak, add a group membership mapper under the client's dedicated scope.

2. Create IdP groups for each role tier

Create a dedicated group for each Zerq role tier with names you control:

• platform-viewers — read access for on-call DevOps
• platform-engineers — operational access for the API platform team
• compliance-team — audit access for the compliance function
• platform-leads — admin access for platform leads

3. Configure backend environment variables

Add the OIDC configuration block to your backend .env file or inject it via your secrets manager. Restart the backend service.

4. Configure frontend environment variables

Add the OIDC and role blocks to your frontend .env. The ROLE_CLAIM_PATH must match the backend OIDC_ROLE_CLAIM_PATH exactly. Rebuild or restart the frontend service.

5. Validate each role tier

Assign a test account to each IdP group and verify enforcement at the API level, not just the UI:

# Viewer token must not create a collection — expect 403
curl -i https://api.example.com/api/v1/collections \
  -H "Authorization: Bearer $VIEWER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"rbac-test"}'

# Modifier token must create a collection — expect 201
curl -i https://api.example.com/api/v1/collections \
  -H "Authorization: Bearer $MODIFIER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"rbac-test"}'

If a viewer token returns 200 or 201, role extraction is not working. Inspect the token claims to debug:

# Decode the JWT payload to inspect claims
python3 -c "
import os, json, base64
t = os.environ['VIEWER_TOKEN'].split('.')[1]
pad = '=' * (-len(t) % 4)
print(json.dumps(json.loads(base64.urlsafe_b64decode(t + pad)), indent=2))
"

Confirm the claim at OIDC_ROLE_CLAIM_PATH exists and contains the expected group name. Common failure modes:

• Widespread 403 after an IdP update: the role claim path changed or is now missing from issued tokens
• UI shows an action but the API denies it: frontend and backend role env vars are out of sync
• Login loops: OIDC_ISSUER_URL does not match the actual issuer metadata URL from your IdP

Role assignment: a decision framework

These questions help assign the right role without over-provisioning:

• Does this person need to change production configuration, or only observe it? Read-only: viewer.
• Is this person responsible for compliance evidence, audit queries, or regulatory responses? Yes: auditor, not modifier.
• Does this person need to create API products, manage clients, or configure workflows? Yes: modifier.
• Is this person specifically responsible for privileged platform operations? Yes, after explicit approval: admin.

Some patterns that work in practice for regulated environments:

Grant platform engineers modifier in non-production environments and require a separate IdP group — with a formal approval step — for production modifier access. The Zerq observability layer captures which account made which change in which environment, so the approval record and the configuration change record both exist as evidence.

Keep admin assignment small. The fewer people holding admin, the smaller the blast radius if a credential is compromised. Reserve one emergency admin identity outside normal group-sync automation: a documented break-glass account with audited access procedures, separate from the day-to-day operator identity model.

What this looks like in practice

A bank running Zerq for its open banking API platform started with a shared admin account used by six platform engineers and accessed by the compliance team during audit periods. When a PSD2 audit asked for evidence that compliance staff had independent access to audit records and that platform engineers could not retroactively alter log data, the team could not provide it. Every entry in the audit trail showed "admin" as the actor with no way to attribute actions to individuals.

After configuring OIDC with the four-tier model, every operator authenticates via enterprise SSO. The compliance analysts hold auditor — they query the full audit trail and configuration state snapshots directly, without involving the platform team, but cannot modify anything they are reviewing. Platform engineers hold modifier. The platform lead holds admin. Every management action in the UI is attributed to a named identity with a timestamp.

When the next audit came, the compliance team produced the evidence without a platform team ticket. The regulator could see which operator approved each API product for production, when each proxy configuration was changed, and that no compliance team member had configuration write access at any point.

Because the entire platform runs in the bank's own infrastructure, OIDC token validation happens in-process against the bank's IdP. No token data leaves the bank's perimeter.

Closing summary

OIDC SSO with four-tier RBAC for your API gateway management platform gives you live enforcement, named audit attribution, and a separation of duties model that auditors recognize. Revoke someone from the IdP group and their gateway access disappears within OIDC_CACHE_TTL seconds. Grant auditor to your compliance team and they query every log entry without touching configuration. Every change is in the audit trail under a real identity, not a shared account name.

Zerq is an enterprise API gateway built for regulated industries — one platform for API management, AI agent access, compliance audit, and developer portal, running entirely in your own infrastructure. See how it works or request a demo to walk through your specific requirements.