Developers and administrators configuring applications to interact with Okta may observe two similar discovery endpoints: /.well-known/openid-configuration and /.well-known/oauth-authorization-server. This article clarifies the distinction between these two endpoints and their intended use cases.

• OpenID Connect (OIDC)
• OAuth 2.0

The primary difference between these endpoints lies in the specific protocol standard they support.

• OpenID Configuration

  • Endpoint: /.well-known/openid-configuration

  • Protocol: OpenID Connect (OIDC)

  • Purpose: This endpoint complies with the OpenID Connect Discovery 1.0 standard. It is used by clients implementing OpenID Connect (OIDC) for authentication (verifying a user's identity). The metadata returned includes OIDC-specific information, such as the userinfo_endpoint and supported scopes like openid, profile, and email.

• OAuth Authorization Server

  • Endpoint: /.well-known/oauth-authorization-server

  • Protocol: OAuth 2.0

  • Purpose: This endpoint complies with the OAuth 2.0 Authorization Server Metadata (RFC 8414) standard. It is used by clients implementing pure OAuth 2.0 for authorization (granting access to resources). While the metadata is similar to the OIDC configuration, it is specifically intended for OAuth clients that do not require identity assertions.

In the context of Okta, OIDC is built on top of OAuth 2.0, so the metadata returned by these endpoints often overlaps. However, developers should select the endpoint that matches the protocol standard their application library expects.

Usage Examples

To retrieve the metadata, perform a GET request to the appropriate URL structure for the organization.

Org Authorization Server

For the Org Authorization Server, the discovery endpoints are located at the root of the Okta domain.

• OIDC Discovery Endpoint:

  https://<OktaDomainName>/.well-known/openid-configuration
  

• OAuth 2.0 Discovery Endpoint:

  https://<OktaDomainName>/.well-known/oauth-authorization-server
  

Custom Authorization Server

For Custom Authorization Servers, the endpoints include oauth2 and the specific <authorizationServerId> in the path. The <authorizationServerId> variable corresponds to the specific alphanumeric ID (such as aus9o8wzkhckw9TLa0h7z) or default if the pre-configured Custom Authorization Server named default is used.

• OIDC Discovery Endpoint:

  https://<OktaDomainName>/oauth2/<authorizationServerId>/.well-known/openid-configuration
  

• OAuth 2.0 Discovery Endpoint:

  https://<OktaDomainName>/oauth2/<authorizationServerId>/.well-known/oauth-authorization-server
  

Related References

• Org Authorization Server Discovery Endpoints
• Custom Authorization Server Discovery Endpoints
• Get Well-Known OAuth Configuration for Custom Authorization Servers
• Get Well-Known OpenID Configuration for Custom Authorization Servers
• Get Well-Known OpenID Configuration for Org Authorization Server