Swedish OpenID Federation Deployment and Interoperability Profile 1.0 - draft 00

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 document extends Section 1.2 of [OpenID.Federation] by introducing the following terms to improve the readability of this profile:¶

Federation Protocol Entity

An Entity within the federation that fulfils a protocol role, such as an OpenID Provider, OpenID Connect Relying Party, OAuth 2.0 Authorization Server, OAuth 2.0 Client, or OAuth 2.0 Protected Resource. This is typically a Leaf Entity.
¶

Federation Service Entity

An Entity within the federation that does not play a protocol role but instead takes on an operational role within the federation, such as a Trust Anchor, an Intermediate Entity, or a Trust Mark Issuer.
¶

Federation Registration Entity

A Superior Entity within the federation with which a Federation Protocol Entity (for example, an OpenID Connect Relying Party) registers to join the federation. This involves the collection of Entity Configuration and metadata, and the creation of an Entity Statement.
¶

Federation Resolver

A Federation Service Entity that provides functionality for obtaining Resolved Metadata and Trust Marks for a given Entity.¶

2.1. Responsibilities of a Federation Operator

This section describes the responsibilities of a Federation Operator, as manifested by a Trust Anchor, when establishing and operating a federation.¶

A Federation Operator MUST define Federation Rules that govern the operation of the federation and the conduct of its members. These rules encompass both technical requirements and non-technical processes. The following requirements apply to Federation Rules:¶

• A Federation Operator MUST define rules and requirements for joining the federation. It is RECOMMENDED that Registration Policies are defined; see Section 3.2.¶

• A Federation Operator SHOULD define protocol-specific requirements, including which underlying standards and profiles federation members are required to comply with. This includes interoperability requirements such as regulated algorithm support and requirements for Entity metadata. See Section 7, Adapting OAuth 2.0 and OpenID Connect for OpenID Federation.¶

• A Federation Operator SHOULD define and maintain a Trust Mark Policy. See Section 5.1.¶

• It is RECOMMENDED that the Federation Operator defines federation-wide security requirements, such as minimum key lengths, key rollover frequency, and client authentication requirements.¶

• A Federation Operator SHOULD define recommended validity periods for Entity Statements in order to promote predictable behaviour and operational stability; see Section 2.4.1.¶

• A Federation Operator SHOULD define a base URL, or domain, for the federation. This base URL SHOULD be used when defining collision-resistant URLs within the federation context, such as Trust Mark type identifiers.¶

Some of the above rules are enforced through metadata policies or constraints, while others are enforced by operational means such as audits and controls.¶

2.2. Federation Entity Types

[OpenID.Federation] does not restrict how federation roles may be combined by a Federation Entity operating under a single Entity Identifier. However, combining the role of an Intermediate Entity with that of a Federation Protocol Entity, such as an OpenID Provider, can introduce challenges and unnecessary complexity. Most importantly, it may lead to conflicts between the contents of the metadata Claim and the metadata_policy Claim in subordinate Entity Statements.¶

Therefore, implementers of this profile MUST NOT combine the role of a Trust Anchor, Intermediate Entity, Trust Mark Issuer, or Federation Resolver with that of a Federation Protocol Entity under the same Entity Identifier.¶

This requirement implies that a Federation Protocol Entity is always a Leaf Entity and that its Entity Configuration MUST NOT include metadata of type federation_entity.¶

2.3. Federation Resolvers

Section 10 of [OpenID.Federation] specifies requirements for how an Entity resolves the Trust Chain and metadata of another Entity with which it wishes to establish trust. This process includes fetching Entity Statements, applying metadata policies and constraints, validating Trust Chains, and handling caching. The procedure is complex and may be difficult for all Federation Protocol Entities within the federation to implement.¶

Also, this algorithm relies on all participants publishing their Entity Configuration information at a well-known location, as specified in Section 9 of [OpenID.Federation]. However, this profile references an alternative way of publishing Entity Configuration (see Section 2.4.2 below), that requires a chain building algorithm starting with a Trust Anchor instead of the bottom-up approach specified in Section 10 of [OpenID.Federation].¶

