Skip to content

OpenID Configuration Reference

The OpenID configuration is defined by a JSON schema.

This section describes each object in the schema.

OpenIDConfigurations

OpenIDConfigurations specifies the OpenID configurations.

Configurations [required]

Configurations is a list of one or more OpenIDConfiguration items.

Each OpenIDConfiguration item corresponds to a tenant in a multi-tenancy application.

In the more common single tenancy application, a single OpenIDConfiguration is defined.

OpenIDConfiguration

OpenIDConfiguration specifies a single OpenID configuration for an OpenID Provider with one or more clients.

Name [optional]

Each OpenIDConfiguration is identified by a unique name. This name is internal to the configuration and is not exposed to clients.

A name is only required if there are multiple OpenID configurations.

ProviderConfiguration [required]

This property specifies the ProviderConfiguration.

ClientConfigurations [required]

This property is a list of one or more ClientConfiguration items.

ProviderConfiguration

ProviderConfiguration specifies the configuration for the OpenID Provider.

Description [optional]

The OpenID Provider description.

ProviderMetadata [required]

The OpenID Provider discovery metadata.

ProviderCertificates [required]

The X.509 certificates used by the OpenID Provider to secure tokens.

AuthCodeExpiry [optional]

The authorization code expiry.

The default is ten minutes.

AccessTokenExpiry [optional]

The access token expiry.

The default is ten minutes.

IdTokenExpiry [optional]

The ID token expiry.

The default is ten minutes.

ClockSkew [optional]

The permitted clock skew between the OpeID provider and clients.

The default is five minutes.

ProviderMetadata

ProviderMetadata corresponds to the OpenID provider metadata defined in the OpenID Connect Discovery specification.

Property names are in Pascal rather than the Snake case uses in the Discovery specification.

This means the property "Issuer" is included in the metadata returned to the client as "issuer". Similarly, "AuthorizationEndpoint" is returned as "authorization_endpoint".

ClientConfiguration

ClientConfiguration specifies the configuration for a client of the OpenID Provider.

Description [optional] The client description.

ClientID [required]

The client ID uniquely identifies the client.

ClientSecret [optional]

The client secret.

RedirectUris [required]

The list of valid redirect URIs for authorization responses.

These may be specified as regular expressions, if required.

PostLogoutRedirectUris [optional]

The list of valid redirect URIs for logout responses.

These may be specified as regular expressions, if required.

RedirectUrisAreRegex [optional]

The flag specifying whether redirect URIs are regular expressions.

The default is false.

ClientCertificates [required]

The X.509n certificates used by the OpenID Provider to validate tokens sent by the client.

SignIDTokens [optional]

The flag specifying whether ID tokens should be signed.

The default is true.

EncryptIDTokens [optional]

The flag specifying whether ID tokens should be encrypted.

The default is false.

SignUserInfo [optional]

The flag specifying whether user info should be signed.

The default is true.

EncryptUserInfo [optional]

The flag specifying whether user info should be encrypted.

The default is false.

SignatureAlgorithm [optional]

The signature algorithm. For more information, refer to RFC 7518.

The default is RS256.

KeyManagementAlgorithm [optional]

The key management algorithm. For more information, refer to RFC 7518.

The default is RSA-OAEP.

EncryptionAlgorithm [optional]

The encryption algorithm. For more information, refer to RFC 7518.

The default is A128CBC-HS256.

RequireCodeChallenge [optional]

The flag specifying whether a Proof Key for Code Exchange (PKCE) code challenge is required.

The default is false.

Certificate

The certificate specifies the location and purpose of an X.509 certificate.

Certificates may be base-64 encoded strings, stored on the file system, within a Windows certificate store, or an Azure key vault.

For certificate strings, the base-64 encoded string and optional password must be specified.

For certificate files, the file name and optional password must be specified.

For certificates in a Windows certificate store, the store name and location may be specified along with one of the following: the certificate's serial number; thumb print; or subject name.

For certificates in an Azure key vault, the configuration key must be specified.

Status [optional]

The certificate status may be:

  • Retired
  • Active
  • Future

This assists with key rollover.

Only active certificates are used for signature generation or encryption.

Retired certificates are previously active certificates that are no longer in use.

Future certificates will become active at some future point in time.

All certificates are included when returning the provider’s keys as part of discovery.

The default is Active.

Use [optional]

The certificate use may be:

  • Encryption
  • Signature
  • Any

A certificate whose use is encryption may be used for encryption or decryption only.

A certificate whose use is signature may be used for signature generation or verification only.

A certificate whose use is any may be used for any purpose with no restrictions.

The default is encryption and signature.

String [optional]

The string is the certificate base-64 encoded string. This may contain the public key only or the public and private keys.

FileName [optional]

The file name is the relative or absolute path to the X.509 certificate file. This may be a CER file containing a public key only or a PFX file also containing a private key.

Password [optional]

The password protects the private key.

StoreName [optional]

For certificates in a Windows certificate store, the store name specifies the store.

The store name may be one of the standard stores:

  • AddressBook
  • AuthRoot
  • CertificateAuthority
  • Disallowed
  • My
  • Root
  • TrustedPeople
  • TrustedPublisher

Alternatively, it may be any other store including:

  • WebHosting

The default is the My (ie personal) store.

StoreLocation [optional]

For certificates in a Windows certificate store, the store location specifies the location.

The store location may be:

  • CurrentUser
  • LocalMachine

The default is the local machine.

SerialNumber [optional]

For certificates in a Windows certificate store, the certificate is specified by its serial number.

Thumbprint [optional]

For certificates in a Windows certificate store, the certificate is specified by its thumb print.

SubjectName [optional]

For certificates in a Windows certificate store, the certificate is specified by its subject name.

Key [optional]

For certificates in an Azure key vault, the certificate is specified by its configuration key.

URL

OpenID Provider metadata URLs may be absolute or relative.

URLs are relative to the host name and port number of the current HTTP request.

For example, an authorization endpoint URL may be specified absolutely.

https://localhost:44311/openid/authorize

Alternatively, it may be specified as a path.

/openid/authorize

This is converted to an absolute URL using the base URL of the current HTTP request.