Logo

OAuth 2.0 Profile for the Swedish SDG Framework

Version: 1.0 - draft 01 - 2023-05-16

Abstract

This specification defines an OAuth2 profile to use within the Single Digital Gateway (SDG) project. It profiles the OAuth2 protocol to get a baseline security and to facilitate interoperability between Relying Parties (clients), Resource Servers and Authorization Servers.

1. Introduction

The profile is loosely based on the International Government Assurance Profile for OAuth2.0 draft, [OAuth2.iGov].

The Sweden Connect Technical Framework will introduce specifications for OAuth2 in the future. When this happens, these specifications will be normative within the Swedish SDG framework.

1.1. Requirements Notation and Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” are to be interpreted as described in [RFC2119].

These keywords are capitalized when used to unambiguously specify requirements over protocol features and behavior that affect the interoperability and security of implementations. When these words are not capitalized, they are meant in their natural-language sense.

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 [RFC6749] and the terms "Claim Name", "Claim Value", and "JSON Web Token (JWT)" defined by [RFC7519].

1.3. Conformance

This specification defines requirements for the following entities:

OAuth 2.0 Clients (relying parties).
OAuth 2.0 Authorization Servers.
OAuth 2.0 Resource Servers (protected resources).

When an entity compliant with this profile is interacting with other entities also compliant with this profile, in any valid combination, all entities MUST fully conform to the features and requirements of this specification. All interaction with other entities is outside the scope of this specification.

2. Client Types

The following descriptions give patterns of deployment for use in different types of client applications based on the OAuth grant type. Additional grant types, such as assertions, chained tokens, or other mechanisms, are out of scope of this profile and must be covered separately by appropriate profile documents.

2.1. Full Client with User Delegation

This client type applies to clients that act on behalf of a particular resource owner (user) and require delegation of that user’s authority to access the protected resource. Furthermore, these clients are capable of interacting with a separate web browser application to facilitate the resource owner's interaction with the authentication endpoint of the Authorization Server.

These clients MUST use the authorization code flow of OAuth2 by sending the resource owner (user) to the authorization endpoint to obtain authorization. The user MUST authenticate to the authorization endpoint. The user’s web browser is then redirected back to a URI hosted by the client service, from which the client can obtain an authorization code passed as a query parameter. The client then presents that authorization code along with its own credentials (private_key_jwt) to the Authorization Server's token endpoint to obtain an access token.

This client type MAY request and be issued a refresh token if the security parameters of the access request allow for it.

2.2. Direct Access Client

This profile applies to clients that connect directly to Resource Servers and do not act on behalf of a particular resource owner (user), such as those clients that facilitate bulk transfers.

These clients use the client credentials flow of OAuth2 by sending a request to the token endpoint with the client's credentials and obtaining an access token in the response. Since this profile does not involve an authenticated user, this flow is appropriate only for trusted applications, such as those that would traditionally use a developer key. For example, a partner system that performs bulk data transfers between two systems would be considered a direct access client.

This client type MUST NOT request or be issued a refresh token.

3. Authorization Requests

Full clients clients making a request to the authorization endpoint MUST include the state parameter and use an unpredictable value 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 the redirect_uri parameter in the authorization request and the value MUST be the full redirect URI. 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 following is a sample response from a (web-based) Client to the user’s browser for the purpose of redirecting the end user to the Authorization Server's authorization endpoint (wrapping for display purposes):

HTTP/1.2 302 Found
Cache-Control: no-cache
Connection: close
Content-Type: text/plain; charset=UTF-8
Date: Wed, 04 May 2013 11:26:54 GMT
Location: https://as.example.se/authorize?client_id=example_client \ 
  &state=cd567e...ca557c30d \
  &response_type=code \
  &scope=read_private_resource \
  &redirect_uri=https%3A%2F%2Fclient.example.se%2Fcallback
Status: 302 Found

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

GET /authorize?client_id=example_client \
  &state=cd567e...ca557c30d \
  &response_type=code \
  &scope=read_private_resource \
  &redirect_uri=https%3A%2F%2Fclient.example.se%2Fcallback
  HTTP/1.1
Host: as.example.se

3.1. Request Parameters

3.1.1. The PKCE Parameter

A client MAY choose to use the Proof Key for Code Exchange (PKCE) extension, [RFC7636] and include the code_challenge and code_challenge_method parameters.

If PKCE is used, the code challenge method S256 SHOULD be used.

An Authorization Server compliant with this specification MUST support the PKCE extension including support for the S256 code challenge method.