Therefore, it is RECOMMENDED that Entities compliant with this profile use a Federation Resolver in order to resolve metadata and trust for peer Entities. A Federation Resolver is an Entity within the federation that provides a federation_resolve_endpoint as specified in Sections 5.1.1 and 8.3 of [OpenID.Federation].¶

A Trust Anchor adhering to this profile MUST ensure the availability of at least one Federation Resolver compliant with the requirements stated in this profile. This resolver MUST support resolving for the given Trust Anchor. It is RECOMMENDED that the resolver is provided as part of the Trust Anchor itself.¶

Section 4, Resolving Metadata and Trust Marks, specifies further requirements for Federation Resolver usage and implementation.¶

2.4. Entity Statements

This section defines requirements and recommendations for Entity Statements defined in Section 3 of [OpenID.Federation].¶

2.5. Controlling Metadata for Subordinates

A Superior Entity can control the resolved metadata of a Subordinate Entity either by assigning metadata values under the metadata Claim in a Subordinate Statement, or by using the metadata_policy Claim as defined in Section 6.1 of [OpenID.Federation]. In the latter case, the policy applies to all Entities that are Subordinates of the Entity that sets the policy.¶

This section specifies requirements and recommendations for metadata control in order to prevent unpredictable behaviour and to avoid metadata merge conflicts when chaining across federation contexts.¶

An Entity's Entity Configuration contains a metadata Claim in which the Entity declares parameters describing its preferences and capabilities. A metadata policy, as specified in Section 6.1 of [OpenID.Federation], may be included in Subordinate Statements to modify the metadata declared by an Entity.¶

Since any Entity in a Trust Chain that issues Subordinate Statements may define metadata policies, the effective metadata of an Entity is the result of merging all applicable policies along the chain. If a policy introduces parameter values that were not originally declared by the Entity, the resolved metadata may include capabilities or preferences that the Entity does not support. This can lead to unpredictable or invalid configurations.¶

Furthermore, merging multiple metadata policies in a Trust Chain may lead to merge conflicts, making it impossible to validate the metadata through that chain in a meaningful way. The risk of such conflicts increases when complex policies are defined by lower-level Entities in the chain.¶

This profile therefore specifies the following requirements:¶

• Adding metadata parameter values to an Entity's metadata SHOULD be limited to the Entity itself and its Immediate Superior Entity responsible for registering the Entity in the federation.¶

• An Immediate Superior Entity that needs to add metadata parameter values to an Entity's resolved metadata SHOULD declare these values directly in the metadata Claim of the Entity Statement issued for the Entity, and SHOULD NOT use metadata policy operators for this purpose.¶

Metadata policies SHOULD be used to constrain, filter, or refine metadata values declared by the Entity, and SHOULD NOT be used to introduce capabilities or preferences that are unknown to the Entity.¶

Metadata parameters can broadly be divided into two categories:¶

• Descriptive parameters that characterise the Entity, such as display name, logotype, and organizational affiliation.¶

• Protocol parameters that define security and functional settings, such as keys, algorithms, and endpoint URLs.¶

Deployments compliant with this profile SHOULD concentrate metadata policies that control security and functional settings at Trust Anchors.¶

Adhering to this requirement, together with the requirement in Section 2.6.1 that Federation Protocol Entities are not chained directly under a Trust Anchor, enables the construction of alternative trust paths towards other Trust Anchors without requiring the application of multiple Trust Anchor metadata policies. This reduces the risk of merge conflicts caused by incompatible policies.¶

2.6. Federation Hierarchy Requirements and Recommendations

[OpenID.Federation] defines an infrastructure in which multiple federation contexts may co-exist without clear boundaries between them. Each federation context is anchored by a common Trust Anchor. A Trust Anchor defines a policy that all subordinate services must satisfy in order for their metadata to be validated through that Trust Anchor.¶

