Sweden Connect – OpenID Federation Rules and Policies 1.0 – draft 01

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

2.1. The Federation Operator

The Swedish Agency for Digital Government (Digg) is the Federation Operator of the Sweden Connect OpenID Connect federation. Digg administers the Trust Anchor, the Trust Mark Issuers, and the Registration Intermediates of the federation.¶

The base URL of the federation is https://id.swedenconnect.se. Identifiers that the Federation Operator defines, such as Registration Policy URIs and Trust Mark type identifiers, are formed under this URL. This is the base URL that Section 2.1 of [OIDC.Sweden.Federation] requires the Federation Rules to define.¶

The Entity Identifiers, endpoints, and Federation Entity Keys of the Trust Anchor for each of the federation environments are published in Section 5 of [OIDC.SC.Structure].¶

2.2. Federation Endpoints

The federation endpoints of the Trust Anchor, the Trust Mark Issuers, and the Registration Intermediates do not require client authentication, see Section 8.8 of [OpenID.Federation]. The endpoints of each environment are listed in Section 5 of [OIDC.SC.Structure].¶

3.1. Validity

It is RECOMMENDED that an Entity set the validity of its Entity Configuration, as given by the exp Claim, to 7 days. An Entity that knows that a change to its metadata is about to happen MAY set a shorter validity.¶

New Entity Configurations SHOULD be published according to the recommendation in Section 2.4.1 of [OIDC.Sweden.Federation], that is, when half the lifetime of the current one has elapsed.¶

The Entity Configuration of the Trust Anchor, and the Subordinate Statements issued by the Trust Anchor and the Registration Intermediates, have a validity of 7 days.¶

3.2. Hosted Entity Configurations

An Entity normally publishes its own Entity Configuration at its well-known location, see Section 9 of [OpenID.Federation]. A hosted Entity Configuration is instead created, signed, and published on behalf of the Entity by another party, which within Sweden Connect is the RP Registration Intermediate. Sweden Connect offers hosting because OpenID Federation is a relatively new technology, and support for it in software is not yet widespread. Hosting allows Relying Parties whose software lacks such support to join the federation. When support becomes more widespread, Sweden Connect may stop offering hosted Entity Configurations.¶

An Entity that publishes its Entity Configuration at its well-known location thereby shows that it controls the domain of its Entity Identifier. A hosted Entity Configuration gives no such proof, see Section 4.1 of [OIDC.Sweden.Hosting], so domain ownership for a hosted Relying Party is checked manually, see Section 6.2, Sweden Connect Domain Ownership.¶

The federation uses the ec_location Claim defined in [OIDC.Sweden.Hosting]. Following the recommendation in Section 2.4.2 of [OIDC.Sweden.Federation], the RP Registration Intermediate includes the ec_location Claim in the Subordinate Statement of every Relying Party, whether the Relying Party's Entity Configuration is hosted or not. The OP Registration Intermediate does not include the Claim, since an OpenID Provider publishes its own Entity Configuration and cannot have it hosted.¶

A Relying Party may have its Entity Configuration hosted by the RP Registration Intermediate. The ec_location value of a hosted Entity Configuration is an https URL of the following form:¶

<ie-entity-id>/hosted/<enc-rp-entity-id>/.well-known/openid-federation

where ie-entity-id is the Entity Identifier of the RP Registration Intermediate, and enc-rp-entity-id is the URL-encoded Entity Identifier of the Relying Party whose Entity Configuration is hosted.¶

The example below is non-normative. It shows the ec_location value for the Relying Party https://rp.example.se, hosted by the RP Registration Intermediate.¶

https://fed.swedenconnect.se/im-reg-sc/hosted/https%3A%2F%2Frp.example.se/.well-known/openid-federation

Example of the ec_location value of a hosted Entity Configuration.¶

A hosted Entity Configuration is signed with a dedicated Federation Entity Key held by the RP Registration Intermediate, not by the Relying Party. The RP Registration Intermediate re-signs and republishes hosted Entity Configurations itself. The RP Registration Intermediate also includes the federation-wide Trust Marks held by the Relying Party in its hosted Entity Configuration.¶

Since a hosted Relying Party does not hold its own Federation Entity Key, the following applies:¶

• A hosted Relying Party MUST NOT use the signed_jwks_uri metadata parameter, since its JWT has to be signed with a Federation Entity Key, see Section 5.2.1 of [OpenID.Federation].¶
• A hosted Relying Party MUST NOT use Explicit Registration, in which the Relying Party sends its own signed Entity Configuration, see Section 12.2 of [OpenID.Federation]. A hosted Relying Party is therefore limited to Automatic Registration.¶

4.1. Resolving Trust Chains

The Sweden Connect Trust Anchor provides a resolve endpoint, see Section 8.3 of [OpenID.Federation]. The endpoint of each environment is listed in Section 5 of [OIDC.SC.Structure]. Since the resolver is the Trust Anchor itself, an Entity that uses it does not need to configure trust in any other Entity than the Trust Anchor.¶

