OpenID Connect

This part of the documentation covers the specification of OpenID Connect.

  1. http://openid.net/specs/openid-connect-core-1_0.html

Shortcut Functions

Some easy to use functions for parsing and validating id_token JWS text.

authlib.specs.oidc.parse_id_token(id_token, key)

Parse an id_token text string into token dict.

Parameters:
  • id_token – A JWS text that represent current id_token.
  • key – A PEM key to parse the given id_token. This value can be: * a string text of PEM key * a dict/string of JWK * a set/list/tuple of JWK
Returns:

(token, header)

authlib.specs.oidc.validate_id_token(token, response_type='code', header=None, issuers=None, client_id=None, nonce=None, max_age=None, now=None)

Validate the parsed id_token.

Parameters:
  • token – The parsed id_token dict.
  • response_type – Current OAuth response_type.
  • header – The header parsed from id_token JWS.
  • issuers – A string or list to validate for iss in id_token.
  • client_id – OAuth client_id string to validate aud in id_token.
  • nonce – OAuth nonce string to validate nonce in id_token.
  • max_age – A max_age parameter in OAuth authorization.
  • now – Current timestamp to validate exp in id_token.
Returns:

IDToken

authlib.specs.oidc.verify_id_token(response, key, response_type='code', issuers=None, client_id=None, nonce=None, max_age=None)

Parse and validate id_token in response.

ID Token

class authlib.specs.oidc.IDToken(token)

ID Token model, per Section 2 and other sections of the OpenID Connect Core spec.

Parameters:token – Parsed token dict from id_token string.
acr

OPTIONAL. Authentication Context Class Reference. String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied. The value “0” indicates the End-User authentication did not meet the requirements of ISO/IEC 29115 level 1. Authentication using a long-lived browser cookie, for instance, is one example where the use of “level 0” is appropriate. Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value. An absolute URI or an RFC 6711 registered name SHOULD be used as the acr value; registered names MUST NOT be used with a different meaning than that which is registered. Parties using this claim will need to agree upon the meanings of the values used, which may be context-specific. The acr value is a case sensitive string.

amr

OPTIONAL. Authentication Methods References. JSON array of strings that are identifiers for authentication methods used in the authentication. For instance, values might indicate that both password and OTP authentication methods were used. Parties using this claim will need to agree upon the meanings of the values used, which may be context-specific. The amr value is an array of case sensitive strings.

aud

REQUIRED. Audience(s) that this ID Token is intended for. It MUST contain the OAuth 2.0 client_id of the Relying Party as an audience value. It MAY also contain identifiers for other audiences. In the general case, the aud value is an array of case sensitive strings. In the common special case when there is one audience, the aud value MAY be a single case sensitive string.

auth_time

Time when the End-User authentication occurred. 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. When a max_age request is made or when auth_time is requested as an Essential Claim, then this Claim is REQUIRED; otherwise, its inclusion is OPTIONAL.

azp

OPTIONAL. Authorized party - the party to which the ID Token was issued. If present, it MUST contain the OAuth 2.0 Client ID of this party. This Claim is only needed when the ID Token has a single audience value and that audience is different than the authorized party. It MAY be included even when the authorized party is the same as the sole audience. The azp value is a case sensitive string containing a StringOrURI value.

exp

REQUIRED. Expiration time on or after which the ID Token MUST NOT be accepted for processing. The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. 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. See RFC 3339 for details regarding date/times in general and UTC in particular.

iat

REQUIRED. Time at which the JWT was issued. 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.

iss

REQUIRED. Issuer Identifier for the Issuer of the response. The iss value is a case sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components.

nonce

String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. If present in the ID Token, Clients MUST verify that the nonce Claim Value is equal to the value of the nonce parameter sent in the Authentication Request. If present in the Authentication Request, Authorization Servers MUST include a nonce Claim in the ID Token with the Claim Value being the nonce value sent in the Authentication Request. Authorization Servers SHOULD perform no other processing on nonce values used. The nonce value is a case sensitive string.

sub

REQUIRED. Subject Identifier. A locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the Client, e.g., 24400320 or AItOawmwtWwcT0k51BayewNvutr. It MUST NOT exceed 255 ASCII characters in length. The sub value is a case sensitive string.

validate(issuers=None, client_id=None, nonce=None, max_age=None, now=None, **kwargs)

ID Token Validation, per Section 3.1.3.7.

class authlib.specs.oidc.CodeIDToken(token)

Implement IDToken when using the Code Flow. Per Sectin 3.1.3.6.

at_hash

OPTIONAL. Access Token hash value. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the ID Token’s JOSE Header. For instance, if the alg is RS256, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url encode them. The at_hash value is a case sensitive string.

class authlib.specs.oidc.ImplicitIDToken(token)

Implement IDToken when using the Implicit Flow. Per Section 3.2.2.10

at_hash

Access Token hash value. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the ID Token’s JOSE Header. For instance, if the alg is RS256, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url encode them. The at_hash value is a case sensitive string.

nonce

Use of the nonce Claim is REQUIRED for this flow.

validate_at_hash(header)

If the ID Token is issued from the Authorization Endpoint with an access_token value, which is the case for the response_type value id_token token, this is REQUIRED; it MAY NOT be used when no Access Token is issued, which is the case for the response_type value id_token.

class authlib.specs.oidc.HybridIDToken(token)

Implement IDToken when using the Hybrid Flow. Per Section 3.3.2.11.

c_hash

Code hash value. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the code value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the ID Token’s JOSE Header. For instance, if the alg is HS512, hash the code value with SHA-512, then take the left-most 256 bits and base64url encode them. The c_hash value is a case sensitive string. If the ID Token is issued from the Authorization Endpoint with a code, which is the case for the response_type values code id_token and code id_token token, this is REQUIRED; otherwise, its inclusion is OPTIONAL.

validate_at_hash(header)

If the ID Token is issued from the Authorization Endpoint with an access_token value, which is the case for the response_type value code id_token token, this is REQUIRED; otherwise, its inclusion is OPTIONAL.