A Federation Protocol Entity or Federation Service Entity may chain to more than one Trust Anchor. Chaining to a Trust Anchor does not, however, guarantee successful validation. Validation succeeds only if the Federation Protocol Entity's metadata conforms to the combined metadata policies of all Entities in the Trust Chain up to and including the Trust Anchor.¶

It is therefore important to structure the hierarchy of Federation Service Entities and their metadata policies carefully. The aim is to enforce essential rules while avoiding the unintended blocking of legitimate services due to incompatible policy applications.¶

This section contains sub-sections with requirements and recommendations for structuring a federation hierarchy in order to avoid unnecessary complexity and pitfalls.¶

3.1. Role of the Federation Registration Entity

A Federation Registration Entity is a Superior Entity within the federation with which a Federation Protocol Entity (for example, an OpenID Connect Relying Party) registers to join the federation.¶

How the registration is initiated is out of scope for this profile, but one example is that the Federation Registration Entity provides an application to which Entity administrators log in and request registration for their Entity.¶

The Federation Registration Entity registers an Entity by creating and signing a Subordinate Statement for this Entity. Thus, the following aspects of an Entity being registered are vouched for by its Immediate Superior Entity:¶

• The binding of a federation key to an Entity Identifier.¶

• That the Entity holding the federation key is the legitimate Entity representing this Entity Identifier.¶

• That the Entity holding the federation key is a legitimate member of the community implied by membership within a particular federation and can be trusted as such.¶

The registration is performed according to a Registration Policy, and in order for other participants within a federation to trust a registered Entity, they must trust and accept the policy under which the Entity joined the federation. See Section 3.2 below.¶

If the Federation Registration Entity includes metadata values in Subordinate Statements, these values SHOULD be limited to fixing descriptive Entity metadata that was controlled during registration. Typically, such values include display names or organizational affiliation. Constraining other metadata values is the responsibility of the Trust Anchor, see Section 2.5.¶

An Intermediate Entity acting as a Federation Registration Entity and compliant with this profile MUST expose a subordinate listing endpoint as defined in Section 8.2 of [OpenID.Federation].¶

3.2. Use of Registration Policies

A Federation Registration Entity that creates a Subordinate Statement for an Entity follows a set of rules, described by a Registration Policy, during the registration process. Such rules may comprise:¶

• Checks to ensure that the organization behind the Entity has entered into the required agreements necessary for federation membership.¶

• Checks to ensure that the individual requesting that the Entity be added to the federation is authorized to do so, for example by validating that the person is authorized to represent the organization that owns the Entity. This may also involve requirements on the authentication strength for the Entity administrator.¶

• Checks to determine the ownership of domains. This is especially important when Entity Configuration Hosting is supported, see Section 4.1 of [OpenID.Federation.Hosting].¶

• Assertions that Entity informational metadata parameters such as organization_name and display_name contain values that correspond to the organization behind the Entity.¶

It is RECOMMENDED that federation deployments compliant with this profile define Registration Policy URIs for the policies that are used for registering Entities, and that Federation Registration Entities include the registration_policy Claim as defined by [OpenID.Federation.RegPolicy].¶

Note: A Trust Mark could in theory be used to represent that a certain policy was applied during registration of an Entity to the federation. However, there is an important distinction between Registration Policies and Trust Marks. Whether an Entity holds a particular Trust Mark is typically checked by other Entities after its metadata and Trust Marks have been resolved and validated. Registration Policies, on the other hand, operate as part of the Trust Chain building process and are enforced through constraints defined by the federation.¶

4.1. Federation Resolver Requirements

A Trust Anchor or an Intermediate Entity that provides a federation_resolve_endpoint is regarded to be a Federation Resolver.¶

This section extends the requirements specified in Section 8.3 of [OpenID.Federation] with the following statements:¶