An Authorization Server MUST NOT allow a client to use the plain code challenge method.

3.2. Requesting User Authentication

An Authorization Server compliant with this specification that supports clients using the authorization code grant type (2.1) MUST also be able to act as an OpenID Provider according to [OIDC.Sweden].

This means that a Full Client (2.1) can delegate user authentication to the Authorization Server (OpenID Provider) by including the openid scope parameter in the request to the authorization endpoint.

Additional OpenID Connect scopes MAY also be supplied in the request. See [OIDC.Attr.Sweden] and the "Sweden Connect - OpenID Connect Claims and Scopes Specification"¹.

Below follows an example of a request to the Authorization Server that will lead to that both an access token and an OpenID Connect ID token can be obtained from the token endpoint (see below):

GET /authorize?client_id=example_client \
  &state=cd567e...ca557c30d \
  &response_type=code \
  &scope=openid https%3A%2F%2Fid.oidc.se%2Fscope%2FnaturalPersonNumber read_private_resource \
  &prompt=login \
  &redirect_uri=https%3A%2F%2Fclient.example.se%2Fcallback \
  &resource=https%3A%2F%2Fresource1.example.se
  HTTP/1.1
Host: as.example.se

Compared with the earlier example there are two differences:

The scopes openid and https://id.oidc.se/scope/naturalPersonNumber are included. This tells the Authorization Server that the user should be authenticated and that the client wishes to receive the identity claims that are part of the naturalPersonNumber scope, see section 3.2 of [OIDC.Attr.Sweden].
The prompt parameter is included which is an OpenID Connect-specific request parameter. The value login tells the Authorization Server that the user must be prompted to authenticate, i.e., SSO is disabled.

Note: A "pure" Authorization Server, i.e., an AS that does not support OpenID Connect, will also authenticate the end-user, but in these cases the client has no way of affect the authentication and thus can not request specific identity attributes to be delivered.

Also, if the client wishes to receive specific identity claims in the resulting access token JWT, see section 4.2.1 this needs to be prepared for already during the authorization request by including the appropriate OpenID Connect scopes. If an authorization request does not include these scopes the Authorization Server will only include the sub claim in the JWT.

[1]: At the time of writing this specification the Sweden Connect Claims and Scopes specification is not ready for publication. It will define claims and scopes for eIDAS authentication.

4. Token Endpoint Requests and Token Issuance

4.1. Requests to the Token Endpoint

Requests to the Authorization Server token endpoint can be made to:

request an ID token,
request a JWT access token, or
request both an ID token and a JWT access token.

Requests to the Authorization Server token endpoint MUST be sent and processed according to section 3.2 of [RFC6749]. For For Full Clients (2.1) section 4.1.3 MUST be followed and for Direct Access Clients (2.2) section 4.4.2 MUST be followed.

If the grant type is authorization_code and the corresponding authorization request contained the openid scope, the Authorization Server MUST deliver an ID token in the token response message, see section 3 of [OIDC.Sweden].

If a JWT access token that is to be passed to a resource server is requested, the client MUST include the resource parameter in the token request according to section 2.2 of [RFC8707]. The value of this parameter MUST be set to the registered identity¹ of the resource server where the client intends to use the requested access token.

In cases where the client needs to communicate with multiple resource servers it is RECOMMENDED that separate token requests are sent², i.e., one access token per intended resource server will be issued. In these cases the client passes the refresh token i subsequent requests.

An Authorization Server compliant with this profile MUST support the resource parameter and, if the supplied resource server ID is accepted by the Authorization Server, its exact value MUST be assigned to the resulting token audience, see section 4.2.1 below.

If the client requires that identity claims from the user authentication should be included in the resulting JWT access token, the client MUST include the OpenID Connect scopes identifying these claims. A client MUST NOT include an OpenID Connect scope that was not included in the corresponding authorization request (see section 3.2 above).

In the special case where the client only requires an ID token and not a JWT access token to be passed to a resource server, the client MUST omit the resource parameter. The Authorization Server MUST then issue an opaque string as the value of the access token. This token can only be understood by the Authorization Server and MAY be used in further communications with the Authorization Server.

[1]: How the registered identities for resource servers are made known to OAuth2 clients are out of scope for this specification.

[2]: [RFC8707] allows for passing multiple resource parameters, and thus getting an access token having multiple audiences. The problem with this usage may be that the requested scopes then need to apply for all resource servers, and this is not always the case. Another problem is that multiple audiences in the JWT will reveal unwanted information to the resource servers.

