News

OAuth 2.1 & OIDC

Bryce Groff

• 22 min read
OAuth 2.1 & OIDC

Certainly, an OpenID Connect ID Token is a JSON Web Token (JWT) that contains information about the authenticated user. Here's an example of an ID Token:Copy codeeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaXNzIjoiaHR0cDovL3NlcnZlci5jb20iLCJhdWQiOiJodHRwOi8vYXBpLmNvbSIsImV4cCI6MTYxODkzNzk2NiwiaWF0IjoxNjE4OTM1NzY2fQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Here's a breakdown of each part of the ID Token:

  1. Header: The header contains metadata about the JWT, such as the algorithm used for signing the token. In this example, the header is:jsonCopy code{  "alg": "HS256",  "typ": "JWT"}

You can find more information about the header in the JWT specification RFC7519.

  1. Payload: The payload contains information about the authenticated user, such as their user ID, name, and other optional claims. In this example, the payload is:jsonCopy code{  "sub": "1234567890",  "name": "John Doe",  "iss": "http://server.com",  "aud": "http://api.com",  "exp": 1618937966,  "iat": 1618935766}

You can find a list of standard claims in the OpenID Connect specification OIDC Core.

  1. Signature: The signature is used to verify the integrity of the token and ensure that it hasn't been tampered with. In this example, the signature is:Copy codeSflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

You can find more information about JWT signatures in the JWT specification RFC7519.

Overall, the OpenID Connect ID Token provides a standardized way of transmitting user identity information between parties in a secure and interoperable manner.

Bryce Groff

What is required in the payload

The OpenID Connect specification defines a set of standard claims that are required or recommended to be included in the ID Token's payload. The required claims are:

  1. iss: The issuer identifier of the ID Token's issuer. This claim is required, and its value must be the same as the iss value in the OIDC Provider's discovery document.
  2. sub: The subject identifier of the authenticated user. This claim is required, and its value must be a unique identifier for the user that has been authenticated.
  3. aud: The audience(s) that the ID Token is intended for. This claim is required, and its value must be the client ID of the Relying Party (RP) that requested the ID Token.
  4. exp: The expiration time of the ID Token. This claim is required, and its value must be a UNIX timestamp representing the date and time when the ID Token expires.
  5. iat: The time when the ID Token was issued. This claim is required, and its value must be a UNIX timestamp representing the date and time when the ID Token was issued.

Additionally, there are some recommended claims that may be included in the ID Token's payload, depending on the requirements of the use case. These recommended claims include:

  1. nonce: A random string value that was sent by the RP in the authentication request. This claim is recommended, and its value must be included in the ID Token's payload if it was included in the authentication request.
  2. auth_time: The time when the user was authenticated. This claim is recommended, and its value must be included in the ID Token's payload if it's available.
  3. acr: The authentication context class reference value that was used in the authentication request. This claim is recommended, and its value must be included in the ID Token's payload if it was included in the authentication request.
  4. amr: The authentication methods that were used in the authentication process. This claim is recommended, and its value must be included in the ID Token's payload if it's available.
  5. azp: The authorized party identifier that was granted access to the user's information. This claim is recommended, and its value must be included in the ID Token's payload if the client is a public client and it's not included in the aud claim.
Bryce Groff

Please link the additional claims section of the specification

Certainly, the additional claims that may be included in the OpenID Connect ID Token's payload are described in section 5.1 of the OpenID Connect Core specification, which you can find at the following link:

https://openid.net/specs/openid-connect-core-1_0.html#AdditionalClaims

This section provides more detailed information about each of the recommended claims that can be included in the ID Token's payload, along with their expected format and possible values. It also notes that custom claims may be included in the payload, as long as they are registered in the OIDC Provider's discovery document and follow the naming convention defined in the specification.

In general, it's recommended to use the standard claims whenever possible, as they are widely supported by OIDC Providers and Relying Parties, and can help ensure interoperability and compatibility between different implementations. However, in some cases, additional claims may be necessary to provide more context or information about the authenticated user, and the specification provides a flexible mechanism for including them in the ID Token's payload.

