SIB BAS - Metadata requirements

Ett utkast som diskussionsunderlag.

Document purpose and status

DRAFT

When registering an entity in the SIB federation, the entity must provide a metadata document in its Entity Configuration, either published on a URL or hosted at the federation Intermediary service.

Some metadata are mandatory to comply with [OpenID.Federation] such as iss, keys and sub. Other metadata are optional in the standard, and the SIB federation rules will complement the standard with additional requirements with the purpose of interoperability and security.

This document consists of a draft of metadata requirements for the SIB BAS federation as a starting point for a discussion.

Common metadata requirements

Metadata	Description	Requirement	Defined in	Comment
organization_name	The name of the organization that owns the Entity.	REQUIRED	[OpenID.Fed] as OPTIONAL	Assigned by Intermediary Operator. The term “owner” should be interpreted as the organization that is the federation member and has the appropriate contractual agreement with the federation.
organization_identifier	A unique identifier for the organization that owns the Entity. For details see Organization identifier formats	REQUIRED	[OpenID.Fed.Org.Id] ( extending [OpenID.Fed] )	Assigned by Intermediary Operator.
registration_policy	identifiers for one or more registration policies that were applied when registering an Entity as a trusted Entity within the federation.	REQUIRED	[OpenID.Fed.Reg.Policy] ( extending [OpenID.Fed] )	Assigned by Intermediary Operator.
contacts	Contact addresses for the people or groups responsible for operating the Entity. The value MUST hold at least one email address.	RECOMMENDED	[OpenID.Fed] as OPTIONAL
description	A human-readable brief description of this Entity presentable to the End-User.	OPTIONAL	[OpenID.Fed] as OPTIONAL
information_uri	A URL to further documentation about the Entity, viewable by the end-user.	OPTIONAL	[OpenID.Fed] as OPTIONAL
organization_uri	A URL to a web page for the organization that owns the Entity.	OPTIONAL	[OpenID.Fed] as OPTIONAL
logo_uri	A URL that points to the logo of this Entity	OPTIONAL	[OpenID.Fed] as OPTIONAL
keywords	Search keywords, tags, or categories that apply to the Entity.	OPTIONAL	[OpenID.Fed] as OPTIONAL
policy_uri	URL of the documentation of conditions and policies relevant to this Entity	OPTIONAL	[OpenID.Fed] as OPTIONAL

Common security requirements

See https://www.oidc.se/specifications/swedish-openid-federation-profile.html#name-federation-algorithm-requir

Includes requirements for:

support for signing and encryption algorithms
support för client authentication methods

Proposed for SIB BAS:
Client authentication: private_key_jwt is REQUIRED.

OAuth2 Client metadata requirements

Metadata	Description	Requirement	Defined in	Comment
token_endpoint_auth_method	Authentication method used to authenticate with the token endpoint.	REQUIRED The value MUST be set to private_key_jwt.		Compare with Sweden Connect Metadata requirements for RPs: The value MUST be set to `private_key_jwt`.
token_endpoint_auth_signing_alg	Signature algorithm used when authenticating with the token endpoint	REQUIRED when private_key_jwt is used.
redirect_uris		REQUIRED if the client is registered for the authorization_code grant type
jwks	The Entity's JSON Web Key Set, representing the Entity's protocol keys, included by value in the metadata.	REQUIRED if jwks_uri is not provided	[OpenID.Fed]
jwks_uri	URL referencing a JWK Set document containing the Entity's protocol keys for that Entity Type	REQUIRED if jwks is not provided	[OpenID.Fed]
signed_jwks_uri	URL referencing a signed JWT having the Entity's JWK Set document, representing the Entity's protocol keys for that Entity Type as its payload	OPTIONAL	[OpenID.Fed]
grant_types	Which OAuth grant types the client uses.	OPTIONAL? RECOMMENDED?		[Ena.OAuth]: OPTIONAL, and if not present, the authorization_code grant type MUST be assumed.
scope	list of scope values that the client can use when requesting access tokens	OPTIONAL

Note: [OpenID.Federation]: “It is RECOMMENDED that an Entity Configuration use only one of jwks, jwks_uri, and signed_jwks_uri in its OpenID Connect or OAuth 2.0 metadata.”

Note: [Ena.OAuth]:If the client has registered the private_key_jwt token endpoint authentication method, or if the client produces signatures in other circumstances, one, but not both, of the jwks and jwks_uri parameters is REQUIRED.

Human-readable Client Metadata

Client metadata values intended for human consumption, either directly or via reference (URIs), SHOULD be provided in both English and Swedish using language tags according to BCP 47, [RFC5646].

OAuth2 Authorization Server metadata requirements