4.1.1. Client Authentication

Full clients (2.1) and direct access clients (2.2) MUST authenticate to Authorization Server's token endpoint using a JWT assertion as defined by [RFC7523] using only the private_key_jwt method defined in [OpenID.Core].

The following claims MUST be included in the token request:

client_assertion_type - Set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion - The value of the signed client authentication JWT generated. The Client MUST generate a new assertion JWT for each call to the token endpoint. See below.

The JWT assertion MUST use the claims as follows:

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 token 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.

The following sample claim set illustrates the use of the required claims for a client authentication JWT as defined in this profile. Additional claims MAY be included in the claim set.

{
  "iss": "example_client",
  "sub": "example_client",
  "aud": "https://as.example.se/token",
  "iat": 1683200128,
  "exp": 1683200188, 
  "jti": "AB786tg9kLTMNB90"
}

The JWT assertion MUST be signed by the client using the client's private key. Section 7.1 of [OIDC.Sweden], lists the requirements for allowed and required signature algorithms.

The Authorization Server MUST enforce client authentication as described above for the authorization code and client credentials grant types.

4.2. Token Responses and Validation

An Authorization Server compliant with this specification MUST issue refresh tokens to Full Clients (2.1). Direct Access Clients (2.2) MUST NOT be issued refresh tokens.

If the corresponding authorization request contained the openid scope, the Authorization Server MUST include an ID token in the token response according to section 3.2 of [OIDC.Sweden].

4.2.1. JWT Access Tokens

Authorization Servers compliant with this specification MUST issue access tokens that are cryptographically signed tokens in the JSON Web Token (JWT) format, [RFC7519]. The only exception is when a token request did not contain a resource parameter and the corresponding authorization request contained the openid scope. In these cases the Authorization Server MUST issue an access token that is an opaque string. This token only has meaning for the Authorization Server itself.

The information carried in the JWT is intended to allow a resource server to validate the integrity of the token without any additional invocations, and to allow the resource server to determine which Authorization Server issued the token. Entities compliant with this specification SHOULD NOT use token introspection, meaning that all access tokens issued MUST contain all the needed information both regarding token validation and the data needed by the resource server to take an authorization decision.

An Authorization Server compliant with this specification MUST issue JWT access tokens that follow JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens, [RFC9068], with the following clarifications and overrides:

The aud claim is REQUIRED and MUST match the resource parameter from the corresponding token request, see section 4.1 above. If more than one resource parameter was sent, the aud claim MAY hold several values (in an array).
The sub claim is REQUIRED and for clients using the authorization code grant type (2.1) the value SHOULD contain the Swedish personal identity number (or coordination number), and for clients using the client credentials grant type (2.2) the value MUST be the same as the client_id.
The scope claim, as defined in section 4.2 of [RFC8693], is REQUIRED if the corresponding token request included the scope parameter. All the individual scope strings in the scope claim MUST have meaning for the resources indicated in the aud claim.

If the token request contained an OpenID scope value, the Authorization Server MUST attempt¹ to include the claims identified by the scope. In these cases the following claims MUST be included in the JWT:

auth_time - The authentication time as defined in section 2 of [OpenID.Core].
acr - The authentication context class for the authentication as defined in section 2 of [OpenID.Core].
https://id.oidc.se/claim/authnProvider - The identity of the authentication/identity provider that authenticated the user on behalf of the Authorization Server. See section 2.3.5 of [OIDC.Attr.Sweden].
If the Authorization Server did not delegate user authentication this claim will contain the identity of the Authorization Server.

Furthermore, the JWT MUST be signed with an asymmetric algorithm. See section 2.1 of [RFC9068] and section 7.1 of [OIDC.Sweden].

[1]: Since not all claims for a given OpenID Connect scope may be available from a particular user authentication process, we write "MUST attempt" and not "MUST". Claims issuance from an OpenID Provider is "best effort"-based and a consumer of the resulting token should always check whether the necessary claims are included in the token.

4.2.2. Token Lifetime

This specification provides the following requirements regarding token lifetimes:

For clients using the authorization code grant type (2.1), access tokens SHOULD have a valid lifetime no greater than 60 minutes, and refresh tokens SHOULD have a valid lifetime no greater than 24 hours.
For clients using the client credentials grant type (2.2), access tokens SHOULD have a valid lifetime no greater than 60 minutes.

Any active token MAY be revoked at any time.

5. Resource Servers

