International Government Assurance Profile (iGov) for OAuth 2.0

	iGov OAuth 2.0	February 2025
Burgin & Clancy	Standards Track	[Page]

Abstract

The OAuth 2.0 protocol framework defines a mechanism to allow a resource owner to delegate access to a protected resource for a client application.¶

This specification profiles the OAuth 2.0 protocol framework to increase baseline security, provide greater interoperability, and structure deployments in a manner specifically applicable, but not limited to consumer-to-government deployments.¶

1. Introduction

This document profiles the OAuth 2.0 web authorization framework for use in the context of securing web-facing application programming interfaces (APIs), particularly Representational State Transfer (RESTful) APIs. The OAuth 2.0 specifications accommodate a wide range of implementations with varying security and usability considerations, across different types of software clients. The OAuth 2.0 client, protected resource, and authorization server profiles defined in this document serve two purposes:¶

Define a mandatory baseline set of security controls suitable for a wide range of government use cases, while maintaining reasonable ease of implementation and functionality¶
Identify optional, advanced security controls for sensitive use cases where increased risk justifies more stringent controls.¶

This OAuth profile is intended to be shared broadly, and has been greatly influenced by the HEART OAuth2 Profile [HEART.OAuth2].¶

1.1. Requirements Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119] .¶

All uses of JSON Web Signature (JWS) [RFC7515] and JSON Web Encryption (JWE) [RFC7516] data structures in this specification utilize the JWS Compact Serialization or the JWE Compact Serialization; the JWS JSON Serialization and the JWE JSON Serialization are not used.¶

1.2. Terminology

This specification uses the terms "Access Token", "Authorization Code", "Authorization Endpoint", "Authorization Grant", "Authorization Server", "Client", "Client Authentication", "Client Identifier", "Client Secret", "Grant Type", "Protected Resource", "Redirection URI", "Refresh Token", "Resource Owner", "Resource Server", "Response Type", and "Token Endpoint" defined by OAuth 2.0 [RFC6749] , the terms "Claim Name", "Claim Value", and "JSON Web Token (JWT)" defined by JSON Web Token (JWT) [RFC7519] , and the terms defined by OpenID Connect Core 1.0 [OpenID.Core] .¶

1.3. Conformance

This specification defines requirements for the following components:¶

OAuth 2.0 clients.¶
OAuth 2.0 authorization servers.¶
OAuth 2.0 protected resources.¶

The specification also defines features for interaction between these components:¶

Client to authorization server.¶
Protected resource to authorization server.¶

When an iGov-compliant component is interacting with other iGov-compliant components, in any valid combination, all components MUST fully conform to the features and requirements of this specification. All interaction with non-iGov components is outside the scope of this specification.¶

An iGov-compliant OAuth 2.0 authorization server MUST support all features as described in this specification. A general-purpose authorization server MAY support additional features for use with non-iGov clients and protected resources.¶

An iGov-compliant OAuth 2.0 client MUST use all functions as described in this specification. A general-purpose client library MAY support additional features for use with non-iGov authorization servers and protected resources.¶

An iGov-compliant OAuth 2.0 protected resource MUST use all functions as described in this specification. A general-purpose protected resource library MAY support additional features for use with non-iGov authorization servers and clients.¶

1.4. Global Requirements

All network connections MUST be made using TLS 1.3 or above. Each originator of a TLS connection MUST verify the destination's certificate. Additionally, the following four TLS 1.2 cipher suites MAY be used:¶

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256¶
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384¶
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256¶
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384¶

Implementers of this profile SHOULD monitor the progress of specifications of post-quantum cryptography for TLS implementations. Implementers MAY adopt a cipher suite not included in BCP195 [BCP195] when post quantum safety is required if the cipher suite is supported in the implementation environment.¶

An example of an emerging PQ cipher suite that is broadly supported at the time of writing is X25519MLKEM768, specified by Post-quantum Hybrid Key Exchange with ML-KEM in the Internet Key Exchange Protocol Version 2 (IKEv2) [mlkem.ikev2].¶

For the authorization_endpoint, the authorization server MAY allow additional cipher suites that are permitted by the latest version of BCP195 [BCP195], if necessary to allow sufficient interoperability with users' web browsers or as required by local regulations.¶

NOTE: Permitted cipher suites are those listed in BCP195 [BCP195] that do not explicitly say MUST NOT use.¶

Endpoints for use by web browsers MUST use mechanisms to ensure that connections cannot be downgraded using TLS Stripping attacks. Protected resources MAY implement an HTTP Strict Transport Security policy as defined in HTTP Strict Transport Security (HSTS) [RFC6797] to mitigate these attacks. Protected resources SHOULD consider registering web domain names with browsers that offer browser-side ("preload") HSTS policy enforcement to further mitigate TLS downgrade attacks.¶

2. Client Profiles

2.1. Client Types

OAuth defines two client types, based on their ability to authenticate securely with the authorization server¶

confidential clients:: Clients that have credentials with the authorization server.¶
public clients:: Clients without credentials.¶

2.2. Client Type Use Cases

This specification has been designed around the following client use cases:¶

web application:: A web application is a client running on a web server. Resource owners access the client via an HTML user interface rendered in a user agent on the device used by the resource owner. The client credentials as well as any access tokens issued to the client are stored on the web server and are not exposed to or accessible by the resource owner. In this use case, web applications are confidential clients.¶
native application:: A native application is a client installed and executed on the device used by the resource owner. Protocol data and credentials are accessible to the resource owner. It is assumed that any client authentication credentials included in the application can be extracted. Dynamically issued access tokens and refresh tokens can receive an acceptable level of protection. On some platforms, these credentials are protected from other applications residing on the same device. Best current practices for native applications are detailed in OAuth 2.0 for Native Apps [RFC8252]. In this use case, native applications are public clients.¶
browser-based application:: A browser-based application is a client in which the client code is downloaded from a web server and executes within a user agent (e.g., web browser) on the device used by the resource owner. Protocol data and credentials are easily accessible (and often visible) to the resource owner. If such applications wish to use client credentials, it is recommended to utilize the backend for frontend pattern. Since such applications reside within the user agent, they can make seamless use of the user agent capabilities when requesting authorization. This use case is out of scope due to the inherent lack of security provided by browser-based applications. However, best current practices are detailed in OAuth 2.0 for Browser-Based Applications [browser-based-apps]..¶

2.3. Sender-constrained Tokens

While a bearer token can be used by anyone in possession of the token, a sender-constrained token is bound to a particular symmetric or asymmetric key issued to, or already possessed by, the client. The association of the key to the token is also communicated to the protected resource. When the client presents the token to the protected resource, it is also required to demonstrate possession of the corresponding key.¶

As described in Best Current Practice for OAuth 2.0 Security [BCP240], sender-constrained tokens could prevent a number of attacks on OAuth that entail the misuse of stolen and leaked access tokens by unauthorized parties. The attacker would need to obtain the legitimate client's cryptographic key along with the access token to gain access to protected resources.¶

All clients MUST use proof of possession to sender-constrain access tokens using either mTLS [RFC8705] or DPoP [RFC9449].¶

2.4. Authentication Context and Step-Up Authentication Challenge Protocol Support

OAuth 2.0 clients and Authorization Servers MUST support the mechanism specified in OAuth 2.0 Step Up Authentication Challenge Protocol" [RFC9470] to communicate authentication context and implement interoperable step up authentication.¶

Protected resources MAY use authentication context or step up authentication to implement access controls.¶

This profile acknowledges government use cases will likely operate within an ecosystem of authentication methods of highly variable security value for the foreseeable future by imposing requirements to enable protected resources with basic capabilities to communicate requirements for authentication strength and recency to supporting authorization clients and servers, as well as the capability to enforce access policies using access tokens augmented with the strength and recency of the authentication event that led to the issuance of each specific access token.¶

