Learn »

OpenID Federation policies explained

This guide explains how federation operators can design metadata policies for protocol and API interoperability between entities, such as applications, services and devices. Metadata policies are also indispensable for enforcing security profiles in a federation.

OpenID Federation 1.0 defines 7 operators for validating and shaping entity metadata in a trust chain.

Policy operator Purpose JSON type
Modifier Check Policy operator Metadata parameter
value v x any any
add v x any JSON array
default v x any any
essential x v true, false any
one_of x v JSON array (1) any
subset_of v v JSON array JSON array
superset_of v v JSON array JSON array

Legend:

  • "any" means any JSON value type per RFC 8259, section 3.
  • (1) the JSON array must not be empty

Policy operator: value

The value operator sets or overrides a metadata parameter.

Scenario 1

Example policy to ensure RPs will be registered to receive ID tokens with the auth_time claim, by setting the require_auth_time metadata parameter to true.

{
  "require_auth_time" : {
     "value" : true
  }
}
Input metadata Output metadata
A 
{}



{
  "require_auth_time" : true
}
B 
{
  "require_auth_time" : false
}
 
{
  "require_auth_time" : true
}

Scenario 2

Example policy to ensure RPs cannot register a 3rd party login initiation URL, by removing any initiate_login_uri metadata parameter.

{
  "initiate_login_uri" : {
    "value" : null
  }
}
Input metadata Output metadata
A 
{}


{}
B 
{
  "initiate_login_uri" : "https://example.com/login"
}
 
{}

Policy operator: add

The add operator appends one or more values to a metadata parameter of type JSON array.

Scenario 1

Example policy by an intermediate federation entity that adds the email address of its administrator to the contacts metadata parameter of subordinate RPs.

{
  "contacts" : {
    "add" : "[email protected]"
  }
}
Input metadata Output metadata
A 
{}


{
  "contacts" : [ "[email protected]" ]
}
B 
{
  "contacts" : [ "[email protected]" ]
}


{
  "contacts" : [ "[email protected]",
                 "[email protected]" ]
}

Scenario 2

Example policy that adds two email addresses to the contacts metadata parameter of subordinate RPs.

{
  "contacts" : {
    "add" : [ "[email protected]", "[email protected]" ]
  }
}
Input metadata Output metadata
A 
{}




{
  "contacts" : [ "[email protected]",
                 "[email protected]" ]
}
B 
{
  "contacts" : [ "[email protected]" ]
}



{
  "contacts" : [ "[email protected]",
                 "[email protected]",
                 "[email protected]" ]
}

Policy operator: default

The default operator specifies a parameter when it's absent in the metadata.

Scenario 1

Example policy that sets the ID token JWS algorithm to RS256 for RPs that don't specify an algorithm in their metadata.

{
  "id_token_signed_response_alg" : {
    "default" : "RS256"
  }
}
Input metadata Output metadata
A 
{}




{
  "id_token_signed_response_alg" :
    "RS256"
}
B 
{
  "id_token_signed_response_alg" :
    "ES256"
}
 
{
  "id_token_signed_response_alg" :
    "ES256"
}

Policy operator: essential

When true the essential operator requires a metadata parameter to be present. When false the metadata parameter is voluntary and may be absent. The essential operator has a default value false (voluntary). Entity metadata that is missing an essential parameter is considered invalid.

Scenario 1

Example policy that requires RPs to provide a client_name metadata parameter.

{
  "client_name" : {
    "essential" : true
  }
}
Input metadata Output metadata
A 
{
  "client_name" : "My Payments App"
}
 
{
  "client_name" : "My Payments App"
}
B 
{}


INVALID METADATA

Scenario 2

Example RP policy that marks the client_name metadata parameter as voluntary. This is the same as omitting essential.

{
  "client_name" : {
    "essential" : false
  }
}
Input metadata Output metadata
A 
{
  "client_name" : "My Payments App"
}
 
{
  "client_name" : "My Payments App"
}
B 
{}


{}

Policy operator: one_of

The one_of operator ensures a metadata parameter that is present and not null is set to a whitelisted value.

Scenario 1

Example policy to ensure that when RPs choose to register for signed UserInfo responses the JWS algorithm must be either PS256 or ES256.