An Resource Server, or protected resource, within the SDG framework is basically an API for a particular service. Each API must be identified with an identified that is unique within the SDG federation. An organization, or service provider, MAY have several API:s, each with a unique identifier.

A client making an API-call to a protected resource MUST, after it have obtained an access token from the Authorization Server, include the access token in the HTTP request as a value to the "Authorization header" field. This value is prefixed by the text "Bearer ". See section 2.1 of [RFC6750].

5.1. Registration of Resource Servers

When a resource server registers at the Authorization Server it is assigned a unique identifier in the form of an URI. It will also receive the Authorization Server Metadata document, see section 6.1 below, from where it can extract the trusted key to use when verifying JWT signatures and the Authorization Server identity (see Validation of JWT Access Tokens below).

The resource server supplies the Authorization Server with the following information:

Required scope(s).
Initially, very few scopes will be used within SDG, and it is likely that API:s all "require" the same scope, e.g., read-api.
the organization name and description of the API service, and
optionally, whether the API has any specific requirements concerning which clients that may use the service.

Also. If the API handles data tied to a user (natural person) and requires that the access tokens contain information about that the user has authenticated at the Authorization Server, and explicitly or implicitly given his or hers consent for the calling client to perform an action, this information must be part of the registration. If the Resource Server requires more information than the sub claim (that normally contains the Swedish personal identity number or coordination number) the required identity claims should be made known in the registration phase.

Note: The above is not the normative description of API-registration in SDG. This information is provided via other channels.

5.2. Validation of JWT Access Tokens

An JWT access token serves several purposes for a resource server when receiving it in an API call.

The party that is making the call can be identified via the client_id claim.
The scopes, or rights, assigned to the calling party by the trusted Authorization Server can be found via the scope claim.
The resource owner's (the user's) identity is found in the sub claim, and additional identity claims may also be included (see section 4.2.1 above).

So, in other words, the Authorization Server, whom is trusted by the API, has authenticated both the client and the user and verified that the client is authorized to make the call to the API (in the name of the user).

Before a resource server grants access to an API call it MUST validate the received JWT access token according to section 4 of [RFC9068].

Also, if the API call concerns getting, or manipulating, data tied to a user (resource owner) and the resource server requires proof that the user has authenticated at the Authorization Server, and explicitly or implicitly given his or hers consent for the calling client to perform this action, the resource server MUST ensure that the identity claims¹ of the JWT matches the user related parameters of the API call.

A resource server MUST NOT allow access if a JWT lacks identity claims required by the API endpoint policy.

[1]: Such identity claims are the sub claim and additional identity claims that are dependent on the scopes passed to the token endpoint (see section 4.1 above).

6. Discovery

An Authorization Server compliant with this specification MUST provide an OAuth2 discovery endpoint as described in section 3 of [RFC8414].

If the Authorization Server is also an OpenID Connect Provider, it MUST follow the requirements from section 5.2 of [OIDC.Sweden].

6.1. Authorization Server Metadata

An Authorization Server compliant with this specification MUST provide a Metadata Document according to section 2 of [RFC8414] with the following extensions:

The jwks_uri field is REQUIRED.
The scopes_supported field is REQUIRED.
The grant_types field is REQUIRED and MUST be set to [ "authorization_code" ].
The token_endpoint_auth_methods_supported field is REQUIRED and MUST be set to [ "private_key_jwt" ].
The token_endpoint_auth_signing_alg_values_supported field is REQUIRED and MUST contain RS256 and ES256.
The code_challenge_methods_supported field is REQUIRED. JSON array containing a list of PKCE code challenge methods supported by this Authorization Server. The array MUST include the S256 method and MUST NOT include the plain method.
The signed_metadata is REQUIRED. See section 2.1 of [RFC8414].

Note: The issuer name (iss) and signing key/certificate for the signed_metadata is distributed to SDG clients out-of-band.

6.2. Obtaining and Validating Metadata

An entity wishing to download an Authorization Server's Metadata document SHOULD follow the methods described in sections 3.1 and 3.2 of [RFC8414] and validate the downloaded metadata according to section 3.3.

An entity (Client or Resource Server) compliant with this specification SHOULD support the signed_metadata field of the Metadata document. Before accepting the metadata values contained in this field the signature MUST be successfully verified against an out-of-band distributed key/certificate.

7. Client Registration

All Clients MUST register with the Authorization Server.

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

A Client MUST NOT be registered both as a Full Client (2.1) and a Direct Access Client (2.2), i.e., the client MUST NOT register a Client Metadata document where the grant_types field includes both the authorization_code and the client_credentials grants (see listing below).