This profile will leverage the supporting server metadata, request, token claims and values, and error messages from OAuth 2.0 Step Up Authentication Challenge Protocol" [RFC9470] and OpenID Connect Core 1.0 [OpenID.Core].¶

Digital identity policies and semantic mappings to string values are required for implementation but are out of scope for this technical profile.¶

OAuth 2.0 MUST NOT be used as an authentication protocol. Use of the iGov OpenID Connect Profile" [OpenID.iGov] is RECOMMENDED to provide the identity authentication layer for iGov OAuth 2.0 delegated access use cases.¶

2.5. Client Registration

All clients MUST register with the authorization server. For client software that may be installed on multiple client instances, such as native applications or single page app (SPA), each client instance MAY receive a unique client identifier from the authorization server.¶

Client registration MAY be completed by either static configuration (out-of-band, through an administrator, etc...) or dynamically.¶

If a client uses mTLS [RFC8705] for client authentication or to sender-constrain tokens, the client MUST include the tls_client_certificate_bound_access_tokens parameter in its registration metadata.¶

If a client uses DPoP [RFC9449] to sender constrain tokens, the client MUST include the dpop_bound_access_tokens parameter in its registration metadata.¶

Clients using mTLS for client authentication or to sender-constrain tokens MUST register their TLS certificate's subject DN with the authorization server. Clients using self-signed certificate option are not guaranteed uniqueness of their certificate fingerprint.¶

2.5.1. Redirect URI

Clients using the authorization code grant type MUST register their full redirect URIs. The Authorization Server MUST validate the redirect URI given by the client at the authorization endpoint using strict string comparison.¶

A client MUST protect the values passed back to its redirect URI by ensuring that the redirect URI is one of the following:¶

