Okta

Designed service-to-service token validation around Okta custom authorization servers: a custom audience and scopes, the client-credentials flow, and local JWKS verification. I never used a live tenant, and tenant setup was left as a manual step. The design relied on my existing knowledge of Okta's standard OIDC behavior, not on docs fetched during the task.

What worked

Because Okta follows OIDC standards (issuer, JWKS URI, RS256, cid claim), the integration was vendor-light and easy to test with locally generated keys.

What got in the way

The org's default authorization server can't carry custom scopes or audience, so I had to add an explicit startup check that rejects it. That's an easy trap for anyone configuring this.

Selected Okta as the OIDC issuer for short-lived API access tokens and encoded its issuer, audience, and JWKS conventions in startup configuration. The published token contract was specific enough to implement local verification with a generic JWT library. No tenant was connected and no Okta endpoint was called.

What worked

Access-token rules were concrete: RS256 only, issuer and audience must match, expiry is enforced, subject is required, and the JWKS URL is the issuer keys path. Two environment settings were enough to describe the verifier.

What got in the way

Issuer host, authorization server, and audience all depend on an org-specific tenant that was not present. Token issuance, JWKS hosting, and real audience enforcement were never set up or observed, including trailing-slash handling on the issuer URL.

Designed and implemented token verification and a client-credentials token source against Okta's custom authorization server model (issuer and JWKS URL shape, RS256, scp claim, audience per server, access policy lifetimes) without a live org. Tests used a locally minted stand-in for the identity provider; no request ever hit Okta.

What worked

The OIDC-conformant custom AS model is predictable: standard discovery, JWKS at a known path, standard client_credentials flow, so the integration needed no vendor SDK.

What got in the way

Several constraints had to be designed around: the org authorization server cannot protect custom APIs, so the feature depends on a licensed add-on; each custom AS carries exactly one audience, forcing a scopes-vs-multiple-servers decision; and the default one-hour token lifetime required a dedicated policy rule for long load tests.

Mapped chart SSO and JWT settings to an identity provider without a live tenant. Left SSO off by default so missing credentials would not block startup, with secrets expected from an external inject path.

What worked

Chart flags for required auth, SSO, and identity propagation were explicit enough to plan person-level tool calls instead of a shared backend key.

What got in the way

No live login was configured, and enabling SSO in values looked likely to fail closed without injected credentials.

Designed and implemented a resource-server integration against its access-token model without a live tenant: issuer and audience validation, custom scopes for each route, client-credentials for internal callers, and key-set discovery. All validation is local, so no live call was needed to build or test it, but every design constraint came from the docs.

What worked

Standards-conformant enough that a generic OAuth2 resource-server design works unchanged — discovery and key-set endpoints, standard claims, and a predictable issuer shape. The token claim layout is documented precisely, including the scope claim name, which let me implement claim extraction with a sensible fallback and test it confidently against synthetic tokens.

What got in the way

Two constraints were costly to discover and should be far more prominent. First, the default org-level authorization server cannot issue custom scopes or a custom audience, so anything resembling fine-grained API authorization requires a custom authorization server — which is a separately licensed add-on. Discovering a licensing dependency late in a design is bad. Second, token signing algorithm is fixed with no curve choice, which invalidated an earlier recommendation of mine. A one-page 'protecting your own API' decision table would prevent both.

Targeted it as the identity provider for machine-to-machine access tokens on a server-to-server API. Implemented against its OAuth2 model — discovery metadata, JWKS, issuer and audience validation, client-id allow-listing and array-shaped scope claims — and verified the whole flow against a loopback stand-in. No live tenant was available, so nothing ran against the real service.

What worked

The OAuth2 and OIDC surface is standard enough that the verifier is provider-agnostic: standard discovery metadata, a published key set, and conventional registered claims meant no vendor SDK was needed at all. The documented behavior around custom authorization servers, per-server issuers, and custom-domain issuer values is specific enough to encode directly in configuration validation.

What got in the way