A Federation Resolver MAY include Trust Marks that are not present in an Entity's Entity Configuration. It can do so by communicating directly with a Trust Mark Issuer. This functionality may be useful in cases when Trust Marks are being used a control mechanism within the federation and Entities within the federation are unaware of a particular Trust Mark type.¶

The requirements for the resolve response exp Claim given in Section 8.3.2 of [OpenID.Federation] states that the validity of the response must not exceed the validities of the underlying Trust Chain and Trust Marks included. If a Trust Mark instance for the Entity is being resolved is either expired, or has a validity that is shorter than the validity of the Trust Chain, it is RECOMMENDED that the resolver obtains a new Trust Mark instance for the Entity by calling the Trust Mark endpoint at the Trust Mark Issuer.¶

By following this requirement, the Federation Resolver avoids issuing resolve responses with unnecessarily short validity periods. This reduces the frequency of resolve requests, as longer-lived responses are more amenable to caching by consuming parties.¶

4.2. Using a Federation Resolver

The resolve endpoint, request and response formats are defined in Section 8.3 of [OpenID.Federation].¶

5.1. Trust Mark Policy

A Federation Operator SHOULD define a Trust Mark Policy for the federation. The Trust Mark Policy MUST define:¶

• Rules and processes for designating which actors may act as federation-accredited Trust Mark Issuers.¶

• Rules and requirements applicable to federation-accredited Trust Mark Issuers. The requirements stated in Section 5.2 apply, but the policy may define additional requirements, such as the authorization criteria that determine whether a Trust Mark can be issued to a given Entity.¶

• Rules and processes for defining Trust Mark types recognized by the federation, including which Trust Mark Issuer(s) may issue each Trust Mark type.¶

• The URL identifiers for Trust Mark types recognized within the federation.
  
  Note: The definition of these identifiers cannot be delegated to Trust Mark Issuers, since it is the responsibility of the Federation Operator to ensure that they are collision-resistant across multiple federations, see Section 7.1 of [OpenID.Federation].¶

• Whether Trust Mark Issuers may issue Trust Mark types that are not recognized federation-wide, for example Trust Marks intended for specific purposes or specific Entity audiences.¶

A Trust Mark Policy MAY also define rules or recommendations for the validation of Trust Marks, see Section 7.3 of [OpenID.Federation]. If validation rules are defined, it is RECOMMENDED that these also cover requirements for Trust Mark status checking.¶

Note: Only a federation-accredited Trust Mark Issuer is allowed to issue Trust Mark types that are recognized by the federation. A Trust Mark Issuer is considered federation-accredited when it appears in the trust_mark_issuers Claim of the Trust Anchor's Entity Configuration, as defined in Section 7 of [OpenID.Federation]. This Claim also identifies which Trust Mark types are recognized by the federation, and which Trust Mark Issuers are authorized to issue each type.¶

5.2. Requirements on Trust Mark Issuers

A Federation Service Entity that exposes a Trust Mark endpoint as defined in Section 8.3.3 of [OpenID.Federation], is a Trust Mark Issuer.¶

A Trust Mark Issuer wishing to issue Trust Marks that should be recognized within the federation MUST coordinate with, and apply at, the Federation Operator (Trust Anchor) to have both the Trust Mark Issuer and the Trust Mark type listed in Trust Anchor's trust_mark_issuers Entity Configuration Claim. In these cases, it is the responsibility of the Federation Operator to define the Trust Mark type identifier to be used.¶

The Trust Mark Issuer is responsible for maintaining a repository of the Entities that are entitled to specific Trust Mark types, including the authorizations and limitations that apply to them. The procedures by which an Entity applies for a Trust Mark, and the procedures used to determine whether a Trust Mark is granted, are outside the scope of this profile.¶

If short-lived Trust Mark instances, that is, JWTs with an exp Claim set to a near-term time, are issued, this affects the validity of Entity Configurations that include such Trust Marks. Consequently, the validity period of resolve responses issued by a Federation Resolver may also need to be reduced.¶