Hosted on a website with Transport Layer Security (TLS) protection (a Hypertext Transfer Protocol - Secure (HTTPS) URI)¶
Hosted on a client-specific non-remote-protocol URI scheme (e.g., myapp://)¶
Hosted on the local domain of the client (e.g., http://localhost/)¶

Clients MUST use a unique redirect URI for each logical authorization server.¶

Clients MUST NOT forward values passed back to their redirect URIs to other arbitrary or user-provided URIs (a practice known as an "open redirector").¶

Refer to Best Current Practice for OAuth 2.0 Security [BCP240] Section 2.4.1 for additional guidance for implementation of edge cases.¶

2.6. Connection to the Authorization Server

2.6.1. Requests to the Authorization Endpoint

All clients MUST use the PKCE S256 code challenge method as described in Proof Key for Code Exchange by OAuth Public Clients [RFC7636] and include the "code_challenge" parameter and "code_challenge_method", set to "S256", in the authorization request. The PKCE code_verifier value MUST contain at least 128 bits of entropy.¶

Clients making a request to the authorization endpoint MUST use an unpredictable value for the state parameter with at least 128 bits of entropy. Clients MUST validate the value of the state parameter upon return to the redirect URI and MUST ensure that the state value is securely tied to the user's current session (e.g., by relating the state value to a session identifier issued by the client software to the browser).¶

Clients MUST include their full redirect URI in the authorization request. To prevent open redirection and other injection attacks, the authorization server MUST match the entire redirect URI using a direct string comparison against registered values and MUST reject requests with an invalid or missing redirect URI.¶

The client MAY specify a strength of authentication and maximum age to the authorization server that should be met when issuing an access token for the requesting client by including parameters in the authorization request:¶

acr_values: a space-separated string listing the authentication context class reference values in order of preference. The protected resource requires one of these values for the authentication event associated with the access token. As defined in Section 1.2 of OpenID Connect Core 1.0 [OpenID.Core], the authentication context conveys information about how authentication takes place (e.g., what authentication method(s) or assurance level to meet). It is out of scope of this document to determine how an organization semantically maps their digital identity practices to acr values that identify levels of assurance.¶
max_age: a non-negative integer value that indicates the allowable elapsed time in seconds since the last active authentication event associated with the access token.¶

Furthermore, if the authorization request is a follow-up to a prior request that did not meet the resource server's initial or subsequent authentication strength or recency requirements, the client should include the acr_values and/or max_age values sent by the resource server with the insuffient_user_authentication error code that specify expected strength and recency requirements to be provided to the authentication provider, such as the OpenID Provider, in a new authentication request.¶

The following is a sample response from a client to the end user's browser for the purpose of redirecting the end user to the authorization server's authorization endpoint:¶

NOTE: '\' line wrapping per RFC 8792

HTTP/1.2 302 Found
Cache-Control: no-cache
Connection: close
Content-Type: text/plain; charset=UTF-8
Date: Wed, 07 Jan 2015 20:24:15 GMT
Location: \
  https://idp-p.example.com/authorize?client_id=55f9f559-2496-49d4-b\
6c3-351a586b7484&response_type=code&scope=openid+email&redirect_uri=\
https%3A%2F%2Fclient.example.org%2Fcb&acr_values=myACR&max_age=1800\
Status: 302 Found

This causes the browser to send the following (non-normative) request to the authorization endpoint (inline wraps for display purposes only):¶

NOTE: '\' line wrapping per RFC 8792

GET /authorize?
   client_id=55f9f559-2496-49d4-b6c3-351a586b7484
  &nonce=cd567ed4d958042f721a7cdca557c30d
  &response_type=code
  &scope=openid+email
  &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb HTTP/1.1
Host: idp-p.example.com

2.6.2. Requests to the Token Endpoint

Full clients, native clients with dynamically registered keys, and direct access clients as defined above MUST authenticate to the authorization server's token endpoint using either the private_key_jwt method as defined in OpenID Connect Core [OpenID.Core] or the mutually-authenticated transport layer security (MTLS) request method defined in OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens [RFC8705]. If using the private_key_jwt method, the request MUST be a JWT assertion as defined by the JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants [RFC7523]. If using the mTLS method, the request must be made over a mutually authenticated TLS channel. For both methods, the request MUST include the following parameters:¶

iss: the client ID of the client creating the token¶
sub: the client ID of the client creating the token¶
aud: the URL of the authorization server's issuer endpoint¶
iat: the time that the token was created by the client¶
exp: the expiration time, after which the token MUST be considered invalid¶
jti: a unique identifier generated by the client for this authentication. This identifier MUST contain at least 128 bits of entropy and MUST NOT be re-used by any subsequent authentication token.¶

Additionally, if the client uses mTLS [RFC8705] for client authentication or to sender-constrain tokens, the client MUST include the following claim in the client assertion.¶

cnf: Confirmation, as defined in Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs) [RFC7800] and OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens [RFC8705]. The confirmation claim value MUST be computed using the X.509 Certificate SHA-256 Thumbprint method and include confirmation method value "x5t#256".¶

The following sample claim set illustrates the use of the required claims for a client authentication JWT as defined in this profile using the private_key_jwt authentication method; additional claims MAY be included in the claim set.¶

{
   "iss": "55f9f559-2496-49d4-b6c3-351a586b7484",
   "sub": "55f9f559-2496-49d4-b6c3-351a586b7484",
   "aud": "https://idp-p.example.com/token",
   "iat": 1418698788,
   "exp": 1418698848,
   "jti": "1418698788/107c4da5194df463e52b56865c5af34e5595"
        "cnf":{
        "x5t#S256":"A4DtL2JmUMhAsvJj5tKyn64SqzmuXbMrJa0n761y5v0"
        }
           }

The JWT assertion MUST be signed by the client using the client's private key. See Section 2.5 for mechanisms by which the client can make its public key known to the server. The authorization server MUST support the RS256 signature method (the Rivest, Shamir, and Adleman (RSA) signature algorithm with a 256-bit hash) and MAY use other asymmetric signature methods listed in the JSON Web Algorithms (JWA [RFC7518]) ) specification.¶

The following sample JWT contains the above claims and has been signed using the RS256 JWS algorithm and the client's own private key (with line breaks for display purposes only):¶

NOTE: '\' line wrapping per RFC 8792

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.ew0KICAgImlzcyI6ICI1NWY5ZjU1OS0\
yNDk2LTQ5ZDQtYjZjMy0zNTFhNTg2Yjc0ODQiLA0KICAgInN1YiI6ICI1NWY5ZjU1OS0\
yNDk2LTQ5ZDQtYjZjMy0zNTFhNTg2Yjc0ODQiLA0KICAgImF1ZCI6ICJodHRwczovL2l\
kcC1wLmV4YW1wbGUuY29tL3Rva2VuIiwNCiAgICJpYXQiOiAxNDE4Njk4Nzg4LA0KICA\
gImV4cCI6IDE0MTg2OTg4NDgsDQogICAianRpIjogIjE0MTg2OTg3ODgvMTA3YzRkYTU\
xOTRkZjQ2M2U1MmI1Njg2NWM1YWYzNGU1NTk1Ig0KfQ.t-_gX8JQGq3G2OEc2kUCQ8zV\
j7pqff87Sua5nktLIHj28l5onO5VpsL4sRHIGOvrpo7XO6jgtPWy3iLXv3-NLyo1TWHb\
tErQEGpmf7nKiNxVCXlGYJXSDJB6shP3OfvdUc24urPJNUGBEDptIgT7-Lhf6BbwQNlM\
QubNeOPRFDqQoLWqe7UxuI06dKX3SEQRMqcxYSIAfP7CQZ4WLuKXb6oEbaqz6gL4l6p8\
3G7wKGDeLETOTHszt-ZjKR38v4F_MnSrx8e0iIqgZwurW0RtetEWvynOCJXk-p166T7q\
ZR45xuCxgOotXY6O3et4n77GtgspMgOEKj3b_WpCiuNEwQ

This is sent in the request to the token endpoint as in the following example:¶

POST /token HTTP/1.1
NOTE: '\' line wrapping per RFC 8792

Content-Type: application/x-www-form-urlencoded
User-Agent: Rack::OAuth2 (1.0.8.7) (2.5.3.2, ruby 2.1.3 (2014-09-19))
Accept: */*
Date: Tue, 16 Dec 2014 02:59:48 GMT
Content-Length: 884
Host: idp-p.example.com

grant_type=authorization_code
&code=sedaFh
&scope=openid+email
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertio\
n-type%3Ajwt-bearer
&client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.ew0KICAgImlzc\
yI6ICI1NWY5ZjU1OS0yNDk2LTQ5ZDQtYjZjMy0zNTFhNTg2Yjc0ODQiLA0KICAgInN1Y\
iI6ICI1NWY5ZjU1OS0yNDk2LTQ5ZDQtYjZjMy0zNTFhNTg2Yjc0ODQiLA0KICAgImF1Z\
CI6ICJodHRwczovL2lkcC1wLmV4YW1wbGUuY29tL3Rva2VuIiwNCiAgICJpYXQiOiAxN\
DE4Njk4Nzg4LA0KICAgImV4cCI6IDE0MTg2OTg4NDgsDQogICAianRpIjogIjE0MTg2O\
Tg3ODgvMTA3YzRkYTUxOTRkZjQ2M2U1MmI1Njg2NWM1YWYzNGU1NTk1Ig0KfQ.t-_gX8\
JQGq3G2OEc2kUCQ8zVj7pqff87Sua5nktLIHj28l5onO5VpsL4sRHIGOvrpo7XO6jgtP\
Wy3iLXv3-NLyo1TWHbtErQEGpmf7nKiNxVCXlGYJXSDJB6shP3OfvdUc24urPJNUGBED\
ptIgT7-Lhf6BbwQNlMQubNeOPRFDqQoLWqe7UxuI06dKX3SEQRMqcxYSIAfP7CQZ4WLu\
KXb6oEbaqz6gL4l6p83G7wKGDeLETOTHszt-ZjKR38v4F_MnSrx8e0iIqgZwurW0Rtet\
EWvynOCJXk-p166T7qZR45xuCxgOotXY6O3et4n77GtgspMgOEKj3b_WpCiuNEwQ

2.6.3. Client Keys

Clients using the authorization code grant type or direct access clients using the client credentials grant type MUST have a public and private key pair for use in authentication to the token endpoint. These clients MUST register their public keys in their client registration metadata by either sending the public key directly in the jwks field or by registering a jwks_uri that MUST be reachable by the authorization server. It is RECOMMENDED that clients use a jwks_uri if possible as this allows for key rotation more easily. This applies to both dynamic and static (out-of-band) client registration.¶

The jwks field or the content available from the jwks_uri of a client MUST contain a public key in JSON Web Key Set (JWK Set) [RFC7517] format. The authorization server MUST validate the content of the client's registered jwks_uri document and verify that it contains a JWK Set. The following example is of a 2048-bit RSA key:¶

NOTE: '\' line wrapping per RFC 8792

{
   "keys": [
     {
       "alg": "RS256",
       "e": "AQAB",
      "n": "kAMYD62n_f2rUcR4awJX4uccDt0zcXRssq_mDch5-ifcShx9aTtTVza2\
3PTn3KaKrsBXwWcfioXR6zQn5eYdZQVGNBfOR4rxF5i7t3hfb4WkS50EK1gBYk2lO9NS\
rQ-xG9QsUsAnN6RHksXqsdOqv-nxjLexDfIJlgbcCN9h6TB-C66ZXv7PVhl19gIYVifS\
U7liHkLe0l0fw7jUI6rHLHf4d96_neR1HrNIK_xssr99Xpv1EM_ubxpktX0T925-qej9\
fMEpzzQ5HLmcNt1H2_VQ_Ww1JOLn9vRn-H48FDj7TxlIT74XdTZgTv31w_GRPAOfyxEw\
_ZUmxhz5Z-gTlQ",
       "kty": "RSA",
       "kid": "oauth-client"
     }
   ]
}

For reference, the corresponding public/private key pair for this public key is the following (in JWK format):¶

NOTE: '\' line wrapping per RFC 8792

{
  "alg": "RS256",
  "d": "PjIX4i2NsBQuOVIw74ZDjqthYsoFvaoah9GP-cPrai5s5VUIlLoadEAdGbBr\
ss_6dR58x_pRlPHWh04vLQsFBuwQNc9SN3O6TAaai9Jg5TlCi6V0d4O6lUoTYpMR0cxF\
IU-xFMwII--_OZRgmAxiYiAXQj7TKMKvgSvVO7-9-YdhMwHoD-UrJkfnZckMKSs0BoAb\
jReTski3IV9f1wVJ53_pmr9NBpiZeHYmmG_1QDSbBuY35Zummut4QShF-fey2gSALdp9\
h9hRk1p1fsTZtH2lwpvmOcjwDkSDv-zO-4Pt8NuOyqNVPFahROBPlsMVxc_zjPck8ltb\
lalBHPo6AQ",
  "e": "AQAB",
  "n": "kAMYD62n_f2rUcR4awJX4uccDt0zcXRssq_mDch5-ifcShx9aTtTVza23PTn\
3KaKrsBXwWcfioXR6zQn5eYdZQVGNBfOR4rxF5i7t3hfb4WkS50EK1gBYk2lO9NSrQ-x\
G9QsUsAnN6RHksXqsdOqv-nxjLexDfIJlgbcCN9h6TB-C66ZXv7PVhl19gIYVifSU7li\
HkLe0l0fw7jUI6rHLHf4d96_neR1HrNIK_xssr99Xpv1EM_ubxpktX0T925-qej9fMEp\
zzQ5HLmcNt1H2_VQ_Ww1JOLn9vRn-H48FDj7TxlIT74XdTZgTv31w_GRPAOfyxEw_ZUm\
xhz5Z-gTlQ",
  "kty": "RSA",
  "kid": "oauth-client"
}

Note that the second example contains both the public and private keys, while the first example contains the public key only.¶

2.7. Connection to the Protected Resource

2.7.1. Requests to the Protected Resource

Clients MUST use the authorization request header field mechanism to send bearer tokens as defined by [RFC6750].¶

An example of an OAuth-protected call to the OpenID Connect UserInfo endpoint, sending the token in the Authorization header, follows:¶

NOTE: '\' line wrapping per RFC 8792

GET /userinfo HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0MTg3MDI0MTIsI\
\mF1ZCI6WyJjMWJjODRlNC00N2VlLTRiNjQtYmI1Mi01Y2RhNmM4MWY3ODgiXSwiaXNz\
IjoiaHR0cHM6XC9cL2lkcC1wLmV4YW1wbGUuY29tXC8iLCJqdGkiOiJkM2Y3YjQ4Zi1i\
YzgxLTQwZWMtYTE0MC05NzRhZjc0YzRkZTMiLCJpYXQiOjE0MTg2OTg4MTJ9.iHMz_tz\
Z90_b0QZS-AXtQtvclZ7M4uDAs1WxCFxpgBfBanolW37X8h1ECrUJexbXMD6rrj_uuWE\
qPD738oWRo0rOnoKJAgbF1GhXPAYnN5pZRygWSD1a6RcmN85SxUig0H0e7drmdmRkPQg\
bl2wMhu-6h2Oqize4dKmykN9UX_2drXrooSxpRZqFVYX8PkCvCCBuFy2O-HPRov_SwtJ\
Mk5qjUWMyn2I4Nu2s-R20aCA-7T5dunr0iWCkLQnVnaXMfA22RlRiU87nl21zappYb1_\
EHF9ePyq3Q353cDUY7vje8m2kKXYTgc_bUAYuW-W3SMSw5UlKa

2.7.2. Response From the Protected Resource

If the authentication event associated with the access token does not satisfy the requirements of the resource server for the given request, the protected resource MUST return a 401 Unauthorized status code along with a WWW-Authenticate header as defined in OAuth 2.0 Step Up Authentication Challenge Protocol [RFC9470]. This header MUST include the insufficient_user_authentication error code to indicate that the presented access token is inadequate.¶

Additionally, the response MUST include the acr_values and/or max_age auth-params to communicate the necessary authentication context class reference values and the allowable elapsed time since the last active authentication event, respectively. The acr_values parameter should list the required authentication context class reference values in order of preference, while the max_age parameter should indicate the maximum permissible time in seconds since the last user authentication.¶

The mechanisms by which the protected resource determines whether the authentication requirements are met are outside the scope of this profile.¶

Furthermore, if both acr_values and max_age are relevant, they may be included together in the response.¶

The protected resource may also include the scope parameter if additional scopes are required to access the resource, as per Section 3.1 of The OAuth 2.0 Authorization Framework: Bearer Token Usage [RFC6750].¶

3. Authorization Server Profile

All servers MUST conform to applicable recommendations found in the Security Considerations sections of [RFC6749] and those found in the OAuth Threat Model Document [RFC6819].¶

The authorization server MUST protect all communications to and from its OAuth endpoints using TLS as described in Section 1.4.¶

3.1. Connections with clients

3.1.1. Grant types

The authorization server MUST support the authorization_code, and MAY support the client_credentials grant types as described in Section 2. The authorization server MUST limit each registered client (identified by a client ID) to a single client type only, since a single piece of software will be functioning at runtime in only one of the modes described in Section 2. Clients that have multiple modes of operation MUST have a separate client ID for each mode.¶

3.1.2. Client authentication

The authorization server MUST enforce client authentication as described above for the authorization code and client credentials grant types. Public clients cannot authenticate to the authorization server.¶

The authorization server MUST validate all redirect URIs for authorization code grant types.¶

The authorization server MUST confirm thumbprints of client keys if mTLS is used for client authentication or sender-constraining tokens.¶

3.1.3. Dynamic Registration

Dynamic Registration allows for authorized Clients to on-board programmatically without administrative intervention. This is particularly important in ecosystems with many potential Clients, including Mobile Apps acting as independent Clients. Authorization servers MUST support dynamic client registration, and clients MAY register using the Dynamic Client Registration Protocol [RFC7591] for authorization code grant types. Clients MUST NOT dynamically register for the client credentials grant type. Authorization servers MAY limit the scopes available to dynamically registered clients.¶

Authorization servers MAY protect their Dynamic Registration endpoints by requiring clients to present credentials that the authorization server would recognize as authorized participants. Authorization servers MAY accept signed software statements as described in [RFC7591] issued to client software developers from a trusted registration entity. The software statement can be used to tie together many instances of the same client software that will be run, dynamically registered, and authorized separately at runtime. The software statement MUST include the following client metadata parameters:¶

redirect_uris: array of redirect URIs used by the client; subject to the requirements listed in Section 2.5.1 ¶
grant_types: grant type used by the client; must be "authorization_code" or "client_credentials"¶
client_name: human-readable name of the client¶
client_uri: URL of a web page containing further information about the client¶
tls_client_certificate_bound_access_tokens: REQUIRED. Boolean value indicating server support for mutual-TLS client certificate-bound access tokens.¶
acr_values_supported: OPTIONAL. Indicates the client will include the acr_values and max_age parameters in authorization requests, and send insufficient_user_authentication error messages in conformance with OAuth 2.0 Step Up Authentication Challenge Protocol [RFC9470].¶
dpop_signing_alg_values_supported: REQUIRED. A JSON array containing a list of the JWS alg values supported by the client for DPoP proof JWTs.¶
jwks_uri or jwks: client's public key in a JWK Set [RFC7517], or if jwks_uri is used it MUST be reachable by the Authorization Server and point to the client's public key set. If the PKI/tls_client_auth method is used, the public key must be issued by a trusted Certificate Authority. If either the self-signed mTLS method or private_key_jwt method for client authentication is used, the jwks MUST include a certificate.¶

A client using the tls_client_auth authentication method MUST use exactly one of the below metadata parameters to indicate the certificate subject value that the authorization server is to expect when authenticating the respective client:¶

tls_client_auth_subject_dn: String value specifying the expected subject DN of the client certificate.¶
tls_client_auth_san_dns: String value specifying the expected dNSName SAN entry in the client certificate.¶
tls_client_auth_san_uri: String value specifying the expected uniformResourceIdentifier SAN entry in the client certificate.¶
tls_client_auth_san_ip: String value specifying the expected iPAddress SAN entry in the client certificate.¶
tls_client_auth_san_email: String value specifying the expected rfc822Name SAN entry in the client certificate.¶

3.1.4. Client Approval

When prompting the end user with an interactive approval page, the authorization server MUST indicate to the user:¶

Whether the client was dynamically registered, or else statically registered by a trusted administrator, or a public client.¶
Whether the client is associated with a software statement, and in which case provide information about the trusted issuer of the software statement.¶
What kind of access the client is requesting, including scope, protected resources (if applicable beyond scopes), and access duration.¶

For example, for native clients a message indicating a new App installation has been registered as a client can help users determine if this is the expected behaviour. This signal helps users protect themselves from potentially rogue clients.¶

3.1.5. Sender-constrained Tokens

The authorization server MUST support and verify sender-constraining tokens using mTLS [RFC8705] and DPoP [RFC9449].¶

The Authorization Server MUST NOT issue the client an access token if the client included the tls_client_certificate_bound_access_tokens parameter in its registration metadata and makes a request to the token endpoint over a non-mutual-TLS connection.¶

3.1.6. Discovery

The authorization server MUST provide an OpenID Connect service discovery [OpenID.Discovery] endpoint listing the components relevant to the OAuth 2.0 protocol:¶

issuer: REQUIRED. The fully qualified issuer URL of the server¶
authorization_endpoint: REQUIRED. The fully qualified URL of the server's authorization endpoint defined by OAuth 2.0 [RFC6749]¶
token_endpoint: REQUIRED. The fully qualified URL of the server's token endpoint defined by OAuth 2.0 [RFC6749]¶
token_endpoint_auth_method: REQUIRED. String of values corresponding to permitted methods for client authentication to the authorization server as defined in OAuth 2.0 Dynamic Client Registration Protocol [RFC7591]. Within this profile, the server MUST provide one or more of the following values: "private_key_jwt", "tls_client_auth", and "self_signed_tls_auth".¶
introspection_endpoint: OPTIONAL. The fully qualified URL of the server's introspection endpoint defined by OAuth Token Introspection [RFC7662]¶
revocation_endpoint: OPTIONAL. The fully qualified URL of the server's revocation endpoint defined by OAuth 2.0 Token Revocation [RFC7009]¶
mtls_endpoint_aliases: OPTIONAL. A JSON object containing alternative authorization server endpoints that, when present, an OAuth client intending to perform mutual TLS uses in preference to the conventional endpoints. Use of this parameter enables isolation of mTLS behavior to only clients intending to use mTLS for authentication or sender-constraining tokens. Usage of the parameter is specified in OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens [RFC8705]¶
jwks_uri: REQUIRED. The fully qualified URI of the server's JWK as defined in OAuth 2.0 Authorization Server Metadata [RFC8414]. If the self_signed_tls_auth method is used, a jwks_uri MUST be registered and MUST include a certificate.¶

If the TLS method for client authentication is used, exactly one authentication method metadata value MUST be included.¶

tls_client_auth: Indicates that client authentication to the authorization server will occur with mutual TLS utilizing the PKI method of associating a certificate to a client.¶
self_signed_tls_client_auth: Indicates that client authentication to the authorization server will occur using mutual TLS with the client utilizing a self-signed certificate.¶

If the authorization server is also an OpenID Connect Provider, it MUST provide a discovery endpoint meeting the requirements listed in Section 3.6 of the iGov OpenID Connect profile.¶

The following example shows the JSON document found at a discovery endpoint for an authorization server:¶

{
  "request_parameter_supported": true,
  "registration_endpoint": "https://idp-p.example.com/register",
  "userinfo_signing_alg_values_supported": [
    "HS256", "HS384", "HS512", "RS256", "RS384", "RS512"
  ],
  "token_endpoint": "https://idp-p.example.com/token",
  "request_uri_parameter_supported": false,
  "request_object_encryption_enc_values_supported": [
    "A192CBC-HS384", "A192GCM", "A256CBC+HS512",
    "A128CBC+HS256", "A256CBC-HS512",
    "A128CBC-HS256", "A128GCM", "A256GCM"
  ],
  "token_endpoint_auth_methods_supported": [
    "private_key_jwt",
  ],
  "jwks_uri": "https://idp-p.example.com/jwk",
  "authorization_endpoint": "https://idp-p.example.com/authorize",
  "require_request_uri_registration": false,
  "introspection_endpoint": "https://idp-p.example.com/introspect",
  "request_object_encryption_alg_values_supported": [
    "RSA-OAEP", ?RSA1_5", "RSA-OAEP-256"
  ],
  "service_documentation": "https://idp-p.example.com/about",
  "response_types_supported": [
    "code", "token"
  ],
  "token_endpoint_auth_signing_alg_values_supported": [
    "HS256", "HS384", "HS512", "RS256", "RS384", "RS512"
  ],
  "revocation_endpoint": "https://idp-p.example.com/revoke",
  "request_object_signing_alg_values_supported": [
    "HS256", "HS384", "HS512", "RS256", "RS384", "RS512"
  ],
  "grant_types_supported": [
    "authorization_code",
    "client_credentials"
  ],
  "scopes_supported": [
    "profile", "openid", "email", "address", "phone", "offline_access"
  ],
  "op_tos_uri": "https://idp-p.example.com/about",
  "issuer": "https://idp-p.example.com/",
  "op_policy_uri": "https://idp-p.example.com/about"
  "tls_client_certificate_bound_access_tokens": "true"
  "dpop_signing_alg_values_supported": ["PS256", "ES256"]
}

Clients and protected resources SHOULD cache this discovery information. It is RECOMMENDED that servers provide cache information through HTTP headers and make the cache valid for at least one week.¶

The server MUST provide its public key in JWK Set format. The key MUST contain the following fields:¶

kid: The key ID of the key pair used to sign this token¶
kty: The key type¶
alg: The default algorithm used for this key¶

The following is an example of a 2048-bit RSA public key:¶

{
NOTE: '\' line wrapping per RFC 8792

"keys": [
   {
     "alg": "RS256",
     "e": "AQAB",
     "n": "o80vbR0ZfMhjZWfqwPUGNkcIeUcweFyzB2S2T-hje83IOVct8gVg9FxvHP\
K1ReEW3-p7-A8GNcLAuFP_8jPhiL6LyJC3F10aV9KPQFF-w6Eq6VtpEgYSfzvFegNiPt\
pMWd7C43EDwjQ-GrXMVCLrBYxZC-P1ShyxVBOzeR_5MTC0JGiDTecr_2YT6o_3aE2SIJ\
u4iNPgGh9MnyxdBo0Uf0TmrqEIabquXA1-V8iUihwfI8qjf3EujkYi7gXXelIo4_gipQ\
YNjr4DBNlE0__RI0kDU-27mb6esswnP2WgHZQPsk779fTcNDBIcYgyLujlcUATEqfCaP\
DNp00J6AbY6w",
     "kty": "RSA",
     "kid": "rsa1"
    }
  ]
}

Clients and protected resources SHOULD cache this key. It is RECOMMENDED that servers provide cache information through HTTP headers and make the cache valid for at least one week.¶

3.1.7. Revocation

Token revocation allows a client to signal to an authorization server that a given token will no longer be used.¶

Authorization Servers MUST support token revocation as follows.¶

The AS MUST provide a revocation endpoint URL as specified in OAuth 2.0 Token Revocation [RFC7009] for end users to view a list of clients that have been granted access to resources on the user's behalf, and for end users to revoke this access.¶

An authorization server MUST revoke the token if the client requesting the revocation is the client to which the token was issued, the client has permission to revoke tokens, and the token is revocable.¶

A client MUST immediately discard the token and not use it again after revoking it.¶

3.1.8. PKCE

The authorization server MUST require use of PKCE (Proof Key for Code Exchange by OAuth Public Clients [RFC7636]) by all clients, rejecting requests to the authorization endpoint from clients that do not contain a code challenge. Authorization servers MUST support the S256 code challenge method. Authorization servers MUST NOT allow a client to use the plain code challenge method.¶

3.1.9. Redirect URIs

The authorization server MUST compare a client's registered redirect URIs with the redirect URI presented during an authorization request using an exact string match.¶

3.1.10. Refresh Tokens

AS MAY issue refresh tokens to Full (confidential) and Native (public) clients.¶

AS MUST NOT issue refresh tokens to Direct clients (browser-based apps).¶

3.2. Connections between authorization servers and protected resources

This profile defines interoperability requirements between authorization servers and resource servers.¶

3.2.1. JSON Web Tokens (JWT)

All iGov-compliant authorization servers MUST issue cryptographically signed sender-constrained tokens in the JSON Web Token (JWT) format as defined in JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens [RFC9068]. The information carried in the JWT is intended to allow a protected resource to quickly test the integrity of the token without additional network calls, and to allow the protected resource to determine which authorization server issued the token. The protected resource MAY use the authorization server token introspection service to retrieve additional security information about the token.¶

The server MUST issue tokens as JWTs with, at minimum, the following claims:¶

iss: The issuer URL of the server that issued the token¶
client_id: The client id of the client to whom this token was issued¶
exp: The expiration time (integer number of seconds since from 1970-01-01T00:00:00Z UTC), after which the token MUST be considered invalid¶
jti: A unique JWT Token ID value with at least 128 bits of entropy. This value MUST NOT be re-used in another token. Clients MUST check for reuse of jti values and reject all tokens issued with duplicate jti values.¶
sub: The identifier of the end-user that authorized this client, or the client id of a client acting on its own behalf (such as a bulk transfer). Since this information could potentially leak private user information, it should be used only when needed. End-user identifiers SHOULD be pairwise anonymous identifiers unless the audience requires otherwise.¶
aud: The audience of the token, an array containing the identifier(s) of protected resource(s) for which the token is valid, if this information is known. The aud claim may contain multiple values if the token is valid for multiple protected resources. Note that at runtime, the authorization server may not know the identifiers of all possible protected resources at which a token may be used.¶
scope: The value of the scope claim is a JSON string containing a space-separated list of scopes associated with the token, in the format described in Section 3.3 of The OAuth 2.0 Authorization Framework [RFC6749].¶
iat: The "iat" (issued at) claim identifies the time at which the JWT was issued. This claim can be used to determine the age of the JWT. Its value MUST be a number containing a NumericDate value.¶

In order to support backwards compatibility, AS MAY include the azp claim while resource servers modernize.¶

Additionally, if the client uses mTLS [RFC8705] for client authentication or to sender-constrain tokens, the server MUST include the following claim in the access token.¶

cnf: Confirmation, as defined in Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs) [RFC7800] and OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens [RFC8705]. The confirmation claim value MUST be computed using X.509 Certificate SHA-256 Thumbprint and include confirmation method value "x5t#256".¶

The following sample claim set illustrates the use of the required claims for an access token as defined in this profile; additional claims MAY be included in the claim set:¶

{
   "exp": 1418702388,
   "client_id": "55f9f559-2496-49d4-b6c3-351a586b7484",
   "azp": "55f9f559-2496-49d4-b6c3-351a586b7484",
   "iss": "https://idp-p.example.com/",
   "sub" : "93ff28e3-3982-c34b-f2a4-98bb3d42b277",
   "jti": "2402f87c-b6ce-45c4-95b0-7a3f2904997f",
   "iat": 1418698788,
   "scope" : "MyResource1 MyResource2",
   "acr": "myACR",
   "auth_time": 16463400198,
   "cnf": {
       "x5t#S256":"A4DtL2JmUMhAsvJj5tKyn64SqzmuXbMrJa0n761y5v0"
       }
}

The access tokens MUST be signed with JWS [RFC7515] . If private_key_jwt is used, the authorization server MUST support the RS256 signature method for tokens and MAY use other asymmetric signing methods as defined in the IANA JSON Web Signatures and Encryption Algorithms registry [JWS.JWE.Algs] . The JWS header MUST contain the following fields:¶

kid: The key ID of the key pair used to sign this token¶

This example access token has been signed with the server's private key using RS256:¶

NOTE: '\' line wrapping per RFC 8792

eyJhbGciOiJSUzI1NiJ9.ew0KICAgImV4cCI6IDE0MTg3MDIzODgsDQogICAiYXpwIjo\
gIjU1ZjlmNTU5LTI0OTYtNDlkNC1iNmMzLTM1MWE1ODZiNzQ4NCIsDQogICAiaXNzIjo\
gImh0dHBzOi8vaWRwLXAuZXhhbXBsZS5jb20vIiwNCiAgICJqdGkiOiAiMjQwMmY4N2M\
tYjZjZS00NWM0LTk1YjAtN2EzZjI5MDQ5OTdmIiwNCiAgICJpYXQiOiAxNDE4Njk4Nzg\
4LA0KICAgImtpZCI6ICJyc2ExIg0KfQ.iB6Ix8Xeg-L-nMStgE1X75w7zgXabzw7znWU\
ECOsXpHfnYYqb-CET9Ah5IQyXIDZ20qEyN98UydgsTpiO1YJDDcZV4f4DgY0ZdG3yBW3\
XqwUQwbgF7Gwza9Z4AdhjHjzQx-lChXAyfL1xz0SBDkVbJdDjtXbvaSIyfF7ueWF3M1C\
M70-GXuRY4iucKbuytz9e7eW4Egkk4Aagl3iTk9-l5V-tvL6dYu8IlR93GKsaKE8bng0\
EZ04xcnq8s4V5Yykuc_NARBJENiKTJM8w3wh7xWP2gvMp39Y0XnuCOLyIx-J1ttX83xm\
pXDaLyyY-4HT9XHT9V73fKF8rLWJu9grrA

Refresh tokens SHOULD be signed with JWS [RFC7515] using the same private key and contain the same set of claims as the access tokens.¶

The authorization server MAY encrypt access tokens and refresh tokens using JWE [RFC7516] . Encrypted access tokens MUST be encrypted using the public key of the protected resource. Encrypted refresh tokens MUST be encrypted using the authorization server's public key.¶

3.2.2. Introspection

Token introspection allows a protected resource to query the authorization server for metadata about a token. The protected resource makes a request over a mutually authenticated TLS connection like the following to the token introspection endpoint:¶

NOTE: '\' line wrapping per RFC 8792

POST /introspect HTTP/1.1
User-Agent: Faraday v0.9.0
Content-Type: application/x-www-form-urlencoded
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
Connection: close
Host: as-va.example.com
Content-Length: 1412

client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJhMm\
MzNjkxOS0wMWZmLTQ4MTAtYTgyOS00MDBmYWQzNTczNTEiLCJzdWIiOiJhMmMzNjkxOS\
0wMWZmLTQ4MTAtYTgyOS00MDBmYWQzNTczNTEiLCJhdWQiOiJodHRwczovL2FzLXZhLm\
V4YW1wbGUuY29tL3Rva2VuIiwiaWF0IjoxNDE4Njk4ODE0LCJleHAiOjE0MTg2OTg4Nz\
QsImp0aSI6IjE0MTg2OTg4MTQvZmNmNDQ2OGY2MDVjNjE1NjliOWYyNGY5ODJlMTZhZW\
Y2OTU4In0.md7mFdNBaGhiJfE_pFkAAWA5S-JBvDw9Dk7pOOJEWcL08JGgDFoi9UDbg3\
sHeA5DrrCYGC_zw7fCGc9ovpfMB7W6YN53hGU19LtzzFN3tv9FNRq4KIzhK15pns9jck\
Ktui3HZ25L_B-BnxHe7xNo3kA1M-p51uYYIM0hw1SRi2pfwBKG5O8WntybLjuJ0R3X97\
zvqHn2Q7xdVyKlInyNPA8gIZK0HVssXxHOI6yRrAqvdMn_sneDTWPrqVpaR_c7rt8Ddd\
7drf_nTD1QxESVhYqKTax5Qfd-aq8gZz8gJCzS0yyfQh6DmdhmwgrSCCRC6BUQkeFNvj\
MVEYHQ9fr0NA
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertio\
n-type%3Ajwt-bearer
&client_id=a2c36919-01ff-4810-a829-400fad357351
&token=eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0MTg3MDI0MTQsImF1ZCI6WyJlNzFm\
YjcyYS05NzRmLTQwMDEtYmNiNy1lNjdjMmJjMDAzN2YiXSwiaXNzIjoiaHR0cHM6XC9c\
L2FzLXZhLmV4YW1wbGUuY29tXC8iLCJqdGkiOiIyMWIxNTk2ZC04NWQzLTQzN2MtYWQ4\
My1iM2YyY2UyNDcyNDQiLCJpYXQiOjE0MTg2OTg4MTR9.FXDtEzDLbTHzFNroW7w27RL\
k5m0wprFfFH7h4bdFw5fR3pwiqejKmdfAbJvN3_yfAokBv06we5RARJUbdjmFFfRRW23\
cMbpGQCIk7Nq4L012X_1J4IewOQXXMLTyWQQ_BcBMjcW3MtPrY1AoOcfBOJPx1k2jwRk\
YtyVTLWlff6S5gK-ciYf3b0bAdjoQEHd_IvssIPH3xuBJkmtkrTlfWR0Q0pdpeyVePkM\
SI28XZvDaGnxA4j7QI5loZYeyzGR9h70xQLVzqwwl1P0-F_0JaDFMJFO1yl4IexfpoZZ\
sB3HhF2vFdL6D_lLeHRy-H2g2OzF59eMIsM_Ccs4G47862w

The client assertion parameter is structured as described in Section 2.6.2 .¶

The server responds to an introspection request with a JSON object representing the token containing the following fields as defined in the token introspection specification:¶

active: Boolean value indicating whether or not this token is currently active at this authorization server. Tokens that have been revoked, have expired, or were not issued by this authorization server are considered non-active.¶
scope: Space-separated list of OAuth 2.0 scope values represented as a single string.¶
exp: Timestamp of when this token expires (integer number of seconds since from 1970-01-01T00:00:00Z UTC)¶
sub: An opaque string that uniquely identifies the user who authorized this token at this authorization server (if applicable). This string MAY be diversified per client.¶
client_id: An opaque string that uniquely identifies the OAuth 2.0 client that requested this token¶

The following example is a response from the introspection endpoint:¶

HTTP/1.1 200 OK
Date: Tue, 16 Dec 2014 03:00:14 GMT
Access-Control-Allow-Origin: *
Content-Type: application/json;charset=ISO-8859-1
Content-Language: en-US
Content-Length: 266
Connection: close

{
   "active": true,
   "scope": "file search visa",
   "exp": 1418702414,
   "sub": "{sub\u003d6WZQPpnQxV, iss\u003dhttps://idp-p.example.com/}",
   "client_id": "e71fb72a-974f-4001-bcb7-e67c2bc0037f",
   "token_type": "Bearer"
}

The authorization server MUST require authentication of resource servers for both the revocation and introspection endpoints, using either private_key_jwt or Mutual-TLS methods as described for clients in Section 2.6.2. Protected resources calling the introspection endpoint MUST use credentials distinct from any other OAuth client registered at the server. Authorization servers MUST NOT allow authorization clients to use token introspection endpoints.¶

A protected resource MAY cache the response from the introspection endpoint for a period of time no greater than half the lifetime of the token. A protected resource MUST NOT accept a token that is not active according to the response from the introspection endpoint.¶

3.3. Response to Authorization Requests

The following data will be sent as an Authorization Response to the Authorization Code Flow as described Section 2. The authentication response is sent via HTTP redirect to the redirect URI specified in the request, consistent with The OAuth 2.0 Authorization Framework [RFC6749].¶

The following fields MUST be included in the response:¶

state: REQUIRED. The value of the state parameter passed in in the authentication request. This value MUST match exactly.¶
code: REQUIRED. The authorization code, a random string issued by the IdP to be used in the request to the token endpoint.¶

PKCE parameters MUST be associated with the "code" as per Section 4.4 of Proof Key for Code Exchange by OAuth Public Clients (PKCE) [RFC7636]¶

The following is an example response:¶

https://https://client.example.org/cb?
    state=2ca3359dfbfd0
   &code=gOIFJ1hV6Rb1sxUdFhZGACWwR1sMhYbJJcQbVJN0wHA

3.4. Token Lifetimes

Access tokens SHOULD have a valid lifetime no greater than one hour, and refresh tokens (if issued) SHOULD have a valid lifetime no greater than twenty-four hours. Specific applications MAY issue tokens with different lifetimes. Any active token MAY be revoked at any time.¶

3.5. Scopes

Scopes define individual pieces of authority that can be requested by clients, granted by resource owners, and enforced by protected resources. Specific scope values will be highly dependent on the specific types of resources being protected in a given interface. OpenID Connect, for example, defines scope values to enable access to different attributes of user profiles.¶

Authorization servers SHOULD define and document default scope values that will be used if an authorization request does not specify a requested set of scopes.¶

To facilitate general use across a wide variety of protected resources, authorization servers SHOULD allow for the use of arbitrary scope values at runtime, such as allowing clients or protected resources to use arbitrary scope strings upon registration. Authorization servers MAY restrict certain scopes from use by dynamically registered systems or public clients.¶

Refer to Section 3.1.4 for further information about displaying scopes to end users.¶

4. Protected Resource Profile

4.1. Protecting Resources

4.1.1. Trust Levels and Scopes

Protected Resources grant access to clients if they present a valid sender-constrained access_token with the appropriate scope. Resource servers trust the authorization server to authenticate the end user and client appropriately for the importance, risk, and value level of the protected resource scope.¶

If a protected resources requires a higher end-user authentication trust level to access certain resources, the protected resource MUST associate those resources with a unique scope and MUST associate acceptable acr values for each scope as descibed in OAuth 2.0 Step Up Authentication Challenge Protocol" [RFC9470]. Protected Resources may also specify a max_age for each scope.¶

Clients wishing access to these higher level resources MUST include the higher level scope and acr_values in their authorization request to the authorization server.¶

Authorization servers MUST only grant access to higher level scope resources to clients that have permission to request these scope levels and have met . Client authorization requests containing scopes that are outside their permission MUST be rejected.¶

Authorization servers MAY set the expiry time (exp) of access_tokens associated with higher level resources to be shorter than access_tokens for less sensitive resources.¶

Authorization servers MAY allow a refresh_token issued at a higher level to be used to obtain an access_token for a lower level resource scope with an extended expiry time. The client MUST request both the higher level scope and lower level scope in the original authorization request. This allows clients to continue accessing lower level resources after the higher level resource access has expired -- without requiring an additional user authentication/authorization.¶

4.1.2. Trust Levels Example

For example: a resource server has resources classified as "public" and "sensitive" and assocaites scopes of the same name with those resources. Access to resources with scope "sensitive" requires the user to perform a two-factor authentication and limits those access grants to only 15 minutes. The resource server associates scope "sensitive" with acr="MFA".¶

For a client to obtain access to both "public" and "sensitive" resources, it makes an authorization request to the authorization server with scope=public+sensitive, acr_values="MFA", and max_age=900. The authorization server authenticates the end-user as required to meet the required trust level (two-factor authentication or some approved equivalent) and issues an access_token for the "public" and "sensitive" scopes with an expiry time of 15mins, and a refresh_token for the "public" scope with an expiry time of 24 hrs.¶

The client can access both "public" and "sensitive" resources for 15mins with the access_token. When the access_token expires, the client will NOT be able to access "public" or "sensitive" resources any longer as the access_token has expired, and must obtain a new access_token.¶

The client makes a refresh token request (as described in OAuth 2.0 [RFC6749] section 6) with the refresh_token, and the reduced scope of just "public". The token endpoint validates the refresh_token, and issues a new access_token for just the "public" scope with an expiry time set to 24hrs. An access grant request for a new access_token with the "sensitive" scope would be rejected, and require the client to get the end-user to re-authenticate/authorize the "sensitive" scope request.¶

In this manner, protected resources and authorization servers work together to meet risk tolerance levels for sensitive resources and end-user authentication.¶

4.2. Connections with Clients

A protected resource MUST accept bearer tokens passed in the authorization header as described in [RFC6750] . A protected resource MUST NOT accept bearer tokens passed in the form parameter or query parameter methods.¶

Protected resources MUST define and document which scopes are required for access to the resource and any authentication strength or recency requirements for each scope.¶

If a client uses the mTLS [RFC8705] method to sender-constrain tokens, the protected resource MUST verify that the certificate matches the certificate associated with the access token. If they do not match, the resource access attempt MUST be denied. The client SHOULD use a certificate to sender-constrain tokens that is distinct from the certificate used to connect to the protected resource.¶

4.3. Connections with Authorization Servers

Protected resources MUST interpret access tokens using either JWT, token introspection, or a combination of the two.¶

The protected resource MUST check the aud (audience) claim, if it exists in the token, to ensure that it includes the protected resource's identifier. The protected resource MUST ensure that the rights associated with the token are sufficient to grant access to the resource. For example, this can be accomplished by querying the scopes and acr associated with the token from the authorization server's token introspection endpoint.¶

A protected resource MUST limit which authorization servers it will accept valid tokens from. A resource server MAY accomplish this using a whitelist of trusted servers, a dynamic policy engine, or other means.¶

7. Normative References

[BCP195]: Sheffer, Y., Holz, R., and P. Saint-Andre, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2015, <http://www.rfc-editor.org/info/bcp195>.
[BCP240]: Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, "Best Current Practice for OAuth 2.0 Security", BCP 240, RFC 9700, DOI 10.17487/RFC9700, January 2025, <http://www.rfc-editor.org/info/bcp240>.
[browser-based-apps]: Parecki, A., Waite, D., and P. De Ryck, "OAuth 2.0 for Browser-Based Applications", 17 January 2025, <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps>.
[HEART.OAuth2]: Richer, J., "Health Relationship Trust Profile for OAuth 2.0", 25 April 2017, <http://openid.net/specs/openid-heart-oauth2-1_0-ID1.html>.
[JWS.JWE.Algs]: "JSON Web Signature and Encryption Algorithms registry", 8 August 2016.
[mlkem.ikev2]: Kampanakis, P. and G. Ravago, "Post-quantum Hybrid Key Exchange with ML-KEM in the Internet Key Exchange Protocol Version 2 (IKEv2)", 4 November 2024, <https://datatracker.ietf.org/doc/draft-kampanakis-ml-kem-ikev2/>.
[OpenID.Core]: Sakimura, N., Bradley, J., Jones, M.B., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0", 3 August 2015, <http://openid.net/specs/openid-connect-core-1_0.html>.
[OpenID.Discovery]: Sakimura, N., Bradley, J., Jones, M.B., and E. Jay, "OpenID Connect Discovery 1.0", 3 August 2015, <http://openid.net/specs/openid-connect-discovery-1_0.html>.
[OpenID.iGov]: Varley, M. and P. Grassi, "International Government Assurance Profile (iGov) for OpenID Connect 1.0", 3 August 2023, <https://openid.net/specs/openid-igov-openid-connect-1_0.html>.
[Resource.Metadata]: Jones, M., Hunt, P., and A. Parecki, "OAuth 2.0 Protected Resource Metadata", 15 October 2024, <https://datatracker.ietf.org/doc/draft-ietf-oauth-resource-metadata/>.
[RFC2119]: Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.
[RFC6749]: Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, <https://www.rfc-editor.org/info/rfc6749>.
[RFC6750]: Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, <https://www.rfc-editor.org/info/rfc6750>.
[RFC6797]: Hodges, J., Jackson, C., and A. Barth, "HTTP Strict Transport Security (HSTS)", RFC 6797, DOI 10.17487/RFC6797, November 2012, <https://www.rfc-editor.org/info/rfc6797>.
[RFC6819]: Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 Threat Model and Security Considerations", RFC 6819, DOI 10.17487/RFC6819, January 2013, <https://www.rfc-editor.org/info/rfc6819>.
[RFC6973]: Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., Morris, J., Hansen, M., and R. Smith, "Privacy Considerations for Internet Protocols", RFC 6973, DOI 10.17487/RFC6973, July 2013, <https://www.rfc-editor.org/info/rfc6973>.
[RFC7009]: Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, August 2013, <https://www.rfc-editor.org/info/rfc7009>.
[RFC7515]: Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, <https://www.rfc-editor.org/info/rfc7515>.
[RFC7516]: Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", RFC 7516, DOI 10.17487/RFC7516, May 2015, <https://www.rfc-editor.org/info/rfc7516>.
[RFC7517]: Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015, <https://www.rfc-editor.org/info/rfc7517>.
[RFC7518]: Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI 10.17487/RFC7518, May 2015, <https://www.rfc-editor.org/info/rfc7518>.
[RFC7519]: Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, <https://www.rfc-editor.org/info/rfc7519>.
[RFC7523]: Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 2015, <https://www.rfc-editor.org/info/rfc7523>.
[RFC7591]: Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, July 2015, <https://www.rfc-editor.org/info/rfc7591>.
[RFC7636]: Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key for Code Exchange by OAuth Public Clients", RFC 7636, DOI 10.17487/RFC7636, September 2015, <https://www.rfc-editor.org/info/rfc7636>.
[RFC7662]: Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, October 2015, <https://www.rfc-editor.org/info/rfc7662>.
[RFC7800]: Jones, M., Bradley, J., and H. Tschofenig, "Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs)", RFC 7800, DOI 10.17487/RFC7800, April 2016, <https://www.rfc-editor.org/info/rfc7800>.
[RFC8252]: Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, <https://www.rfc-editor.org/info/rfc8252>.
[RFC8414]: Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018, <https://www.rfc-editor.org/info/rfc8414>.
[RFC8705]: Campbell, B., Bradley, J., Sakimura, N., and T. Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens", RFC 8705, DOI 10.17487/RFC8705, February 2020, <https://www.rfc-editor.org/info/rfc8705>.
[RFC8725]: Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best Current Practices", BCP 225, RFC 8725, DOI 10.17487/RFC8725, February 2020, <https://www.rfc-editor.org/info/rfc8725>.
[RFC9068]: Bertocci, V., "JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens", RFC 9068, DOI 10.17487/RFC9068, October 2021, <https://www.rfc-editor.org/info/rfc9068>.
[RFC9449]: Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof of Possession (DPoP)", RFC 9449, DOI 10.17487/RFC9449, September 2023, <https://www.rfc-editor.org/info/rfc9449>.
[RFC9470]: Bertocci, V. and B. Campbell, "OAuth 2.0 Step Up Authentication Challenge Protocol", RFC 9470, DOI 10.17487/RFC9470, September 2023, <https://www.rfc-editor.org/info/rfc9470>.
[SAM]: Fett, D., "PKCE vs. Nonce: Equivalent or Not?", 16 May 2020, <https://danielfett.de/2020/05/16/pkce-vs-nonce-equivalent-or-not/>.

International Government Assurance Profile (iGov) for OAuth 2.0 - draft 06