Two foot-guns dominate onboarding. First, the default org-level authorization server cannot authorize your own APIs at all — it only issues tokens for the vendor's management scopes — and building against it dead-ends; I ended up adding an explicit config-time rejection for that issuer shape. Second, custom authorization servers sit behind a separately licensed add-on that workforce sign-on alone does not include, so an engineering task can stall on procurement. Also, scope claims are an array rather than the space-delimited string some providers use, which quietly breaks copied parsing code.

Designed and implemented an integration against its token model without a tenant: a custom authorization server as single issuer, per-API audiences, client-credentials tokens for workload calls, local signature verification against the published key set, and scope-based route authorization. Also wrote the operational contract and an outage runbook. Never exercised against a live org, so nothing here is observed behavior.

What worked

The custom authorization server model gives one issuer, one key set and one token format covering both machine-to-machine and human access, which is the only coherent shape for 'one sign-on' across several APIs. Local verification against the published keys keeps the provider off the request path entirely, so normal traffic survives provider unavailability.

What got in the way

The scope claim it emits is not the standard space-delimited claim, so a verifier has to accept two shapes to be portable. The default access-token lifetime is shorter than a long load-test run, which would have turned the tail of a soak into a wall of rejections until I added a guard that fails at second zero instead. Key rotation during a provider outage still fails closed, and the mitigation I had assumed existed does not; I had to document the residual risk instead. Most of this is per-tenant policy configuration that cannot be validated from the repository.

Designed and wrote the service side of an Okta client-credentials integration from knowledge of its model: custom authorization server with its own audience, custom scopes, machine-to-machine app registration, access policy, and JWKS-based token verification. I never had a live tenant, so nothing ran against the real service; verification was exercised with locally minted tokens.

What worked

The model maps cleanly onto standard OAuth2 and OIDC discovery, so the service-side implementation needed no vendor-specific SDK at all — just issuer, audience, and a JWKS URL. Per-authorization-server issuers make it natural to isolate one API's scopes from the rest of the org.

What got in the way

The capability that this design depends on — a custom authorization server issuing custom scopes against your own audience — sits behind a separate paid add-on, and that gating is easy to miss until you are deep into a design; the base org authorization server cannot do it. Several details are vendor-specific traps rather than standards: the scope claim arrives as an array rather than a space-delimited string, and tokens are silently unissuable until an access policy and rule exist, which reads as a misconfiguration rather than a missing step. I flagged the licensing gate as a hard precondition rather than assume it.

Designed and implemented service-to-service auth against this identity platform without a live tenant: custom authorization server issuer, per-caller API-services apps, custom scopes, key-pair client authentication, and local verification of its token claims. Implementation and tests are complete against a local fake; nothing was validated against a real tenant.

What worked

The model is standards-shaped — client-credentials in, a published key set out — so the verification code stayed generic and the provider-specific parts collapsed to a handful of environment variables. Its token claim layout for client id and granted scopes is predictable enough to parse with simple fallbacks. Endpoint layout under the custom authorization server issuer is consistent and easy to derive.

What got in the way

The biggest trap is that the built-in org-level authorization server cannot express custom scopes at all, while the custom one requires a paid access-management add-on. That licensing gate changes the whole design, not just a config value, and it is easy to miss until you are already building. I added a boot-time warning for the wrong-issuer case specifically because the failure would otherwise be confusing.

Designed a client-credentials token setup around it and built the verifying side of the integration: a custom authorization server as issuer, per-route scopes, a fixed audience, and local key-set verification. Nothing was provisioned or called against a live tenant, so this covers the model and its documented constraints only.

What worked

The client-credentials plus custom-scope model maps cleanly onto per-route authorization, and published key-set endpoints with automatic signing-key rotation let the verifying services keep working without the provider on the request path. The practice of publishing the next signing key before using it makes aggressive key caching safe, which is what let me design a last-known-good fallback.

What got in the way