Bryce Groff

Please link the recommended hashing algorithm

The recommended hashing algorithm for generating OpenID Connect ID Tokens is specified in section 8.5 of the OpenID Connect Core specification.

According to the specification, ID Tokens must be signed using either the RS256 or ES256 algorithm. RS256 is a SHA-256 based RSA signature algorithm, while ES256 is a SHA-256 based ECDSA signature algorithm.

Here is the link to section 8.5 of the specification:

https://openid.net/specs/openid-connect-core-1_0.html#Signing

Note that while these are the recommended signature algorithms for ID Tokens, other algorithms may be used as long as they are supported by both the OIDC Provider and the Relying Party. The choice of algorithm may depend on factors such as security requirements, performance considerations, and regulatory compliance requirements.

Bryce Groff

What is the difference between the id token and the access token

In OpenID Connect, the ID Token and Access Token are both tokens that are issued by the OpenID Connect Provider (OP) as part of the OAuth 2.0 flow. While they serve different purposes, they are both important components of the OpenID Connect protocol.

The ID Token is a JSON Web Token (JWT) that contains information about the authenticated user. It is intended to provide information about the user to the Relying Party (RP) without requiring the RP to make additional requests to the OpenID Connect Provider. The ID Token typically includes information such as the user's unique identifier, the issuer identifier, and other claims that describe the user's authentication context. The ID Token is always a bearer token, meaning it is simply presented by the RP to the OP as proof of authentication.

The Access Token, on the other hand, is a token that is used to access protected resources on behalf of the authenticated user. It is intended to provide authorization to access resources, rather than information about the user. The Access Token is typically issued with a scope that defines the level of access that the RP is authorized to have. The Access Token may be a bearer token, or it may be a proof of possession token, depending on the type of token used and the requirements of the RP.

In summary, the main difference between the ID Token and Access Token is that the ID Token provides information about the authenticated user, while the Access Token provides authorization to access protected resources on behalf of the authenticated user.

Bryce Groff

When initiating an authorization code flow with an oauth 2.1 authorization server. What query parameters are required?

OAuth 2.1 is not a formal specification at the moment, and there is no such version of the OAuth 2.0 specification. However, I can provide an answer based on the requirements specified in the OAuth 2.0 specification, which is widely used and accepted.

When initiating an authorization code flow with an OAuth 2.0 authorization server, the following query parameters are typically required:

  1. response_type: This parameter must be set to code, which indicates that the authorization server should return an authorization code to the client.
  2. client_id: This parameter is used to identify the client application that is making the request. It must be registered with the authorization server in advance.
  3. redirect_uri: This parameter specifies the URI to which the authorization server should redirect the user-agent after the user grants or denies consent. It must be registered with the authorization server in advance.
  4. scope: This parameter specifies the level of access that the client application is requesting. It is an optional parameter, but is commonly used in practice.
  5. state: This parameter is an opaque value that is used to maintain state between the request and callback. It is an optional parameter, but it is strongly recommended to use it to prevent CSRF attacks.

Here is an example of how these parameters might be included in an authorization request URL:sqlCopy codehttps://authorization-server.com/oauth2/authorize? response_type=code &client_id=CLIENT_ID &redirect_uri=REDIRECT_URI &scope=SCOPE  &state=STATE

Note that the exact parameter names and format may vary depending on the authorization server implementation, but the basic concepts and requirements should be similar.

Bryce Groff

Please link the part of of specification that defines these parameters.

Sure, here are the sections of the OAuth 2.0 specification that define the query parameters required for initiating an authorization code flow:

  1. response_type: This parameter is defined in section 3.1.1 of the OAuth 2.0 Authorization Framework specification: https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.1
  2. client_id: This parameter is defined in section 2.2 of the OAuth 2.0 Dynamic Client Registration Protocol specification: https://datatracker.ietf.org/doc/html/rfc7591#section-2.2
  3. redirect_uri: This parameter is defined in section 3.1.2 of the OAuth 2.0 Authorization Framework specification: https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2
  4. scope: This parameter is defined in section 3.3 of the OAuth 2.0 Authorization Framework specification: https://datatracker.ietf.org/doc/html/rfc6749#section-3.3
  5. state: This parameter is defined in section 4.1.1 of the OAuth 2.0 Authorization Framework specification: https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1

