Federationskontext BAS: OAuth 2.0 Metadata Requirements 1.0, draft 02

Federationskontext BAS: OAuth 2.0 Metadata Requirements 1.0, draft 01

Published: September 2026
Workgroup: Samordnad identitet och behörighet
Organization: The Swedish Agency for Digital Government (Digg)

Abstract

This specification defines the metadata requirements for OAuth 2.0 Clients, Authorization Servers and Protected Resources participating in Federationskontext BAS, a federation context for machine-to-machine access within the Swedish public sector. The metadata is published in Entity Configurations according to OpenID Federation 1.0. The requirements apply to the Resolved Metadata, meaning the metadata that results once the Trust Chain of an Entity has been applied to the declarations the Entity makes about itself. The primary purpose of the requirements is that a party can verify the system identity of an Entity and the organization it is registered for. The requirements also support interoperability according to the Ena OAuth 2.0 Interoperability Profile, and the registration of Clients at Authorization Servers, in that identifiers, keys, authentication methods, endpoints and algorithms are obtained from Resolved Metadata rather than agreed bilaterally. They do not regulate the information exchange that follows, including which scopes are defined or requested and what access a Client is granted.

Table of Contents

1. Introduction
   1.1. Requirements Notation and Conventions
   1.2. Terminology
   1.3. Scope of the Requirements
2. General Requirements
3. Common Requirements
   3.1. The organization_identifier Format
4. OAuth Client Requirements
   4.1. Client Identifier
   4.2. Client Authentication
5. Authorization Server Requirements
6. Protected Resource Requirements
   6.1. Resource Identifier
7. BAS Metadata Policies
   7.1. Trust Anchor Metadata Policy
   7.2. Federation Registration Entity Metadata Assignment
8. Normative References
9. Informative References
   Appendix A. Notices
   Appendix B. Document History

1. Introduction

This document specifies the metadata that an OAuth 2.0 Client, Authorization Server or Protected Resource publishes when it joins Federationskontext BAS, hereafter BAS. It is written for the organizations that operate such Entities, and for the developers and operators who implement them. How BAS is structured, and which requirements apply when Federation Members are connected and their Entities registered, is described in [BAS.Rules].

BAS is a federation context for machine-to-machine access within, and towards, the Swedish public sector. It exists so that a party can verify the system identity of another party's Entity, and which organization that Entity is registered for, before any information is exchanged. This is the primary purpose of the requirements in this document. The same metadata also serves two further purposes. It supports interoperability according to the Ena OAuth 2.0 Interoperability Profile [Ena.OAuth2], in that the endpoints, keys, algorithms and authentication methods that parties need in order to interact are published in Resolved Metadata rather than agreed bilaterally. It also supports Client Registration, in that the Client's identifier, keys and authentication method can be taken from its Resolved Metadata. Meeting the requirements does not by itself ensure that two Entities can interoperate, nor does it result in Client Registration at every Authorization Server in BAS. [Ena.OAuth2] leaves some choices to the individual Entity, such as whether mutual TLS is supported for client authentication, and the scopes, resources and access that an exchange depends on are agreed between the parties. Whether an Authorization Server accepts a Client, and what access it grants, remains the Authorization Server's decision. Every requirement in this document is derived from these purposes, and the document places no requirements beyond them. Section 1.3 states where the boundary lies.

BAS applies the requirements of the federation platform of Samordnad identitet och behörighet (SIB) for connection and registration. A Federation Member is connected under Requirements and Guidance for Connection (Swedish: Anslutning – Tillämpningskrav och vägledning) [SIB.Connection], which establishes the identity of the organization. Its Entities are then registered by a Federation Registration Operator under Requirements and Guidance for Registration (Swedish: Registrering – Tillämpningskrav och vägledning) [SIB.Registration], which establishes the identity of each Entity and its connection to the organization. Registration comprises three checks: verification of organisational affiliation [SIB.Registration.OrgAffiliation], verification of registration submitter [SIB.Registration.Submitter], and verification of display name [SIB.Registration.DisplayName] (Swedish: verifiering av organisationskoppling, uppgiftslämnare och visningsnamn). Each check that has been performed is indicated by a registration policy URI in the Subordinate Statement for the Entity. What the checks mean and how they are performed is stated in [SIB.Registration]. This document states how their outcome is expressed in metadata, so that a peer can read it. The documents are meant to be read together. A metadata value assigned under this specification carries exactly the meaning given to it by the corresponding requirement, and no other.