It is RECOMMENDED that Entities use the Trust Anchor's resolver to obtain the Resolved Metadata and Trust Marks of peer Entities, in line with Section 2.3 of [OIDC.Sweden.Federation]. An Entity that does so does not build or validate Trust Chains itself.¶

Some Relying Parties have their Entity Configurations hosted by the RP Registration Intermediate, see Section 3.2, Hosted Entity Configurations. Such an Entity Configuration is not published at the Relying Party's well-known location, so bottom-up chain building as described in Section 10.1 of [OpenID.Federation] fails for these Relying Parties, see Section 3 of [OIDC.Sweden.Hosting]. An implementation cannot know in advance whether a Relying Party is hosted.¶

An Entity that builds Trust Chains itself, rather than using the resolver, applies the constraints described in Section 4.2, Constraints. It MUST support top-down chain building, see Section 17.2.2 of [OpenID.Federation], and the ec_location Claim [OIDC.Sweden.Hosting], and it SHOULD support the registration_policy constraint Section 3 of [OIDC.Sweden.RegPolicy]. The same applies to anyone implementing their own resolver for the federation.¶

4.2. Constraints

Constraints are applied when Trust Chains are resolved and validated.¶

The Sweden Connect Trust Anchor sets two constraints in the Subordinate Statements it issues for the Registration Intermediates, allowed_entity_types Section 6.2.3 of [OpenID.Federation] and registration_policy Section 3 of [OIDC.Sweden.RegPolicy]. No other constraints are set.¶

The allowed_entity_types constraint holds openid_relying_party for the RP Registration Intermediate and openid_provider for the OP Registration Intermediate. A Trust Mark Issuer may also be registered under each of the Registration Intermediates. It is not listed in the constraint, since the Entity Type federation_entity is always allowed and Section 6.2.3 of [OpenID.Federation] does not permit it to be included.¶

The registration_policy constraint requires that both Registration Policies of Section 6, Registration Policies, have been applied, that is, Sweden Connect Organizational Affinity and Sweden Connect Domain Ownership. This applies to Relying Parties under the RP Registration Intermediate and to OpenID Providers under the OP Registration Intermediate. A constraint rule is satisfied if at least one of the policies it lists appears in the registration_policy Claim of the Subordinate Statement, so the constraint holds one rule for each policy.¶

The allowed_entity_types constraint keeps each Registration Intermediate to the kind of protocol Entity it is responsible for. Entity Types not listed in the constraint are removed from the subject's metadata during Trust Chain resolution, see Section 6.2.3 of [OpenID.Federation]. The registration_policy constraint makes Trust Chain validation itself guarantee that every Relying Party and OpenID Provider has been registered under both Registration Policies. A peer can therefore rely on what the policies check without checking it itself.¶

The examples below are non-normative.¶

{
  "iss": "https://fed.swedenconnect.se/trustanchor",
  "sub": "https://fed.swedenconnect.se/im-reg-sc",
  ...
  "constraints": {
    "allowed_entity_types": [ "openid_relying_party" ],
    "registration_policy": [
      {
        "entity_types": [ "openid_relying_party" ],
        "policy": [ "https://id.swedenconnect.se/regpolicy/org-affinity" ]
      },
      {
        "entity_types": [ "openid_relying_party" ],
        "policy": [ "https://id.swedenconnect.se/regpolicy/domain-ownership" ]
      }
    ]
  }
}

Example of the constraints Claim of the Subordinate Statement issued by the Sweden Connect Trust Anchor for the RP Registration Intermediate.¶

{
  "iss": "https://fed.swedenconnect.se/trustanchor",
  "sub": "https://fed.swedenconnect.se/im-reg-sc-op",
  ...
  "constraints": {
    "allowed_entity_types": [ "openid_provider" ],
    "registration_policy": [
      {
        "entity_types": [ "openid_provider" ],
        "policy": [ "https://id.swedenconnect.se/regpolicy/org-affinity" ]
      },
      {
        "entity_types": [ "openid_provider" ],
        "policy": [ "https://id.swedenconnect.se/regpolicy/domain-ownership" ]
      }
    ]
  }
}

Example of the constraints Claim of the Subordinate Statement issued by the Sweden Connect Trust Anchor for the OP Registration Intermediate.¶

5.1. Trust Mark Policy

The Trust Anchor lists the federation-wide Trust Mark types, and the Trust Mark Issuers accredited to issue them, in the trust_mark_issuers Claim of its Entity Configuration, see Section 7 of [OpenID.Federation]. The Trust Mark Issuers operated by the Federation Operator are the only accredited Trust Mark Issuers, and only the Federation Operator defines federation-wide Trust Mark types. Their type identifiers are formed under the base URL of the federation, see Section 2.1, The Federation Operator.¶