Note that the links provided above are to the latest versions of the relevant specifications as of my knowledge cutoff date, which was September 2021. The specifications may be updated in the future, so you may want to check for the latest versions of the specifications to ensure you have the most up-to-date information.

Bryce Groff

When requesting an access token with an authorization code, what parameters are required?

When requesting an access token with an authorization code in OAuth 2.0, the following parameters are typically required:

  1. grant_type: This parameter must be set to authorization_code, which indicates that the client is requesting an access token using an authorization code.
  2. code: This parameter contains the authorization code that was issued by the authorization server in response to the initial authorization request.
  3. redirect_uri: This parameter is required and must match the redirect URI that was used in the initial authorization request.
  4. client_id: This parameter is required and identifies the client application that is making the request.
  5. client_secret: This parameter is required if the client application has been issued a client secret by the authorization server. The client secret is a shared secret between the client and the authorization server, used for authentication.

Here's an example of how these parameters might be included in a token request:bashCopy codePOST /oauth2/token HTTP/1.1 Host: authorization-server.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &code=AUTHORIZATION_CODE &redirect_uri=REDIRECT_URI &client_id=CLIENT_ID &client_secret=CLIENT_SECRET

Note that the exact parameter names and format may vary depending on the implementation of the authorization server, but the basic concepts and requirements should be similar.

Bryce Groff

Please link the parts of the specification that describe the parameters.

Sure, here are the sections of the OAuth 2.0 specification that describe the parameters required for requesting an access token with an authorization code:

  1. grant_type: This parameter is defined in section 4.1.3 of the OAuth 2.0 Authorization Framework specification: https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3
  2. code: This parameter is defined in section 4.1.3 of the OAuth 2.0 Authorization Framework specification: https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3
  3. redirect_uri: This parameter is defined in section 3.1.3 of the OAuth 2.0 Authorization Framework specification: https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.3
  4. client_id: This parameter is defined in section 2.2 of the OAuth 2.0 Dynamic Client Registration Protocol specification: https://datatracker.ietf.org/doc/html/rfc7591#section-2.2
  5. client_secret: This parameter is defined in section 2.3.1 of the OAuth 2.0 Dynamic Client Registration Protocol specification: https://datatracker.ietf.org/doc/html/rfc7591#section-2.3.1

Note that the links provided above are to the latest versions of the relevant specifications as of my knowledge cutoff date, which was September 2021. The specifications may be updated in the future, so you may want to check for the latest versions of the specifications to ensure you have the most up-to-date information.

Bryce Groff

What is a device_token in oauth 2.0

In OAuth 2.0, a device_token is a type of token that is used in the Device Authorization Grant flow. This flow is used when the user is unable to interact with a device's user interface, such as a TV or an IoT device, in order to authenticate themselves to the authorization server.

In the Device Authorization Grant flow, the device requests an authorization code from the authorization server on behalf of the user. The authorization server responds with a user code and a device code. The user then goes to a separate device, such as a smartphone or computer, to enter the user code and authenticate themselves to the authorization server.

Once the user has authenticated, the authorization server issues an access token to the device. This access token is known as the device_token, and it can be used by the device to make API requests on behalf of the user.

The device_token is similar to other types of access tokens in OAuth 2.0, in that it provides authorization for the device to access specific resources on behalf of the user. However, it is issued and used in a specific flow that is designed for devices with limited user interfaces.

Bryce Groff

What document is the device_token described in

The Device Authorization Grant flow and the device_token are described in the OAuth 2.0 Device Authorization Grant specification. The specification defines a new grant type, called the "device_code" grant type, which is used to obtain an access token in situations where the user is not able to directly authenticate themselves to the authorization server. The specification can be found at the following link:

