Test support for OAuth/Okta

[Aniruddh25]

We might already be supporting OAuth - https://github.com/Azure/data-api-builder/blob/c5c7031a86275ea5b33cf11e31acac48965b9185/src/Core/AuthenticationHelpers/SupportedAuthNProviders.cs#L13 with the name Custom authentication provider. Might just need to try, test and validate this before documenting.

[Aniruddh25]

When tried years ago, the issue was that we were NOT able to properly get the roles from OAuth/Okta

[vs-dsva]

I do not think it works: https://github.com/Azure/data-api-builder/issues/2820

[JerryNixon]

From our friend GitHub Copilot

Can Data API Builder (DAB) work with Okta? How?

Yes! Data API Builder (DAB) can work with Okta as an OAuth2 provider, provided your Okta access tokens are JWTs and your DAB configuration matches your Okta issuer/audience and keys.

---

Flow

• Set "provider": "Custom" in DAB config.
• Configure jwt.issuer, jwt.audience, and ensure DAB can access Okta’s JWKS (public key) endpoint.
• Any OAuth2 provider (Okta, Auth0, etc.) is supported if it issues JWTs with the required claims.

Source:
ClientRoleHeaderAuthenticationMiddleware.cs

This middleware validates JWT tokens when JWT Auth is configured
and an Authorization HTTP header is present with a token.

---

Okta Compatibility

• JWTs only: Okta must issue JWT access tokens, not opaque tokens.
• Signing: Tokens must be signed with RS256 and Okta’s JWKS endpoint must be reachable.
• Claims: Must match DAB’s expectations for issuer, audience, and (optionally) roles.

---

Required Claims & Validation

1. aud – must equal jwt.audience.
   Source: JwtTokenAuthenticationUnitTests.cs
2. iss – must equal jwt.issuer.
3. Signature – must be signed by a key DAB trusts (Okta’s JWKS).
4. exp – must be valid (not expired).

---

Recommended Claims

• name – user identifier (username/email).
• roles – array of roles for RBAC.
  • Okta often uses groups; you can map this to roles in Okta or configure DAB to use groups.

Source:
AuthorizationResolver.cs

DAB will only resolve one 'roles' claim whose value matches the x-ms-api-role header value
because DAB executes requests in the context of a single role.

---

JWT Example

Header

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "abcdef123456"
}

Payload

{
  "iss": "https://your-okta-domain/oauth2/default",
  "aud": "api://default",
  "exp": 1750975200,
  "iat": 1750971600,
  "nbf": 1750971600,
  "sub": "00u1abcd2EFGH3ijk4l5",
  "name": "[email protected]",
  "email": "[email protected]",
  "groups": ["admin", "user"],     // Okta default
  "roles": ["admin", "user"]       // Map Okta groups to roles for DAB RBAC
}

Signature

• RS256 (signed using Okta’s JWKS public key).

Source:
JwtTokenAuthenticationUnitTests.cs

---

Example DAB Config

"authentication": {
  "provider": "Custom",
  "jwt": {
    "audience": "<okta-client-id-or-api-audience>",
    "issuer": "https://<your-okta-domain>/oauth2/default"
  }
}

---

JWT Processing and Claims Extraction

• DAB uses ASP.NET Core/JWT middleware to validate signature, issuer, audience, and expiration.
• Claims are extracted and flattened to key-value pairs, including handling arrays (roles, groups).
• Only one role is used for authorization context per request (see x-ms-api-role header).

Source:

• AuthorizationResolver.GetProcessedUserClaims
• AuthorizationResolver.GetAllAuthenticatedUserClaims
• dotnet claim flattening behavior

---

Common Issues

1. Audience (aud) mismatch.
2. Issuer (iss) mismatch.
3. Invalid or missing signing key.
4. Expired/not yet valid token.
5. Wrong signing algorithm (must be RS256).
6. Missing claims (roles or name). (Map Okta groups if needed)
7. Okta returns opaque tokens (not JWTs).
8. Misconfigured DAB jwt section.
9. JWKS endpoint is unreachable from DAB.

---

Summary Table

Claim	Required	Purpose	Example Value
aud	Yes	Audience	Okta client ID or API audience
iss	Yes	Issuer	https://<okta-domain>/oauth2/default
exp	Yes	Expiration	UNIX timestamp
name	Recommended	User identifier	Username/email/user id
roles	For RBAC	Role-based access	["admin", "user"] or mapped from groups

---

Conclusion

DAB does work with standard Okta JWT access tokens if:

• Issuer and audience match your config.
• RS256 signing is used with a valid JWKS key.
• Roles are supplied in roles or mapped from groups.

See also:

• AuthorizationResolver.cs
• JwtTokenAuthenticationUnitTests.cs
• dotnet JWT claims behavior

[JerryNixon]

@vs-dsva I want to figure this out, so please let us know.

[vs-dsva]

@JerryNixon - updated #2820 with all the info i could gather.