The protocol requirements build on [Ena.OAuth2], which is the profile that BAS applies. Entities in BAS adhere to that profile. This document restates its metadata requirements and adds the constraints that follow from operating in a federation, where a Client joins the federation rather than registering separately with each Authorization Server it uses. Where the profile leaves a parameter optional but the purposes above require it to be present, this document raises the requirement level. This is the current scope rather than a permanent limitation. BAS may later admit other Entity Types, and Entities adhering to other profiles, and the requirements in this document would then not apply to them unaltered.

The requirements build on a number of further specifications. [OpenID.Federation] defines how metadata is published and resolved. [OIDC.Sweden.Federation] profiles OpenID Federation for use in Swedish federations, a profile that BAS follows, and requires that an Authorization Server accepts and incorporates the metadata of a Client registered in the federation. [RFC7591], [RFC8414] and [RFC9728] define the metadata parameters for the three Entity Types. [OIDC.Sweden.OrgId] defines the parameter that identifies the organization behind an Entity.

The requirement chapters state what has to appear in the Resolved Metadata of an Entity. Common Requirements covers the parameters that all three Entity Types share and that express identity and organizational connection. These requirements do not depend on the choices made for BAS, and are specified so that they can be applied unaltered in other federation contexts. The chapters on Clients, Authorization Servers and Protected Resources contain the requirements that are specific to BAS, including those that support interoperability and Client Registration. BAS Metadata Policies shows how the requirements are enforced, through the metadata policy that the BAS Trust Anchor applies to every Entity, and through the per-Entity values that a Federation Registration Entity sets when an Entity joins the federation. Within BAS these two roles are held by different organizations, the Federation Operator and a Federation Registration Operator, and the document states for every assigned or constrained value which of them controls it.

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 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

1.2. Terminology

This specification uses the terms "Entity", "Entity Configuration", "Entity Identifier", "Entity Type Identifier", "Intermediate Entity", "Leaf Entity", "Subordinate Statement", "Trust Anchor", "Trust Chain" and "Resolved Metadata" as defined in [OpenID.Federation], and the terms "Federation Protocol Entity" and "Federation Registration Entity" as defined in [OIDC.Sweden.Federation]. It uses the terms "Client", "Authorization Server" and "Protected Resource" as defined in [Ena.OAuth2]. Within BAS, the Federation Registration Entity is the connection service (Swedish: anslutningstjänst) that a Federation Registration Operator provides.

This specification also defines the following terms:

Client Registration : The incorporation of a Client into the service configuration of an Authorization Server, based on the Client's Resolved Metadata. Client Registration is distinct from the registration of an Entity in BAS, which a Federation Registration Entity performs by issuing a Subordinate Statement for the Entity.

Federation Member (Swedish: Federationsmedlem) : An organization that has been connected to BAS under [SIB.Connection.Member], and on whose behalf Entities are registered in BAS.

Federation Operator (Swedish: Federationsoperatör) : The organization that operates the BAS Trust Anchor. For BAS, this is the Swedish Agency for Digital Government (Digg).

Federation Registration Operator (Swedish: Anslutningsoperatör) : An organization that has been connected to BAS as a Federation Registration Operator under [SIB.Connection.Operator], and that registers the Entities of Federation Members under [SIB.Registration].

1.3. Scope of the Requirements

The requirements in this document serve the purposes stated in Section 1. Primarily, a party can verify who it is about to exchange information with. In addition, Entities can interoperate according to [Ena.OAuth2], and Client Registration can be based on Resolved Metadata. To that end, this document regulates

• the parameters that identify the Entity and the organization it is registered for (Section 3), and the registration checks that have been performed (Section 7.2),
• the keys and cryptographic algorithms by which the Entity's identity is verified (Sections 2, 4, 5 and 6),
• the way an Entity presents its identity to a peer, including its identifier and, for a Client, its authentication method (Sections 4.1, 4.2, 5 and 6.1),
• the protocol parameters that a peer needs in order to interact with the Entity, including those an Authorization Server needs for Client Registration (Sections 4, 5 and 6),
• the parameters that [Ena.OAuth2] requires an Entity to publish, at the requirement levels that profile states unless this document raises them, and
• which of the Federation Operator and the Federation Registration Operator controls each value that is assigned or constrained in the Trust Chain (Section 7).