An OAuth2 Client compliant with this specification that also acts as an OpenID Connect Client MUST also follow the requirements put in section 6 of [OIDC.Sweden].

Section 2 of [RFC7591] states requirements for the Client Metadata document. This specification puts the following additional requirements:

Each registered client receives a unique Client ID during the registration process. This ID is later used by the client to identify itself in authorization and token requests.
redirect_uris - REQUIRED for Full Clients (2.1). See section 7.1 below.
token_endpoint_auth_method - REQUIRED for all clients compliant with this specification. MUST be set to private_key_jwt, see [OpenID.Core].
grant_types - REQUIRED. The array MUST include authorization_code for Full Clients (2.1) and client_credentials for Direct Access Clients (2.2).
response_types - REQUIRED for Full Clients (2.1). The array MUST include the code value and MUST NOT include the token value (implicit response type).
scope - REQUIRED. String containing a space-separated list of scope values.
jwks - RECOMMENDED. The client's JSON Web Key Set [JWK] document, passed by value. See [RFC7517]. If not provided, the jwks_uri MUST be present and be reachable by the Authorization Server and point to the client's public key set. See note about jkws_uri below.
client_name - REQUIRED for Full Clients (2.1). Human-readable string name of the client to be presented to the end-user during authorization. The value of this field SHOULD be internationalized with values for Swedish and English supplied. See section 2.2 of [RFC7591]

Note: This specification, unlike [RFC7591], prefers that JWK:s are registered by value (jwks) instead of by reference (jwks_uri). The reason for this is that it is unlikely that all clients within the SDG Framework manage to publish public URL:s containing a JWK.

7.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 TLS protection (HTTPS)
Hosted on the local domain of the client (e.g., https://localhost:8443) - For testing only.

Clients SHOULD NOT have multiple redirect URIs on different domains.

Clients MUST NOT forward values passed back to their redirect URI:s to other arbitrary or user-provided URI:s.

8. Security Requirements

See Section 7, Security Requirements, of [OIDC.Sweden].

9. Normative References

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997.

[RFC6749]

Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012.

[RFC6750]

Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, October 2012.

[RFC7523]

Jones, M., Campbell, B. and C. Mortimore, "JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7523, May 2015.

[RFC7591]

Richer, J., Jones, M., Bradley, J., Machulak, M. and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, July 2015.

[RFC8414]

Jones, M., Bradley, J., and N. Sakimura, "OAuth 2.0 Authorization Server Metadata", RFC 8414, June 2018.

[RFC8707]

Campbell, B., Bradley, J., and H. Tschofenig, "Resource Indicators for OAuth 2.0", RFC 8707, February 2020.

[RFC9068]

Bertocci, V., "JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens", RFC 9068, October 2021.

[RFC8693]

Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693, January 2020

[RFC6819]

Lodderstedt, T., McGloin, M. and P. Hunt, "OAuth 2.0 Threat Model and Security Considerations", RFC 6819, January 2013.

[RFC7636]

Sakimura, N., Bradley, J. and N. Agarwal, "Proof Key for Code Exchange by OAuth Public Clients", RFC 7636, September 2015.

[OpenID.Core]

Sakimura, N., Bradley, J., Jones, M., de Medeiros, B. and C. Mortimore, "OpenID Connect Core 1.0", August 2015.

[OpenID.Discovery]

Sakimura, N., Bradley, J., Jones, M. and E. Jay, "OpenID Connect Discovery 1.0", August 2015.

[RFC7515]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, May 2015.

[RFC7517]

Jones, M., "JSON Web Key (JWK)", RFC 7517, May 2015.

[RFC7518]

Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, May 2015.

[RFC7519]

Jones, M., Bradley, J. and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, May 2015.

[RFC5480]

IETF RFC 5480, Elliptic Curve Cryptography Subject Public Key Information, RFC 5480, March 2009.

[NIST.800-52.Rev2]

NIST Special Publication 800-52, Revision 2, "Guidelines for the Selection, Configuration, and Use of Transport Layer Security (TLS) Implementations".

[OIDC.Sweden]

The Swedish OpenID Connect Profile.

[OIDC.Attr.Sweden]

Attribute Specification for the Swedish OpenID Connect Profile.

[OAuth2.iGov]

J. Richer, P. Grassi, M. Varley, "International Government Assurance Profile (iGov) for OAuth 2.0 - Draft 03", October 2018.