This Article provides a guide for diagnosing and resolving a 401 Unauthorized error during an OpenID Connect (OIDC) integration, specifically when the error is returned by a third-party Service Provider (SP).

401 Unauthorized

The scenario addressed is one where the client application has successfully received the ID Token and/or Access Token from the Okta Authorization server, but is subsequently rejected by the Service Provider (SP) when using those tokens to access a protected resource.

• Okta OpenID Connect
• API Access Management
• OAuth 2.0

The root cause will most likely be found in one of the following areas for OIDC SSO:

1. OIDC Token Validation failure (missing user claims): The required user data (claims) needed for the SP to recognize the user is missing or incorrect.
2. OIDC Token Validation failure (audience mismatch): The SP is expecting a specific audience value ("aud" claim), which is different from the value already included in the token.

NOTE: Before contacting the Service Provider, it is essential to check the Okta system logs to verify that OIDC tokens are generated successfully.

The following three events will be visible for the application/client used in the OIDC integration:

After validating that the tokens are successfully generated, please confirm/check with the Service Provider (SP) the following:

1. Ensure that the client application is requesting all necessary OIDC scopes (openid, profile, email).

This can be checked from the Service Provider's configuration dashboard.

Additionally, confirm if the SP is looking for the correct claim (for example, email vs preferred_username).

An example of a decoded ID Token can be found in the OpenID Connect & OAuth 2.0 Okta Developer documentation.

2. Check the target audience: The token contains an "aud" claim specifying who it is for.

This value must match the Client ID or unique identifier that the Service Provider (SP) expects.

NOTE: 

• When using the ORG server, the "aud" claim (audience value) will be the Client ID of the OIDC application. The ORG server does not allow custom scope definitions. Only the standard OIDC Scopes and Okta Scopes are allowed.
• When using a Custom Authorization server, the audience value is specified in the server settings. In this case, specify a custom audience value according to the requirements from the SP.

Related References

• OAuth 2.0 and OpenID Connect overview
• ID Token payload example
• Access Token payload example
• Okta OpenID Connect & OAuth 2.0 scopes
• Authorization Servers