The practical consequences include the following:¶

• Leaf Entities have to obtain new Trust Mark instances frequently and update and re-sign their Entity Configurations accordingly.¶

• Federation Resolvers will be required to issue resolve responses with short validity periods, since a resolve response cannot exceed the validity of the artefacts it contains, see Section 8.3.2 of [OpenID.Federation]. This limits the ability to cache resolve responses within the federation and increases the number of invocations to Federation Resolvers.¶

Therefore, the following requirements apply to Trust Mark Issuers that are compliant with this profile:¶

• The validity period of a Trust Mark JWT SHOULD be aligned with the validity of the underlying authorization that determines the Entity’s entitlement to the Trust Mark. If that authorization is not time-limited, the Trust Mark Issuer SHOULD NOT include an exp Claim in the Trust Mark JWT.¶

• A Trust Mark Issuer MUST expose a Trust Mark Status endpoint, as defined in Section 8.4 of [OpenID.Federation]. This is required because the use of long-lived Trust Mark instances needs to be combined with status checking, that is, verifying that the Trust Mark privileges for the holder have not been revoked.¶

A Federation Service Entity can choose to require client authentication for its federation endpoints.¶

When a Trust Mark Issuer deployment is configured to require client authentication for its Trust Mark endpoint, see Section 8.6 of [OpenID.Federation], the Federation Operator SHOULD be consulted to obtain information about which Entities are permitted to request a Trust Mark on behalf of another Entity. Typically, these are Federation Resolvers that retrieve a subject’s Trust Marks as part of the resolve process, see Section 4.1, Federation Resolver Requirements, or an Intermediate Entity acting as a Federation Registration Entity that retrieves Trust Marks on behalf of Entities being registered.¶

7.1. Algorithm Support

In both OAuth 2.0 and OpenID Connect, a client or Relying Party declares one algorithm in its registration data for each specific usage. For example, token_endpoint_auth_signing_alg [OpenID.Registration] declares which signature algorithm a Relying Party uses when signing a JWT for authentication at the OpenID Provider token endpoint. The Relying Party selects a suitable algorithm based on the token_endpoint_auth_signing_alg_values_supported in the OpenID Provider's Discovery Document [OpenID.Discovery].¶

In a federation, where a client's metadata may be consumed by several peers, this approach breaks down, since different servers (Authorization Servers or OpenID Providers) may support different sets of algorithms, and the intersection of those sets may be empty.¶

"OpenID Connect Relying Party Metadata Choices 1.0" [OpenID.RP.Choices] attempts to solve this problem by introducing metadata parameters through which a Relying Party can declare which algorithms it supports, allowing the OpenID Provider to use these values during client registration. This approach works in deployments where all Relying Parties and all OpenID Providers fully support that specification.¶

However, this profile does not impose such requirements. Instead, it specifies a set of algorithms that are mandatory to support. This ensures that legacy systems that are not fully OpenID Federation-compliant can still function within the federation.¶

OAuth 2.0 Clients, OAuth 2.0 Authorization Servers, OpenID Connect Relying Parties, and OpenID Connect OpenID Providers compliant with this profile MUST adhere to the algorithm requirements specified below.¶

All compliant Entities MUST support validation of signatures using any of the following algorithms:¶

• RS256, RSASSA-PKCS1-v1_5 using SHA-256, as defined in Section 3.3 of [RFC7518].¶
• RS384, RSASSA-PKCS1-v1_5 using SHA-384, as defined in Section 3.3 of [RFC7518].¶
• RS512, RSASSA-PKCS1-v1_5 using SHA-512, as defined in Section 3.3 of [RFC7518].¶
• ES256, ECDSA using P-256 and SHA-256, as defined in Section 3.4 of [RFC7518].¶
• ES384, ECDSA using P-384 and SHA-384, as defined in Section 3.4 of [RFC7518].¶
• ES512, ECDSA using P-521 and SHA-512, as defined in Section 3.4 of [RFC7518].¶