The device_token is not specifically defined as a term in the specification, but it is used to refer to the access token that is issued to the device in the Device Authorization Grant flow. The specification describes the flow and the parameters used in the flow, including the device_code, the user_code, and the interval parameter that the device can use to poll the authorization server for the device_token.

Bryce Groff

What is pkce and how can it be used with the authorization code flow.

PKCE stands for "Proof Key for Code Exchange". It is an extension to the OAuth 2.0 Authorization Code flow that is designed to prevent certain types of attacks, such as code interception and replay attacks.

In the standard OAuth 2.0 Authorization Code flow, a client application requests authorization from a user and receives an authorization code from the authorization server. The client then exchanges the authorization code for an access token. However, this flow is vulnerable to attacks where an attacker can intercept the authorization code and use it to obtain an access token for themselves.

PKCE addresses this vulnerability by requiring the client to generate a random cryptographic code verifier and hash it using a hashing algorithm, such as SHA-256. The client then sends the hash, known as the "code challenge", along with the authorization request to the authorization server. When the authorization server issues the authorization code, it also includes a "code challenge method" that indicates the hashing algorithm used to hash the code verifier. The client must then send the original code verifier to the authorization server when exchanging the authorization code for an access token, so that the server can verify that the code verifier matches the code challenge.

To use PKCE with the Authorization Code flow, the client must add two additional parameters to the authorization request: code_challenge and code_challenge_method. The code_challenge parameter is the hashed code verifier, and the code_challenge_method parameter specifies the hashing algorithm used to hash the code verifier. The authorization server must also support PKCE and validate the code verifier and challenge when exchanging the authorization code for an access token.

PKCE provides an additional layer of security to the Authorization Code flow, making it more difficult for attackers to intercept and use the authorization code to obtain an access token.

Bryce Groff

Please link the parts of the specification that describe the pkce parameters

The PKCE extension to the OAuth 2.0 Authorization Code flow is described in RFC 7636, which specifies the code_challenge and code_challenge_method parameters. The relevant sections of the specification are:

  • Section 1: Introduction, which provides an overview of PKCE and the motivation for its use.
  • Section 4.1: Authorization Request, which describes how the client includes the code_challenge and code_challenge_method parameters in the authorization request.
  • Section 4.2: Authorization Response, which describes how the authorization server includes the code_challenge and code_challenge_method in the authorization response.
  • Section 4.3: Token Request, which describes how the client includes the original code_verifier in the token request.
  • Section 4.4: Token Response, which describes how the authorization server verifies the code_verifier and returns an access token.

Here is a link to RFC 7636:

Bryce Groff

When using pkce to get an access token, do I need to provide the client_secret?

Whether or not the client needs to provide a client_secret when using PKCE to obtain an access token depends on the OAuth 2.0 server implementation and the client type.

In the standard OAuth 2.0 Authorization Code flow, the client typically needs to provide a client_secret when exchanging the authorization code for an access token. However, in the case of a public client, such as a native mobile or desktop application, it may not be possible to securely store and transmit the client_secret. In this case, the client can use PKCE to obtain an access token without using a client_secret.

In the PKCE flow, the client includes a hashed value called the code_challenge parameter in the authorization request. When the client exchanges the authorization code for an access token, it sends the original code verifier to the authorization server, which uses it to validate the code_challenge. If the code_challenge matches the code verifier, the server issues an access token.

Some OAuth 2.0 server implementations require the client to provide a client_secret even when using PKCE, while others do not. If the server requires a client_secret, the client must include it in the token request. However, if the server does not require a client_secret, the client can omit it from the token request.

In summary, whether or not a client_secret is required when using PKCE to obtain an access token depends on the specific OAuth 2.0 server implementation and the type of client used.

Bryce Groff

In what specification is the well know endpoints described.

The "well-known" URI specification for OAuth 2.0 is defined in RFC 8414. This specification defines a set of standardized URIs that can be used by clients to discover information about an OAuth 2.0 server. These URIs are known as "well-known" URIs, and they are used to provide information such as the server's authorization and token endpoints, as well as the server's public keys for verifying signed tokens.