Metadata	Description	Requirement	Defined in	Comment
issuer	MUST be a globally unique URL. ”Corresponds” to where the authorization server metadata is located.	REQUIRED	[RFC8414], REQUIRED
grant_types_supported	Supported Grant Types	OPTIONAL The same requirements as specified in Section 2 of [RFC8414], with the following exception: If the parameter is omitted, the default value SHALL be [ "authorization_code" ].	[RFC8414], OPTIONAL, ["authorization_code", "implicit"] is default if not present	Note: [Ena.OAuth]: If the parameter is omitted, the default value SHALL be "authorization_code" Could it be a risk to change the default of the standard?
token_endpoint	Endpoint for requesting access tokens	REQUIRED	[RFC8414], REQUIRED
token_endpoint_auth_methods_supported	Client authentication methods supported by the token endpoint.	REQUIRED and MUST include private_key_jwt.	[RFC8414] OPTIONAL, client_secret_basic is default if not present	In line with the security requirements
token_endpoint_auth_signing_alg_values_supported	JWS signing algorithms for client authentication supported by the token endpoint.	REQUIRED and MUST conform to the signature requirements (separately specified)	[RFC8414] REQUIRED when private_key_jwt is used.
scopes_supported	scopes supported by the authorization server	REQUIRED SHOULD list all scopes supported by the authorization server	[RFC8414] , RECOMMENDED [Ena.OAuth] REQUIRED	What is the rationale for this sharper requirement in Ena.OAuth?
dpop_signing_alg_values_supported	JWS algorithms supported for DPoP proof JWTs. Signals that the authorization server supports the DPoP mechanism.	RECOMMENDED	[Ena.OAuth] RECOMMENDED The use of DPoP is recommended to mitigate replay attacks.
authorization_response_iss_parameter_supported	indicates whether the authorization server supports including the issuer parameter in authorization responses to protect against Authorization Server Mix-Up Attacks	SHOULD OPTIONAL?	[RFC9207] [Ena.OAuth] SHOULD be used and be set to true, for authorization servers within a federation	issuer is already required, so this could be OPTIONAL because this is only an indication?
jwks	The Entity's JSON Web Key Set, representing the Entity's protocol keys, included by value in the metadata.	REQUIRED if jwks_uri is not provided	[OpenID.Fed]	[Ena.OAuth], and [RFC8414] does NOT include this. Not supported?
jwks_uri	URL referencing a JWK Set document containing the Entity's protocol keys for that Entity Type	REQUIRED if jwks is not provided	[OpenID.Fed] REQUIRED if jwks is not provided [RFC8414] OPTIONAL [Ena.OAuth] REQUIRED	[Ena.OAuth] has this as the only option - why?
signed_jwks_uri	URL referencing a signed JWT having the Entity's JWK Set document, representing the Entity's protocol keys for that Entity Type as its payload	OPTIONAL	[OpenID.Fed]	[Ena.OAuth], and [RFC8414] does NOT include this. Not supported?
Below is ONLY applicable IF the corresponding features are supported.
authorization_endpoint	URL of the authorization server's authorization endpoint	REQUIRED IF authorization code grant type is supported.	[RFC8414] REQUIRED unless no grant types are supported that use the authorization endpoint	Out of cope for SIB BAS Step 1, but should be included.
code_challenge_methods_supported	PKCE [RFC7636] code challenge methods supported	REQUIRED IF authorization code grant type is supported.	[RFC8414] OPTIONAL [Ena.OAuth] REQUIRED for authorization code grant.
ui_locales_supported	Languages and scripts supported for the user interface	SHOULD and should include Swedish (sv) and English (en).	[RFC8414] OPTIONAL [Ena.OAuth] SHOULD.	Should only be relevant if the authorization endpoint is supported.
pushed_authorization_request_endpoint	URL of the authorization server's endpoint for pushed authorization requests	REQUIRED IF pushed authorization requests are supported.	Section 5 of [RFC9126] (extension) [Ena.OAuth] CONDITIONAL
protected_resources	resource identifiers for OAuth protected resources as defined Section 4 of [RFC9728]	OPTIONAL	[Ena.OAuth] RECOMMENDED	An extension to RFC8414.
registration_endpoint	URL of the authorization server's OAuth 2.0 Dynamic Client Registration endpoint	OPTIONAL	[RFC8414] OPTIONAL
revocation_endpoint	URL of the authorization server's revocation endpoint	OPTIONAL	[RFC8414] OPTIONAL
revocation_endpoint_auth_methods_supported	client authentication methods supported by this revocation endpoint	OPTIONAL	[RFC8414] OPTIONAL
revocation_endpoint_auth_signing_alg_values_supported	signing algorithms supported by this endpoint for the signature on the JWT, when used with private_key_jwt	OPTIONAL	[RFC8414] OPTIONAL
introspection_endpoint	URL of the authorization server's introspection endpoint	OPTIONAL	[RFC8414] OPTIONAL
introspection_endpoint_auth_methods_supported	signing algorithms supported by this endpoint for the signature on the JWT, when used with private_key_jwt	OPTIONAL	[RFC8414] OPTIONAL
mtls_endpoint_aliases		OPTIONAL	[Ena.OAuth] SHOULD if Mutual TLS is supported for client authentication.
tls_client_certificate_bound_access_tokens	indicates authorization server support for mutual TLS client certificate-bound access tokens	OPTIONAL	Section 3.3 of [RFC8705]	[RFC8705] Mutual-TLS client certificate-Bound Access Tokens does not combine well with private_key_jwt.
require_signed_request_object	indicates where authorization request needs to be protected as Request Object and provided through either request or request_uri parameter	OPTIONAL	Section 10.5 of [RFC9101] [Ena.OAuth] Section 7.2, JAR – JWT-Secured Authorization Requests.