All compliant Entities MUST support encryption using any of the following algorithms:¶

• RSA-OAEP, RSAES OAEP using default parameters, as defined in Section 4.3 of [RFC7518].¶
• RSA-OAEP-256, RSAES OAEP using SHA-256 and MGF1 with SHA-256, as defined in Section 4.3 of [RFC7518].¶
• ECDH-ES, ECDH Ephemeral Static direct key agreement, as defined in Section 4.6 of [RFC7518].¶

An Entity holding an RSA protocol key MUST support decryption using any of the following algorithms:¶

• RSA-OAEP, RSAES OAEP using default parameters, as defined in Section 4.3 of [RFC7518].¶
• RSA-OAEP-256, RSAES OAEP using SHA-256 and MGF1 with SHA-256, as defined in Section 4.3 of [RFC7518].¶

An Entity holding an EC protocol key MUST support decryption using the following algorithm:¶

• ECDH-ES, ECDH Ephemeral Static direct key agreement, as defined in Section 4.6 of [RFC7518].¶

Profiles extending this profile, or a Federation Operator's federation rules, MAY mandate additional algorithms to support.¶

7.2. Client Authentication Methods

Similarly to algorithms, the token_endpoint_auth_method parameter [RFC7591][OpenID.Registration] can only hold one value. In a federation, a single set of client metadata may be resolved and consumed by any number of servers. This may cause interoperability problems if two servers that the client needs to interact with have different and non-overlapping requirements for client authentication, as the client would be unable to satisfy both simultaneously.¶

It is RECOMMENDED that the Federation Operator defines requirements for which client authentication methods OAuth 2.0 Authorization Servers and OpenID Connect OpenID Providers should support, in order to avoid such interoperability problems. This can be done by referring to a specific profile, or by including such requirements in the federation rules.¶

7.3. Additional Considerations

This section presents a non-exhaustive list of topics where a Federation Operator, or members of the federation, need to be aware of potential interoperability issues or semantic differences between non-federation OAuth 2.0 and OpenID Connect and their use within an OpenID Federation deployment.¶

Within OpenID Federation, resolved metadata for a client Entity is metadata produced by the client itself, possibly modified by metadata policies. It is therefore the client's self-declared metadata. In contrast, in a non-federation OAuth 2.0 or OpenID Connect deployment, client metadata is the result of a registration operation, and the metadata parameters have been approved and authorized by the Authorization Server or OpenID Provider. An Authorization Server or OpenID Provider functioning within an OpenID Federation deployment MUST be aware of this difference, and employ appropriate mechanisms when consuming client metadata obtained from the federation.¶

OAuth 2.0 Scopes: An Authorization Server declares its supported scopes using the scopes_supported parameter [RFC8414], and an OAuth 2.0 client's metadata may contain a scope parameter [RFC7591] listing the scopes it intends to use when requesting tokens. In a non-federation deployment, these scopes may have been authorized as part of the registration process (see above). In an OpenID Federation deployment, other mechanisms are needed to establish trust in such scope declarations.¶

Furthermore, in a peer-to-peer registration, any scopes referenced are in the context of that specific registration. In an OpenID Federation deployment, generic scope values such as read or write may be ambiguous, since a client may interact with multiple Authorization Servers. One approach to mitigating this is to use distinct scope values mapped to specific resources or functions.¶

OpenID Connect Subject Types: Section 2 of [OpenID.Registration] defines the subject_type metadata parameter, which is used by an OpenID Connect Relying Party to declare whether it requires subject identifiers in tokens to be public or pairwise. Correspondingly, an OpenID Provider's Discovery metadata contains the subject_types_supported parameter [OpenID.Discovery], listing the subject types the OpenID Provider supports. If OpenID Providers within the federation do not support both types, interoperability issues may arise. It is RECOMMENDED that the Federation Operator, via referenced profiles or federation rules, requires OpenID Providers to support both the public and pairwise subject types.¶