Other organizations may apply to operate Trust Mark Issuers within the federation. Such Trust Mark Issuers are not listed in the trust_mark_issuers Claim of the Trust Anchor, and the Trust Mark types they issue are not recognized federation-wide. Their Trust Mark type identifiers MUST NOT be formed under the base URL of the federation.¶

A Trust Mark Issuer that issues Trust Marks without an exp Claim, or with a validity longer than 7 days, MUST expose a Trust Mark Status endpoint, see Section 8.4 of [OpenID.Federation].¶

An Entity holding a federation-wide Trust Mark, see Section 5.2 below, MUST include it in its Entity Configuration.¶

Trust Mark delegation, see Section 7.2 of [OpenID.Federation], is not used within the federation.¶

5.2. Sweden Connect Trust Marks

This section defines the federation-wide Sweden Connect Trust Marks.¶

6.1. Sweden Connect Organizational Affinity

Identifier: https://id.swedenconnect.se/regpolicy/org-affinity¶

When this policy has been applied, the Registration Intermediate asserts that:¶

• the value of organization_name without a language tag is the legal name of the organization that owns the Entity, see Section 3 of [OIDC.SC.Metadata],¶
• organization_identifier holds the registration number of that organization, see Section 3 of [OIDC.SC.Metadata],¶
• the administrator who registered the Entity has been verified by the Federation Operator to be authorized to represent the organization, and¶
• the presentation names of the Entity have been checked, that is, display_name, see Section 3 of [OIDC.SC.Metadata], and for a Relying Party also client_name, see Section 4 of [OIDC.SC.Metadata].¶

These values are set or pinned in the Subordinate Statement issued for the Entity, see Section 6.2 of [OIDC.SC.Metadata], and cannot be changed without the involvement of the Federation Operator.¶

With a registration_policy constraint, the federation can require that every Entity has been registered under this policy. A peer can then trust the organization information and the presentation names of an Entity without checking them itself.¶

6.2. Sweden Connect Domain Ownership

Identifier: https://id.swedenconnect.se/regpolicy/domain-ownership¶

When this policy has been applied, the Registration Intermediate asserts that the organization behind the Entity owns, or has the right to use, the domain of the Entity Identifier, and that the Entity Identifier is not used by another Entity in the federation.¶

An Entity that publishes its own Entity Configuration at its well-known location, see Section 9 of [OpenID.Federation], thereby proves control of the domain of its Entity Identifier, and the policy is applied to it on that basis.¶

A hosted Entity Configuration gives no such proof. For a hosted Relying Party, the Registration Intermediate therefore checks manually that the Entity Identifier, and the other URLs in the metadata of the Relying Party, are within domains that the organization owns or has the right to use, and that the Entity Identifier is not already used by another Entity in the federation.¶

The purpose of the policy is to make it possible to assert that no hosted Entity Configuration has been registered in the federation without an explicit check of domain ownership.¶

7.1. Steps for Joining the Federation

The steps below differ between Relying Parties with their own Entity Configuration, hosted Relying Parties, and OpenID Providers.¶

7.2. Updating a Registration

Metadata values that are checked during registration are pinned in the Subordinate Statement that the Registration Intermediate issues for the Entity. These values are listed in Section 6.2 of [OIDC.SC.Metadata]. Since a pinned value overrides the value in the Entity Configuration, a change to such a value MUST be requested through the portal, where it is checked in the same way as during registration before the Subordinate Statement is updated.¶

A change of the Federation Entity Keys of the Entity MUST also be requested through the portal. An Entity Configuration is signed with a key from the jwks Claim of the Subordinate Statement issued for the Entity, see Section 4 of [OpenID.Federation], so a new key can only be used after the Registration Intermediate has issued a Subordinate Statement that contains it.¶

Other changes, such as changes to its protocol keys, are made by the Entity itself, by publishing an updated Entity Configuration.¶

A hosted Relying Party does not publish its own Entity Configuration, so all changes to its metadata MUST be requested through the portal.¶

7.3. Joining the Federation with Limited OpenID Federation Support

It is RECOMMENDED that all Entities joining the federation support OpenID Federation. A Relying Party whose software lacks such support may still join the federation by having its Entity Configuration hosted by the RP Registration Intermediate, see Section 3.2, Hosted Entity Configurations. Hosting is requested through the Sweden Connect Metadata Registration Portal by an RP administrator. The portal URL for each environment is listed in [OIDC.SC.Structure].¶

A Relying Party that cannot resolve the metadata of OpenID Providers may download it from the Sweden Connect Metadata Registration Portal, as a resolve response, as plain JSON, or in the format of [OpenID.Discovery], and configure it statically. This is an informal way of using the services of the federation, and does not comply with [OpenID.Federation]. The metadata of an OpenID Provider may change, and it is the responsibility of the Relying Party to make sure that it uses the latest version. A Relying Party that uses statically configured metadata does not benefit from what the federation provides, and does so at its own responsibility.¶