OpenID Relying Party (RP) metadata requirements

Metadata	Description	Requirement	Defined in	Comment
redirect_uris	Array of redirection URI values used by the Relying Party.	REQUIRED	[RFC7591] REQUIRED [OIDC.Sweden] REQUIRED
response_types	The response types that the Relying Party uses. Must be set to code.	REQUIRED	[RFC7591] OPTIONAL [OIDC.Sweden] REQUIRED
grant_types	The OAuth2 grant types the Relying Party uses.	REQUIRED MUST be set to authorization_code.	[RFC7591] OPTIONAL [OIDC.Sweden] REQUIRED
token_endpoint_auth_method	Authentication method for accessing the Token endpoint.	REQUIRED MUST be set to private_key_jwt	[RFC7591] OPTIONAL default is client_secret_basic [OIDC.Sweden] REQUIRED
jwks	The Entity's JSON Web Key Set, representing the Entity's protocol keys, included by value in the metadata.	REQUIRED IF jwks_uri is not provided	[OpenID.Fed] [RFC7591] OPTIONAL	[RFC7591] The jwks_uri and jwks parameters MUST NOT be used together.
jwks_uri	URL referencing a JWK Set document containing the Entity's protocol keys for that Entity Type	REQUIRED IF jwks is not provided	[OpenID.Fed] [RFC7591] OPTIONAL	[RFC7591] The jwks_uri and jwks parameters MUST NOT be used together.
signed_jwks_uri	URL referencing a signed JWT having the Entity's JWK Set document, representing the Entity's protocol keys for that Entity Type as its payload	OPTIONAL	[OpenID.Fed]
default_acr_values	Default requested Authentication Context Class Reference values.	OPTIONAL	[RFC7591] OPTIONAL [OIDC.Sweden] OPTIONAL
subject_type	Subject type requested for responses to this Client.	OPTIONAL	[RFC7591] OPTIONAL [OIDC.Sweden] OPTIONAL

OpenID Provider metadata requirements

Metadata	Description	Requirement	Defined in
TBD



https://id.oidc.se/disco/authnProviderSupported	indicates whether the request extension parameter https://id.oidc.se/param/authnProvider is supported	OPTIONAL	[OIDC.Sweden.Parameters] [Ena.OAuth] RECOMMENDED for servers that support multiple authentication methods Authorization servers that do support the parameter MUST indicate this in their metadata. See Section 5.1.1.1, Extension Parameter for Controlling User Authentication at the Authorization Server.

Appendix

Organization identifier formats

The organization identifier formats are defined by the following:

Structure according to GLobal Unique Enterprise Identifier (GLUE)
- https://datatracker.ietf.org/doc/draft-ietf-spice-glue-id/10/
- Denna ger möjlighet att stödja flera olika typer av identifierare samtidigt.
ISO/IEC 6523
- internationell standard som definierar hur organisationer och delar av organisationer identifieras på ett entydigt sätt i elektronisk dataöverföring
Rekommenderade format baserade på ovan standarder (vilka kan byggas ut efter behov):
- Svenskt organisationsnummer (ICD 0007)
  - urn:glue:iso6523:0007:xxxxxxxxxx
- GLN-kod (ICD 0088)
  - urn:glue:iso6523:0088:<gln-kod>
- Domänbaserad eDelivery Participant Identifier (ICD 0203)
  - urn:glue:iso6523:0203:foretaget.se

References

[OpenID.Fed], https://openid.net/openid-federation-1-1-final-specifications-approved/

[Ena.OAuth] https://ena-infrastructure.github.io/specifications/ena-oauth2-profile.html#client-metadata-and-registration

[RFC8414] OAuth 2.0 Authorization Server Metadata

[OpenID.Fed.Swe.Profile] https://www.oidc.se/specifications/swedish-openid-federation-profile.html

[OpenID.Fed.Org.Id] https://www.oidc.se/openid-federation-organization-identifier/main.html

[OpenID.Fed.Reg.Policy] https://www.oidc.se/openid-federation-registration-policy/main.html

[RFC7591] https://openid.net/specs/openid-connect-registration-1_0.html

[OIDC.Sweden] https://www.oidc.se/specifications/

Notes

[OpenID.Fed.Swe.Profile] contains recommendations regarding “Adapting OAuth 2.0 and OpenID Connect for OpenID Federation“, chapter 7, which may affect metadata requirements:
- “For federation deployments based on this profile, it is RECOMMENDED that support for the parameters defined in [OpenID.RP.Choices] be mandatory for federation participants.“
- “It is RECOMMENDED that the Federation Operator define 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.“
- “Requirements for 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, require OpenID Providers to support both the public and pairwise subject types.”

Page tree