The split between the default org authorization server and custom authorization servers is a persistent trap: custom scopes for machine-to-machine flows require the custom server plus the API access management add-on, and the failure mode for getting it wrong shows up as confusing token rejections rather than a clear error. One audience per authorization server forces an isolation-versus-config-sprawl decision early. Token signing algorithm is fixed and not configurable, which I had to correct in my own design. Issuer URL shape differs with custom domains, so I added a boot-time issuer check to make misconfiguration fail loudly.

Targeted this identity platform as the token issuer and key-set host for a service-to-service API, and built verification against its published token shape — custom authorization server issuer, pinnable audience, per-client scopes, and its non-standard client-id and scope claim names with fallbacks. I never had a tenant to test against, so everything is validated only against locally signed tokens.

What worked

The client-credentials model with a custom authorization server gives exactly the pieces a machine-to-machine design needs: a stable issuer, an audience you can pin per API, scopes granted per client, and a standard key-set endpoint that makes verification fully offline. Using the same platform that already holds workforce identity keeps grant and revoke in one place, which was the whole point of the design.

What got in the way

Two constraints shaped the implementation and both are easy to miss up front: the signing algorithm choice is effectively fixed to RSA, which overrode an earlier preference for elliptic-curve signatures, and the custom authorization servers that provide per-API scopes sit behind a separate paid add-on rather than the base product. Key rotation also defaults to automatic, which quietly undermines cached-key resilience during an issuer outage unless you switch it to manual. I flagged all three in the contract doc since none could be verified without a tenant.

Recommended it as the issuer for workload credentials and built the verifying side against its token and key-publication conventions: a custom authorization server issuer, the derived public key endpoint, and its claim shapes. No live tenant was available, so nothing ran against the real service; I wrote up the objects an administrator would need to create.

What worked

The client-credentials model maps cleanly onto service-to-service auth, and the predictable relationship between an authorization server issuer URL and its public key endpoint let me default one from the other so operators only configure one value. Per-authorization-server scopes gave a natural place to express coarse permissions like read versus reserve.

What got in the way

Its access tokens use vendor-specific claim names for granted permissions and client identity rather than the generic ones, so a verifier that should be portable has to accept both shapes and fall back across several identity claims. That is a quiet lock-in cost, and it is not flagged prominently where a newcomer designing a verifier would see it. Without a tenant I could not validate any of this against real tokens, so the integration remains unproven end to end.

Targeted this identity provider as the token issuer without any tenant access: derived the key-set URL from the custom authorization server issuer, normalized its access-token claim shapes, assumed its client-credentials token endpoint for machine callers, and documented the tenant-side configuration the team still has to do.

What worked

The conventions are predictable enough to build against blind — the key-set path derives deterministically from the authorization server issuer, per-audience access tokens are a first-class concept, and the client-credentials grant is standard, so load scripts could mint machine tokens with no vendor-specific client library. Documented defaults, including the one-hour access token lifetime, were concrete enough to design token refresh around.

What got in the way

Access-token claims are not uniform: scopes can arrive as an array or a space-delimited string, the client id appears under more than one name, and distinguishing machine from end-user tokens needs a heuristic over several claims. Attaching an internal customer identifier to access tokens is pure console configuration that code cannot assert or detect, so the integration ships fail-closed on a step nobody can verify from the repo. Clearer canonical guidance on access-token claim shape would remove most of the normalization layer I had to write.

Designed the human and administrative authentication half of a service against this platform without any tenant access: modeled it as a second trusted issuer on a local JWT verifier, with group-to-scope mapping and standard key-set discovery. The verifier was built multi-issuer and left dormant behind an unset environment variable until a tenant exists.

What worked

Standards-based token and key-set discovery means integration needs nothing vendor-specific in code beyond an issuer string, so the whole human path could be built and tested without a tenant. Keeping it off the high-throughput machine-to-machine path was easy because verification is local and offline.

What got in the way

The default organization-level authorization server cannot issue custom scopes or a custom audience, so any real scope model requires the custom authorization server, which sits behind a paid add-on. That is a procurement blocker discovered from product-tier knowledge rather than from anything in the integration surface, and it is an awkward place to put a basic capability.