{
  "userinfo_signed_response_alg" : {
    "one_of" : [ "PS256", "ES256" ]
  }
}
Input metadata Output metadata
A 
{}


{}
B 
{
  "userinfo_signed_response_alg" :
    "PS256"
}
 
{
  "userinfo_signed_response_alg" :
    "PS256"
}
C 
{
  "userinfo_signed_response_alg" :
    "RS256"
}
 
INVALID METADATA

Scenario 2

Example policy that requires RPs to register either for the PS256 or the ES256 ID token JWS algorithm. The metadata parameter is marked essential and hence RPs must always specify it.

{
  "id_token_signed_response_alg" : {
    "essential" : true,
    "one_of" : [ "PS256", "ES256" ]
  }
}
Input metadata Output metadata
A 
{}


INVALID METADATA
B 
{
  "id_token_signed_response_alg" :
    "PS256"
}
 
{
  "id_token_signed_response_alg" :
    "PS256"
}
C 
{
  "id_token_signed_response_alg" :
    "RS256"
}
 
INVALID METADATA

Policy operator: subset_of

The subset_of operator computes the intersection between a specified JSON array of values and a metadata parameter (also a JSON array) that is present:

  • If the resulting intersection is non-empty the metadata parameter becomes the intersection.
  • If the resulting intersection is empty the outcome depends on whether the metadata parameter is essential:
    • If the parameter is essential, the metadata is considered invalid.
    • If the parameter is voluntary it is removed from the metadata.

Scenario 1

Example policy to ensure that when RPs choose to specify a set of response types they must include the code and / or code id_token values.

{
  "response_types" : {
    "subset_of" : [ "code", "code id_token" ]
  }
}
Input metadata Output metadata
A 
{
  "response_types" :
    [ "code" ]
}

{
  "response_types" :
    [ "code" ]
}
B 
{
  "response_types" :
    [ "code", "code id_token" ]
}
 
{
  "response_types" :
    [ "code", "code id_token" ]
}
C 
{
  "response_types" :
    [ "code", "token" ]
}
 
{
  "response_types" :
    [ "code" ]
}
D 
{
  "response_types" :
    [ "token" ]
}
 
{}
E 
{}


{}

Scenario 2

Example policy requiring RPs to register for a set of response types that includes the code and / or code id_token values. The metadata parameter is marked essential and RPs must always specify it.

{
  "response_types" : {
    "essential" : true,
    "subset_of" : [ "code", "code id_token" ]
  }
}
Input metadata Output metadata
A 
{
  "response_types" :
    [ "code", "token" ]
}
 
{
  "response_types" :
    [ "code" ]
}
B 
{
  "response_types" :
    [ "token" ]
}
 
INVALID METADATA
C 
{}


INVALID METADATA

Policy operator: superset_of

The superset_of operator ensures a metadata parameter (JSON array) that is present includes a specified set of values.

Scenario 1

Example policy requiring RPs that choose to specify a set of grant types to include at least the authorization_code type.

{
  "grant_types" : {
    "superset_of" : [ "authorization_code" ]
  }
}
Input metadata Output metadata
A 
{
  "grant_types" :
    [ "authorization_code" ]
}
 
{
  "grant_types" :
    [ "authorization_code" ]
}
B 
{
  "grant_types" :
    [ "authorization_code",
      "refresh_token" ]
}
 
{
  "grant_types" :
    [ "authorization_code",
      "refresh_token" ]
}
C 
{}


{}

Scenario 2

Example policy requiring RPs to register for a set of grant types that include at least the authorization_code type. The metadata parameter is marked essential and RPs must always specify it.

{
  "grant_types" : {
    "essential" : true,
    "superset_of" : [ "authorization_code" ]
  }
}
Input metadata Output metadata
A 
{
  "grant_types" :
    [ "authorization_code" ]
}
 
{
  "grant_types" :
    [ "authorization_code" ]
}
B 
{
  "grant_types" :
    [ "authorization_code",
      "refresh_token" ]
}
 
{
  "grant_types" :
    [ "authorization_code",
      "refresh_token" ]
}
C 
{}



INVALID METADATA
comments powered by Disqus