Where [Ena.OAuth2] leaves a choice to the individual Entity, such as whether to support mutual TLS client authentication or DPoP, this document may require the Entity to declare its choice in its metadata, but does not make the choice for it. A peer can therefore determine from Resolved Metadata whether an interaction is possible, but the requirements do not ensure that it is.

This document does not regulate the information exchange itself. It places no requirements on which scopes an Authorization Server defines or a Client requests, on the claims carried in access tokens, or on the interface of a Protected Resource. Where such parameters appear in the tables, they are included because the underlying specification defines them, and their values are left to the parties to an exchange.

Nor does this document regulate the decisions that the metadata informs. Whether an Authorization Server accepts a Client, which Clients may obtain access tokens for a Protected Resource, and what access is granted, are decided by the parties to an exchange and are outside the scope of this document.

2. General Requirements

This document specifies metadata requirements for OAuth 2.0 Clients, Authorization Servers and Protected Resources in BAS. The metadata is carried in the metadata Claim of each Entity's Entity Configuration, under the Entity Type Identifier oauth_client, oauth_authorization_server or oauth_resource, as specified in Section 5.1 of [OpenID.Federation]. A Client or Protected Resource that cannot publish an Entity Configuration of its own may have it hosted by the Federation Registration Entity according to [OIDC.Sweden.Hosting], in which case the requirements below apply to the hosted document.

The requirements apply to the Resolved Metadata, meaning the metadata that results from applying the Subordinate Statements of the Trust Chain to the Entity's own declarations, see Section 10 of [OpenID.Federation]. A Federation Registration Entity may assign or refine values in the Subordinate Statement it issues, see Section 2.5 of [OIDC.Sweden.Federation]. Some requirements apply to every Entity in BAS rather than to an individual Entity, and these are enforced through the metadata policy that the Trust Anchor applies. A parameter that is REQUIRED in the Resolved Metadata is therefore not always a parameter the Entity has to declare itself. Where a Federation Registration Entity supplies or modifies a value, or a metadata policy constrains it, the Description column says so.

Some metadata values are verified by the Federation Registration Operator when an Entity is registered, and are fixed by the Federation Registration Entity in the Subordinate Statement for the Entity. Which values are verified, and how, is stated in [BAS.Rules]. Section 7.2 states how the values are assigned.

Metadata values intended for human consumption are provided in both Swedish and English using language tags, as stated in [Ena.OAuth2]. Within BAS, Swedish is the default language. The Federation Registration Entity assigns a corresponding parameter without a language tag, holding the Swedish value, in the Subordinate Statement, so that the Resolved Metadata always contains it and implementations without support for language tags can use it. A value without a language tag that the Entity declares itself is replaced by the value assigned by the Federation Registration Entity.

"client_name#sv" : "Min tjänst",
"client_name#en" : "My service",
"client_name" : "Min tjänst" <- assigned by the Federation Registration Entity

Example: Multilingual parameter.

The keys that an Entity uses in the OAuth 2.0 protocol, as opposed to the Federation Entity Keys that sign its Entity Statements, are published in its oauth_client, oauth_authorization_server or oauth_resource metadata, as stated in Sections 4 to 6. The keys MUST meet the requirements of Section 8.2 of [Ena.OAuth2], which state the algorithms and minimum key lengths that apply. To allow every peer to select the correct key, including when a key is replaced, each JWK MUST include a kid parameter, also when the JWK Set holds a single key.

This document does not specify the Entity Statement Claims themselves, such as iss, sub, iat, exp, jwks, authority_hints and trust_marks, with the exception of the registration_policy Claim, see Section 7.2. Those Claims are defined by Section 3.1 of [OpenID.Federation] and profiled by [OIDC.Sweden.Federation]. Clients, Authorization Servers and Protected Resources are Federation Protocol Entities, and therefore always Leaf Entities, so their Entity Configurations MUST NOT contain metadata of the Entity Type federation_entity, see Section 2.2 of [OIDC.Sweden.Federation].

A parameter that is not listed in the tables below MAY be used at the requirement level given by the specification that defines it. Where a table states a requirement level that differs from the level given by the defining specification, the level stated in the table is the one that applies within BAS.

3. Common Requirements

The table below covers the metadata parameters that Clients, Authorization Servers and Protected Resources publish with the same meaning in their oauth_client, oauth_authorization_server and oauth_resource metadata, respectively. These parameters describe the Entity and the organization behind it, and are defined in Section 5.2.2 of [OpenID.Federation]. Some of these values are verified when an Entity is registered, see Section 2.

Table 1: Organization and informational metadata parameters.

3.1. The organization_identifier Format

A Swedish organization number is a ten-digit string, without a hyphen, according to [SKV709]. To allow BAS to interoperate with other federations, the identifier MUST be expressed as a GLUE-URI [I-D.ietf-spice-glue-id] using ISO/IEC 6523 [ISO.6523] representation. The format for such identifiers is urn:glue:iso6523:<icd>:<organization-number>, where icd stands for International Code Designator, the ISO/IEC 6523 code identifying the scheme that issued the identifier. Swedish organization numbers are registered under ICD 0007, assigned to the Swedish Tax Agency (Skatteverket), so all Swedish organization numbers are prefixed with urn:glue:iso6523:0007:.

"organization_identifier" : "urn:glue:iso6523:0007:2021006883"

Example of how the organization number for the Swedish Agency for Digital Government (Digg) is represented in an organization_identifier.

4. OAuth Client Requirements

The table below covers the metadata parameters that a Client publishes in its oauth_client metadata, in addition to those in Section 3. The parameters are defined in Section 2 of [RFC7591], and profiled by Section 2.2.2 of [Ena.OAuth2]. This version of the document covers Clients that use the client_credentials grant, which is the grant type that [BAS.Rules] permits. Parameters that apply only to other grant types, such as redirect_uris, require_signed_request_object and require_pushed_authorization_requests, are therefore not used.

Table 2: Client metadata parameters.

4.1. Client Identifier

The client identifier of a Client in BAS is its Entity Identifier. A Client MUST use its Entity Identifier as client_id at every Authorization Server it interacts with. This fulfils the requirement of Section 2.2.1 of [Ena.OAuth2] that a Client in a federative context uses the same client identifier for all registrations, and allows every Authorization Server to verify the Client's identity and organizational connection through its Trust Chain.

4.2. Client Authentication

A Client in BAS authenticates at the token endpoint using the private_key_jwt method, as specified in Section 8.3.1 of [Ena.OAuth2]. Every Authorization Server compliant with [Ena.OAuth2] supports this method, see Section 5, so a Client using it can authenticate at every Authorization Server in BAS. The keys used for signing are those published in jwks or jwks_uri.

5. Authorization Server Requirements

The table below covers the metadata parameters that an Authorization Server publishes in its oauth_authorization_server metadata, in addition to those in Section 3. The parameters are defined in Section 2 of [RFC8414], and profiled by Section 3.1.1 of [Ena.OAuth2]. Parameters that apply only to grant types other than client_credentials, such as authorization_endpoint, pushed_authorization_request_endpoint, code_challenge_methods_supported and require_signed_request_object, are not used.

An Authorization Server also publishes its metadata at the location stated in Section 3.1.2 of [Ena.OAuth2]. For every parameter that appears in both, the metadata published there MUST be consistent with the Authorization Server's Resolved Metadata.

Table 3: Authorization Server metadata parameters.

6. Protected Resource Requirements

The table below covers the metadata parameters that a Protected Resource publishes in its oauth_resource metadata, in addition to those in Section 3. The parameters are defined in Section 2 of [RFC9728], and profiled by Section 4.3 of [Ena.OAuth2].

Table 4: Protected Resource metadata parameters.

6.1. Resource Identifier

The resource identifier of a Protected Resource in BAS is its Entity Identifier. The resource parameter MUST be equal to the Entity Identifier, and MUST meet the requirements of Section 4.3 of [Ena.OAuth2]: it is a URL using the HTTPS scheme with a host component, it SHOULD NOT include a query component, and it MUST NOT include a fragment component. An Authorization Server uses the resource identifier as the audience of the access tokens it issues for the Protected Resource, see Section 6.1.1 of [Ena.OAuth2]. Resources that do not share the same access rules are registered as separate Entities, each with its own resource identifier, as recommended in Section 4.3 of [Ena.OAuth2].