Entity Statement
Full Title or Meme
An Attestation statement about the Trusted Identifier of the Entity typically from a Federation Operator.
Preconditions
- The primary use case for the Entity Statement is a user navigating to the web site where they need be able to trust the site with their User Private Information.
Problems
- Best method for establishing trust with a web site today in the EV Cert which is designed to bind the web site to a real world entity.
Solutions
- Users can Authenticate in a manner that gives a Relying Party a consistent Identifier that can be sued from session to session without the need for sharing any User Private Information.
- To be fully compliant with the various Privacy legislation like the GDPR or the California legislation the Relying Party may first require that the user establish a channel back to the user for the performance of required Redress and Recovery operations.
- Only then should the Relying Party be in a position to request additional Attributes from the User.
Entity Statement from OpenID
An entity statement is composed of the following claims:
iss
REQUIRED. The entity identifier of the issuer of the statement. If the iss and the sub are identical, the issuer is making a statement about itself.
sub
REQUIRED. The entity identifier of the subject
iat
REQUIRED. The time the statement was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See RFC 3339 for details regarding date/times in general and UTC in particular.
exp
REQUIRED. Expiration time on or after which the statement MUST NOT be accepted for processing. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
jwks
REQUIRED. A JSON Web Key Set (JWKS) representing the public part of the subject entity's signing keys. The corresponding private key is used by leaf entities to sign entity statements about themselves, and intermediate entities to sign statements about other entities. The keys that can be found here are primarily intended to sign entity statements and should not be used in other protocols.
aud
OPTIONAL. The entity statement may be specifically created for a entity. The entity identifier for that entity should appear in this claim.
authority_hints
OPTIONAL. A JSON object where the keys are the entity IDs of the intermediate entities that may issue an entity statement about the issuer entity. The value MUST be a JSON array of entities that are further up in the trust chain. The array may be an empty list. The JSON array can be used to simplify the selection of trust chains without the need for following all possible trust chains. authority_hints values may be multiple hops up the chain. These values will typically be trust anchors.
metadata
OPTIONAL. JSON object including protocol specific metadata claims that represent the entity's metadata. Each key of the JSON object represents a metadata type identifier, and each value MUST be a JSON object representing the metadata according to the metadata schema of that metadata type. An entity statement may contain multiple metadata statements, but only one for each metadata type.
metadata_policy
OPTIONAL. JSON object that describes a metadata policy. Each key of the JSON object represents a metadata type identifier, and each value MUST be a JSON object representing the metadata policy according to the metadata schema of that metadata type. An entity statement may contain multiple metadata policy statements, but only one for each metadata type. If the metadata type identifier is federation_entity, then the policy MUST be applied to the immediate subordinate in the trust chain unless that is a leaf entity. If the metadata type identifier is not federation_entity, then the policy MUST be applied to all subordinate nodes of that type in the trust chain. Only non-leaf entities contain a metadata_policy field.
crit
OPTIONAL. The crit (critical) entity statement claim indicates that extensions to entity statement claims defined by this specification are being used that MUST be understood and processed. It is used in the same way that crit is used for extension JWS header parameters that MUST be understood and processed. Its value is an array listing the entity statement claims present in the entity statement that use those extensions. If any of the listed extension entity statement claims are not understood and supported by the recipient, then the entity statement is invalid. Producers MUST NOT include entity statement claim names defined by this specification or names that do not occur as entity statement claim names in the entity statement in the crit list. Producers MUST NOT use the empty list [] as the crit value.
policy_language_crit
OPTIONAL. The policy_language_crit (critical) entity statement claim indicates that extensions to the policy language defined by this specification are being used that MUST be understood and processed. It is used in the same way that crit is used for extension JWS header parameters that MUST be understood and processed. Its value is an array listing the policy language extensions present in the policy language statements that use those extensions. If any of the listed extension policy language extensions are not understood and supported by the recipient, then the entity statement is invalid. Producers MUST NOT include policy language names defined by this specification or names that do not occur in policy language statements in the entity statement in the policy_language_crit list. Producers MUST NOT use the empty list [] as the policy_language_crit value.
The entity statement is signed using the private key of the issuer entity, in the form of a JSON Web Signature (JWS).
The following is a non-normative example of an entity statement, before serialization and adding a signature. The example contains a critical extension jti (JWT ID) to the entity statement and one critical extension to the policy language regexp (Regular expression).
{
"iss": "https://feide.no",
"sub": "https://ntnu.no",
"iat": 1516239022,
"exp": 1516298022,
"crit": ["jti"],
"jti": "7l2lncFdY6SlhNia",
"policy_language_crit": [regexp"],
"metadata_policy": {
"openid_provider": {
"issuer": {"value": "https://ntnu.no"},
"organization_name": {"value": "NTNU"},
"id_token_signing_alg_values_supported":
{"subset_of": ["RS256", "RS384", "RS512"]},
"op_policy_uri": {
"regexp": "^https:\/\/[\w-]+\.example\.com\/[\w-]+\.html"}
},
"openid_relying_party": {
"organization_name": {"value": "NTNU"},
"grant_types_supported": {
"subset_of": ["authorization_code", "implicit"]},
"scopes": {
"subset_of": ["openid", "profile", "email", "phone"]}
}
},
"jwks": {
"keys": [
{
"alg": "RS256",
"e": "AQAB",
"ext": true,
"key_ops": ["verify"],
"kid": "key1",
"kty": "RSA",
"n": "pnXBOusEANuug6ewezb9J_...",
"use": "sig"
}
]
},
"authority_hints": {
"https://edugain.org/federation": [
"https://edugain.org/federation"
]
}
}