Obtaining OpenID Provider Configuration Information
Introduction
OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol. It enables Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.
In order for an OpenID Connect Relying Party to utilize OpenID Connect services for an End-User, the RP needs to know where the OpenID Provider is.
Once the OpenID Provider has been identified, the configuration information for that OP is retrieved from a well-known location as a JSON document, including tis OAuth 2.0 endpoint locations.
In this document, we’ll explain how to retrieve this configuration information and how to interpret this.
Retrieving Configuration
We’re exposing our OpenID Provider configuration, by making a JSON document available at the path formed by concatenating the string /.well-known/openid-configuration.
For example, https://login.nxtport.eu/.well-known/openid-configuration.
Configuration Response
The configuration retrieved contains metadata about the OpenID configuration, including all necessary endpoints and public key location information.
Following OpenID provider metadata values are used by OpenID Connect.
issuer
URL using the https scheme with no query or fragment component that the OP asserts as its issuer identifier. This will also be identical to the iss claim value in ID Tokens issued from this issuer.
jwks_uri
URL of the OP’s JSON Web Key Set (JWK) document. This contains the signing key(s) the RP uses to validate signatures from the OP.
authorization_endpoint
URL of the OP’s OAuth 2.0 Authorization Endpoint. This endpoint can be used to request tokens or authorization codes via the browser.
token_endpoint
URL of the OP’s OAuth 2.0 Token Endpoint. This endpoint can be used to programmatically request tokens.
userinfo_endpoint
URL of the OP’s UserInfo Endpoint. This endpoint can be used to retrieve identity information about a user.
end_session_endpoint
URL at the OP to which an RP can perform a redirect to request that the End-User be logged out at the OP.
check_session_iframe
URL of an OP iframe that supports cross-origin communications for session state information with the RP client, using the HTML5 postMessage API.
revocation_endpoint
URL of the OP’s Revocation Endpoint. This endpoint allows revoking access tokens (reference tokens only) and refresh token.
REMARK: NxtPort is using JWT tokens, which are not revocable.
introspection_endpoint
URL of the OP’s Introspection Endpoint. This endpoint can be used to validate reference tokens.
REMARK: NxtPort is using JWT tokens instead of reference tokens.
device_authorization_endpoint
URL of the provider’s Device Authorization Endpoint. This endpoint can be used to request device and user codes. It is used to start the device flow authorization process.
frontchannel_logout_supported
Boolean value specifying whether the OP supports HTTP-based logout, with true indicating support.
frontchannel_logout_session_supported
Boolean value specifying whether the OP can pass iss and sid query parameters to identity the RP session with the OP when frontchannel_logout_uri is used. If supported, the sid claim is also included in ID Tokens issued by the provider.
backchannel_logout_supported
Boolean value specifying whether the OP supports back-channel logout, with true indicating support.
backchannel_logout_session_supported
Boolean value specifying whether the OP can pass a sid claim in the logout token to identify the RP session whit the OP. If supported, the sid claim is also included in ID Tokens issued by the provider.
scopes_supported
JSON array containing a list of OAuth 2.0 scope values that this server supports. The server must support the openid scope value.
claims_supported
JSON array containing a list of the Claim Names of the Claims that the OpenID Provider may be able to supply values for. Note that for privacy or other reasons, this might not be an exhaustive list.
grant_types_supported
JSON array containing a list of the OAuth 2.0 Grant Type values that this OP supports.
resonse_types_supported
JSON array containing a list of the OAuth 2.0 response_type values that this OP supports.
response_modes_supported
JSON array containing a list of the OAuth 2.0 response_mode values that this OP supports.
token_endpoint_auth_methods_supported
JSON array containing a list of Client Authentication methods supported by this Token Endpoint.
id_token_signing_alg_values_supported
JSON array containing a list of the JWS signing algorithms (alg values) supported by the OP for the ID Token to encode the Claims in a JWT.
subject_types_supported
JSON array containing a list of Subject Identifier types that this OP supports.
code_challenge_methods_supported
JSON array containing a list of PKCE code challenge methods supported by this OP.
request_paramter_supported
Boolean value specifying whether the OP supports use of the request parameter, with true indicating support.
Requesting Claims Using Scope Values
OpenID Connect Clients use Scope Values to specify what access privileges are being requested for Access Tokens. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints. Protected Resource endpoints may perform different actions and return different information based on the scope values and other parameters used when requesting the presented Access Token.
For OpenID Connect, scopes can be used to request that specific sets of information be made available as Claim Values.
Multiple scope values may be used by creating a space delimited, case sensitive list of ASCII scope values.
UserInfo Endpoint
The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User. To obtain the requested Claims about the End-User, the Client makes a request to the UserInfo Endpoint using an Access Token obtained through OpenID Connect Authentication. These Claims are represented by a JSON object that contians a collection of name and value pairs for the Claims.
Claims
The pre-defined sets of Claims can be requested using specific scope values.
Following table shows the correlation between these scopes and claim values.
Scope | Claim | Type | Description |
|---|---|---|---|
openid | sub | string | Subject. Identifier for the End-User at the Issuer. |
profile | name | string | End-User's full name in displayable form including all name parts. |
profile | given_name | string | Given name(s) or first name(s) of the End-User. |
profile | family_name | string | Surname(s) or last name(s) of the End-User. |
profile | locale | string | End-User's locale, represented as a BCP47 language tag. This is typically an ISO 639-1 Alpha-2 language code in lowercase and an ISO 3166-1 Alpha-2 country code in uppercase, separated by a dash. |
profile | updated_at | number | Time the End-User's information was last updated. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. |
profile | nxt:entity:street | string | ? Street of the preferred postal address for the NxtPort-Entity. |
profile | nxt:user:email | string | End-User's preferred e-mail address. |
string | End-User's preferred e-mail address. | ||
address | country | Not used at this time. | |
address | locality | Not used at this time. | |
address | postal_code | Not used at this time. | |
address | region | Not used at this time. | |
address | street_address | Not used at this time. | |
phone | phone_number | string | End-User's preferred telephone number. |
roles | role | Not used at this time. | |
nxt:user | nxt:user:email | string | End-User's preferred e-mail address. |
nxt:user | nxt:user:externalId | string | ? |
nxt:user | nxt:user:firstName | string | Given name(s) or first name(s) of the End-User. |
nxt:user | nxt:user:fullName | string | End-User's full name in displayable form including all name parts. |
nxt:user | nxt:user:id | string | ? |
nxt:user | nxt:user:idp | string | ? Identity provider used by the End-User to login. |
nxt:user | nxt:user:lastName | string | Surname(s) or last name(s) of the End-User. |
nxt:user | nxt:user:phone | string | End-User's preferred telephone number. |
nxt:user | nxt:user:updatedAt | Not used at this time. | |
nxt:entity | nxt:entity:city | string | ? City of the preferred postal address for the NxtPort-Entity. |
nxt:entity | nxt:entity:country | string | ? Country of the preferred postal address for the NxtPort-Entity. |
nxt:entity | nxt:entity:domain | string | ? NxtPort-Entity’s preferred e-mail address domain. |
nxt:entity | nxt:entity:id | string | ? |
nxt:entity | nxt:entity:name | string | ? NxtPort-Entity’s name. |
nxt:entity | nxt:entity:number | string | ? House number of the preferred postal address for the NxtPort-Entity. |
nxt:entity | nxt:entity:street | string | ? Street of the preferred postal address for the NxtPort-Entity. |
nxt:entity | nxt:entity:trustLevel | string | ? |
nxt:entity | nxt:entity:updatedAt | Not used at this time. | |
nxt:entity | nxt:entity:vat | string | ? NxtPort-Entity’s VAT. |
nxt:entity | nxt:entity:zipCode | string | ? Zip code of the preferred postal address for the NxtPort-Entity. |
Glossary
IdentityServer4
An OpenID Connect and OAuth 2.0 framework for ASP.NET Core.
OAuth 2.0
The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.
OIDC
OpenID Connect. This is a protocol that allow web applications (also called relying parties, or RP) to authenticate users with an external server called the OpenID Connect Provider (OP).
OP
OpenID Connect Provider. See OIDC.
NxtPort uses IdentityServer4 as OpenID Connect Provider.
PKCE
OAuth 2.0 public clients utilizing the Authorization Code Grant are susceptible to the authorization code interception attack. You can mitigate against the thread through the use of Proof Key for Code Exchange (PKCE, pronounced “pixy”).
RP
Relying parties. See OIDC.
External Links
OpenID Connect Provider
IdentityServer4
OpenID Connect
OpenID Connect Core
OpenID Connect Discovery
OpenID Connect Session Management
OpenID Connect Front-Channel Logout
OpenID Connect Back-Channel Logout
OAuth 2.0
OAuth 2.0 Authorization Server Metadata
Proof Key for Code Exchange by OAuth Public Clients