Skip to content

Instantly share code, notes, and snippets.

@zamzterz

zamzterz/oidc-fed.md

Last active November 8, 2018 04:11
Show Gist options
  • Star 5 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save zamzterz/f0de040f2cf26b8f2705 to your computer and use it in GitHub Desktop.
Save zamzterz/f0de040f2cf26b8f2705 to your computer and use it in GitHub Desktop.
Download ZIP
Description of model for federations built using OpenID Connect.
Raw
oidc-fed.md

OpenID Connect federation model

All JWS's passed between entities MUST contain the "kid" header parameter to allow explicitly signaling a key change to the recipient. Furthermore, all key id's used by an entity MUST be scoped (to avoid name conflicts) by a unique URI managed by the organization owning the entity. In the same way, all JWK's passed between entities must have a scoped key id.

JWS's in the model:

  • Software statements issued by a federation.
  • Public intermediate signing key published both by relying party and provider.
  • JWKS published both by relying party and provider.
  • Signed metadata published by the provider.
  • Registration request signature value computed by the relying party.

JWK's in the model:

  • The federations public key.
  • The OP and RP's JWK's:
    • root key
    • intermediate signing key
    • all its keys published in the JWKS.

Joining a federation

Assume the Federation Operator (FO) has a public/private signing key pair, call it F. The public part of this key, pub(F), must be given to all entities that are part of the federation as a JWK.

Relying Party

  1. Relying Party Operator (RPO) creates a long-lived signing key pair; call it A.
  2. RPO submits registration data to Federation Operator (FO). The registration data MUST include redirect_uris and root_key = pub(A).
  3. FO returns a signed (with key F) software statement containing the submitted registration data, and any applied policy restrictions (response_types, signing/encryption algorithms for ID Tokens and/or UserInfo Responses, similar to SAML entity categories in the form of e.g. claims_allowed and/or scopes_allowed).

OpenID Connect Provider

  1. OpenID Connect Provider Operator (OPO), creates a long-lived signing key pair; call it B
  2. OPO submits registration data to Federation Operator (FO). The registration data MUST include issuer and root_key = pub(B).
  3. FO returns a signed (with key F) software statement, SSOP, containing the submitted registration data, and any applied policy restrictions (response_types, signing/encryption algorithms for ID Tokens and/or UserInfo Responses, similar to SAML entity categories in the form of e.g. claims_supported and/or scopes_supported).
  4. The OP MUST use the same root_key = pub(B) for all software statements it intends to publish in the same discovery document.

Key initialization

To allow for key rotation in multiple steps, an intermediate key is used for signing. The keys in the JWKS could be rotated on a timescale of once every 24 hours, while the intermediate key could be rotated on timescale of once every month (the long-lived key can't be rotated at all).

Relying Party

  1. Create a JSON Web Key Set (JWKS) and publish it at a URL specified by jwks_uri in the client metadata sent in the Registration Request.
  2. Create a new intermediate signing key pair, call it An and sign the JWK representation of pub(An) with A.
  3. Sign the JWKS with An.

A -- sign --> JWK(pub(An)) -- sign --> JWKS

OpenID Connect Provider

  1. Create a JSON Web Key Set (JWKS) and publish it at a URL specified by jwks_uri in the provider metadata.
  2. Create a new intermediate signing key pair, call it Bn and sign that key with B.
  3. Sign the JWKS with Bn.
  4. Include the software statement SSOP in the provider configuration and sign the provider configuration document using the key Bn.

B -- sign --> JWK(pub(Bn)) -- sign --> JWKS and provider metadata

OpenID Connect communication

There are three steps of communication between an RP and OP, see below figure.

------                             ------
|    | <--- 1) Discovery --------> |    |
| RP | <--- 2) Registration -----> | OP |
|    | <--- 3) Authentication ---> |    |
------                             ------

After the discovery and registration is completed a first time, they SHOULD only be repeated if any changes occur (see notes in respective sections below).

Discovery

The OP MUST publish its provider metadata as specified by Obtaining OpenID Provider Configuration Information. The RP makes a standard OpenID Provider Configuration Request. The OP responds with its provider configuration and the following additional metadata parameters:

  • software_statements: a list of software statements from all federations the OP is part of.
  • signed_metadata: a JWS containing all published metadata, except signed_metadata.
  • signed_jwks_uri: a URI to the location where the OP publishes the signed JWKS, SHOULD return the Content-Type 'application/jose' to indicate that the JWKS is in the form of a JWS using the JWS Compact Serialization.
  • signing_key: a JWK containing the OP's intermediate public key pub(Bn).

Upon receiving the response the RP MUST do the following steps:

  1. Find any software statement, SSOPH, in the software_statements signed by federation H which the RP is also part of and verify its signature with the federations public key, pub(FH). If the OP and RP both are part of more than one common federation the RP may decide, using any heuristic of its choice, which software statement to use. Since the OP MUST have the same root_key in all its software statements, it does not matter from which software statement root_key is extracted.
  2. Verify that issuer in the software statement matches issuer in the discovery response.
  3. Verify the signature of signing_key with the root_key from SSOPH.
  4. Verify the signature of signed_metadata with signing_key, and use this metadata instead of the clear-text values provided in the OpenID Provider Configuration Response.

Note: the OpenID Provider Configuration Request must be repeated when the OP rotates its intermediate signing key pair Bn -> Bn+1.

Registration

The OP MUST support dynamic client registration. The RP makes a signed standard Client Registration Request and includes the following additional metadata parameters:

  • software_statements: a list of software statements from all federations the RP is part of.
  • signing_key: a JWK containing the RP's intermediate public key pub(An).
  • signed_jwks_uri: a URI to the location where the RP publishes the signed JWKS, SHOULD return the Content-Type 'application/jose' to indicate that the JWKS is in the form of a JWS using the JWS Compact Serialization.

The body of the request MUST be signed with key An, using A Method for Signing an HTTP Requests for OAuth. The signature value MUST be sent in the request header field "Authorization", using the authorization scheme "pop", i.e.:

Authorization: pop <signature value>"

Upon receiving the request the OP MUST do the following steps:

  1. Find any software statement, SSRPI, in the software_statements signed by federation I which the OP is also part of and verify its signature with the federations public key, pub(FI). If the OP and RP both are part of more than one common federation the RP may decide, using any heuristic of its choice, which software statement to use.
  2. Verify the signature of signing_key with the root_key included in the software statement.
  3. Verify the signature of the registration request with signing_key.
  4. Use any client metadata parameters in SSRPI for the registration (they override any metadata paramters in the signed registration request).
  5. Fetch the RP's signed JWKS from signed_jwks_uri and verify its signature with signing_key. This step must be repeated every time the RP rotates the keys in the JWKS.
  6. Include provider_software_statement = SSOPI in the Registration Response, signaling the OP's choice to use the common federation I as grounds for trust/policy.

Upon receiving the response the RP MUST do the following steps:

  1. Verify the signature of provider_software_statement.
  2. Verify that issuer in the software statement matches issuer known from the previous the discovery response.
  3. Verify the providers signing key again with root_key from provider_software_statement.
  4. Fetch the OP's signed JWKS from signed_jwks_uri and verify its signature with signing_key. This step must be repeated every time the OP rotates the keys in the JWKS.
  5. Use any provider metadata parameters in provider_software_statement, which override the signed metadata parameters specified in the earlier Discovery step.

Note: the Client Registration Request must be repeated when the RP rotates its intermediate signing key pair An -> An+1.

Authentication

The authentication/request does not need to be extended in any way.

Questions

  • Conflicting claims in software statements when RP and OP are part of multiple common federations?
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment