The OpenID Connect protocol requires that the client application have knowledge of the configuration of the OpenID Connect Provider, including endpoints, supported features, public keys, etc. This configuration can change over time. In order to allow the client application to easily discover the provider's current configuration, and to give the provider the flexibility to change configuration, the OpenID Connect Discovery specification was created.

To facilitate the dynamic discovery of configuration information, every OpenID Connect Provider is required to provide a document of metadata. The structure of this document is defined by the OpenID Connect Discovery specification, and includes information about the OpenID Connect Provider, including OAuth 2.0 endpoint locations and the public keys used for signing id_tokens. Although the specification is intended for use by client applications, we anticipate that portions of the information contained in the documents will be of value to service providers as well. The document is served from a well-known URI that is guaranteed to not change over time.

Document Location and usage

It is intended that a client application will read the discovery document both at startup and during operation, in order to dynamically configure itself. The document will always be provided at the same location.

The document will be delivered with HTTP cache control headers in order that the client and infrastructure can cache the document appropriately. The client should respect the cache control headers. The client application developer should never copy the values from the discovery document to static variables within his or her application. The values in the document are subject to change without prior notification to the client application developer.

The document of metadata for the BYUAPI implementation can be found at the following link:

https://api.byu.edu/.well-known/openid-configuration

The Discovery Document

The discovery document contains a JSON structure that includes standard keys describing various aspects of our OpenID Connect (and OAuth 2.0) implementation. A minimal implementation of the document looks something like this:

{
	"issuer": "https://api.byu.edu",
	"authorization_endpoint": "https://api.byu.edu/authorize",
	"token_endpoint": "https://api.byu.edu/token",
	"userinfo_endpoint": "https://wso2-is.byu.edu/oauth2/userinfo?schema=openid",
	"revocation_endpoint": "https://api.byu.edu/revoke",
	"jwks_uri": "http://brentmoore.org/test/byucerts",
	"response_types_supported": 
		[
			"code",
			"token"
		],
	"subject_types_supported": 
		[
			"public"
		],
	"id_token_signing_alg_values_supported": 
		[
			"RS256"
		],
	"scopes_supported": [
		"openid"
		]
}

The definition of the content of all the possible keys can be found in the documentation. A few of the keys of interest are:

Key Definition
issuer The entity issuing the document. This should never change for a specific document.

authorization_endpoint

token_endpoint

revocation_endpoint

 

The various endpoints used to interact with the OAuth 2.0 provider. See the OAuth document for more information (citation needed).

userinfo_endpoint The location of the OpenID Connect user information endpoint. See the OpenID Connect document for more information (citation needed).
jwks_uri

The location of the public keys the client can use to validate id_token signatures. The format of this document is described in the JWKS Public Key document.