The well-known URI specification defines the following URIs:

  • .well-known/oauth-authorization-server: This URI provides information about the server's authorization endpoint, including the supported authorization flows and client types.
  • .well-known/oauth-token-endpoint: This URI provides information about the server's token endpoint, including the supported token grant types.
  • .well-known/oauth-public-keys: This URI provides the public keys used by the server to sign and verify tokens.

Here is a link to RFC 8414:

Bryce Groff

Show the oidc well known specification

The OpenID Connect (OIDC) specification defines a set of "well-known" URIs that clients can use to discover information about an OIDC provider. These URIs are similar to the ones defined in the OAuth 2.0 well-known URI specification. The OIDC well-known URIs are defined in section 4.2 of the OIDC Core specification.

The following are the well-known URIs defined by OIDC:

  • /.well-known/openid-configuration: This URI provides information about the OIDC provider's configuration, including the provider's authorization and token endpoints, supported scopes, and other metadata.
  • /.well-known/jwks.json: This URI provides the public keys used by the OIDC provider to sign and verify JSON Web Tokens (JWTs).

Here is a link to the OIDC Core specification:

Bryce Groff

Show the authorization servers endpoints as described in the oidc specification.

The OpenID Connect (OIDC) specification defines several endpoints that are used by the authorization server to perform authentication and provide information about the OIDC provider. These endpoints are described in section 3 of the OIDC Core specification. The following is a list of the main endpoints:

  • Authorization Endpoint: This endpoint is used to initiate the authorization flow. Clients send users to this endpoint to request authorization to access protected resources on their behalf. The endpoint URL is typically obtained from the OIDC provider's /.well-known/openid-configuration endpoint.
  • Token Endpoint: This endpoint is used by clients to exchange an authorization code for an access token. It can also be used to obtain a refresh token. The endpoint URL is typically obtained from the OIDC provider's /.well-known/openid-configuration endpoint.
  • UserInfo Endpoint: This endpoint is used to obtain information about the authenticated user. Clients can send an access token to this endpoint to retrieve user profile information. The endpoint URL is typically obtained from the OIDC provider's /.well-known/openid-configuration endpoint.
  • End Session Endpoint: This endpoint is used to initiate the logout flow. Clients can send users to this endpoint to log them out of the OIDC provider. The endpoint URL is typically obtained from the OIDC provider's /.well-known/openid-configuration endpoint.
  • JWKs Endpoint: This endpoint is used to obtain the public keys used to sign and verify JSON Web Tokens (JWTs) issued by the OIDC provider. The endpoint URL is typically obtained from the OIDC provider's /.well-known/openid-configuration endpoint.

Here is a link to the OIDC Core specification:

Bryce Groff

Please link each endpoint to the part where it appears in the specification.

Certainly, here are the links to the relevant sections of the OpenID Connect Core specification that describe each of the endpoints:

Bryce Groff

Does oidc specify the format of the access token?

Yes, the OpenID Connect (OIDC) specification does specify the format of the access token. The access token is a JSON Web Token (JWT), which is a compact and self-contained way of transmitting information between parties as a JSON object. The JWT format is defined in RFC 7519, and OIDC builds on this standard by defining the specific claims that should be included in the access token.

In OIDC, the access token is issued by the authorization server and contains information about the authenticated user and the authorization context. The access token is then sent to the client, which can use it to access protected resources on the user's behalf. The specific format of the access token, including the claims that should be included, is defined in section 5.1 of the OIDC Core specification.

Here is a link to the relevant section of the OIDC Core specification:

Bryce Groff

Please show all of the claims defined in the oidc specification for access tokens

Certainly, here are the standard claims defined in the OpenID Connect (OIDC) specification that can be included in the access token:

  • "iss" (Issuer): The issuer identifier for the authorization server that issued the access token.
  • "sub" (Subject): The identifier for the authenticated user.
  • "aud" (Audience): The intended audience for the access token, typically the client that requested the token.
  • "exp" (Expiration Time): The expiration time for the access token, after which it should not be accepted for authentication.
  • "iat" (Issued At): The time at which the access token was issued.
  • "auth_time" (Authentication Time): The time at which the user was authenticated.
  • "nonce": A random value that the client included in the authentication request, which is echoed back in the access token to help prevent replay attacks.
  • "acr" (Authentication Context Class Reference): A value that specifies the authentication context class that was used for the authentication.
  • "amr" (Authentication Methods References): An array of values that specify the authentication methods that were used for the authentication.
  • "azp" (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.

Note that these claims are not required, and additional custom claims can be included in the access token as needed.

Here is a link to the relevant section of the OIDC Core specification:

Bryce Groff

What scopes are defined in the oidc specification

The OpenID Connect (OIDC) specification defines several standard scopes that can be used in authorization requests. Here is a list of the standard scopes defined in OIDC:

  • "openid": This scope is required for all OIDC requests, and indicates that the client is requesting an ID Token that contains authentication information about the user.
  • "profile": This scope requests access to the user's basic profile information, such as their name and profile picture.
  • "email": This scope requests access to the user's email address.
  • "address": This scope requests access to the user's address information, such as their street address, city, and postal code.
  • "phone": This scope requests access to the user's phone number.

In addition to these standard scopes, OIDC allows for custom scopes to be defined and used in authorization requests.

Here is a link to the relevant section of the OIDC Core specification:

Bryce Groff

What rfc describes the nonce parameter in oauth 2.0

The "nonce" parameter is not part of the OAuth 2.0 specification itself, but it is a required parameter in OpenID Connect (OIDC) authentication requests, which builds on top of OAuth 2.0.

The use of the "nonce" parameter in OIDC is defined in the OpenID Connect Core specification, which is based on several RFCs including:

  • RFC 6749 - The OAuth 2.0 Authorization Framework
  • RFC 7519 - JSON Web Token (JWT)
  • RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients

Here is a link to the relevant section of the OIDC Core specification that describes the "nonce" parameter:

What are the primary documents that describe oidc

The primary documents that describe OpenID Connect (OIDC) are:

  1. OpenID Connect Core specification: This document defines the core features and functionality of OIDC. It describes the flows, data structures, and other aspects of the protocol, including how to obtain ID Tokens and UserInfo endpoints.
  2. OpenID Connect Discovery specification: This document defines how clients can dynamically discover the endpoints and other configuration information needed to interact with an OpenID Connect provider. This includes the provider's issuer URL, authorization and token endpoints, and supported scopes and claims.
  3. OpenID Connect Session Management specification: This document defines how to manage user sessions across multiple clients and across different devices. It provides a way for clients to receive notifications when a user logs out or when their session expires.
  4. OpenID Connect Dynamic Client Registration specification: This document defines a protocol for dynamically registering clients with an OpenID Connect provider. This allows new clients to register themselves with the provider without requiring manual configuration.
  5. JSON Web Token (JWT) specification: This document defines the JWT format, which is used extensively in OIDC for exchanging information between the various parties involved in the protocol.

Here are links to the relevant specifications:

Bryce Groff

What oauth 2.0 documents does oidc use as a base

OpenID Connect (OIDC) is built on top of OAuth 2.0, which means it relies on the core OAuth 2.0 specifications for many of its underlying features and functionality. Specifically, OIDC builds on top of the following OAuth 2.0 RFCs:

  1. RFC 6749 - The OAuth 2.0 Authorization Framework: This document defines the core concepts and functionality of OAuth 2.0, including the different grant types, token types, and error codes.
  2. RFC 6750 - The OAuth 2.0 Bearer Token Usage: This document describes how access tokens are transmitted using the Bearer token type, which is the default token type used in OAuth 2.0.
  3. RFC 7009 - OAuth 2.0 Token Revocation: This document describes a mechanism for revoking access tokens and refresh tokens.
  4. RFC 7662 - OAuth 2.0 Token Introspection: This document describes a mechanism for introspecting access tokens to determine their validity and scope.

OIDC also uses other related specifications such as JSON Web Tokens (JWTs), which are used to represent ID tokens and other types of tokens exchanged in OIDC flows.

Here are links to the relevant specifications: