OpenID Connect for Identity Assurance 1.0

Table of Contents

1. Introduction

This specification defines an extension to OpenID Connect [OpenID] for providing Relying Parties with identity information, i.e. verified Claims, along with an explicit statememt about the verification status of those Claims (what, how, when, according to what rules, using what evidence). This specification is aimed at enabling use cases requiring strong identity assurance, for example, to comply with potential regulatory requirements such as Anti-Money Laundering laws or access to health data, risk mitigation, or fraud prevention.¶

In such use cases, the Relying Party (RP) needs to understand the trustworthiness or assurance level of the Claim about the End-User that the OpenID Connect Provider (OP) is willing to communicate, along with process-related information and evidence used to verify the End-User Claims.¶

The acr Claim, as defined in Section 2 of the OpenID Connect specification [OpenID], is suited to assure information about the authentication performed in an OpenID Connect transaction. But identity assurance requires a different representation for the following reason: authentication is an aspect of an OpenID Connect transaction while identity assurance is a property of a certain Claim or a group of Claims and several of them will typically be conveyed to the RP as the result of an OpenID Connect transaction.¶

For example, the assurance an OP typically will be able to give for an e-mail address will be "self-asserted" or "verified by opt-in or similar mechanism". The family name of an End-User, in contrast, might have been verified in accordance with the respective Anti Money Laundering Law by showing an ID Card to a trained employee of the OP operator.¶

Identity assurance therefore requires a way to convey assurance data along with and coupled to the respective Claims about the End-User. This specification defines a suitable representation and mechanisms the RP will utilize to request verified claims about an End-User along with identity assurance data and for the OP to represent these verified Claims and accompanying identity assurance data.¶

Note: this specifications fulfills the criteria for portability and interoperability mechanisms of Digital ID systems as defined in [FATF-Digital-Identity] .¶

2. Scope

This specification defines the technical mechanisms to allow Relying Parties to request verified Claims and to enable OpenID Providers to provide Relying Parties with verified Claims ("the tools").¶

Additional facets needed to deploy a complete solution for identity assurance, such as legal aspects (including liability), concrete trust frameworks, or commercial agreements are out of scope. It is up to the particular deployment to complement the technical solution based on this specification with the respective definitions ("the rules").¶

Note: although such aspects are out of scope, the aim of the specification is to enable implementations of the technical mechanism to be flexible enough to fulfill different legal and commercial requirements in jurisdictions around the world. Consequently, such requirements will be discussed in this specification as examples.¶

3. Requirements

The RP will be able to request the minimal data set it needs (data minimization) and to express requirements regarding this data, the evidence and the identity verification processes employed by the OP.¶

This extension will be usable by OPs operating under a certain regulation related to identity assurance, such as eIDAS, as well as other OPs operating without such a regulation.¶

It is assumed that OPs operating under a suitable regulation can assure identity data without the need to provide further evidence since they are approved to operate according to well-defined rules with clearly defined liability. For example in the case of eIDAS, the peer review ensures eIDAS compliance and the respective member state assumes the liability for the identities asserted by its notified eID systems.¶

Every other OP not operating under such well-defined conditions may be required to provide the RP data about the identity verification process along with identity evidence to allow the RP to conduct their own risk assessment and to map the data obtained from the OP to other laws. For example, if an OP verifies and maintains identity data in accordance with an Anti Money Laundering Law, it shall be possible for an RP to use the respective identity in a different regulatory context, such as eHealth or the beforementioned eIDAS.¶

The basic idea of this specification is that the OP provides all identity data along with metadata about the identity verification process at the OP. It is the responsibility of the RP to assess this data and map it into its own legal context.¶

From a technical perspective, this means this specification allows the OP to provide verified Claims along with information about the respective trust framework, but also supports the externalization of information about the identity verification process.¶

The representation defined in this specification can be used to provide RPs with verified Claims about the End-User via any appropriate channel. In the context of OpenID Connnect, verified Claims can be provided in ID Tokens or as part of the UserInfo response. It is also possible to utilize the format described here in OAuth Access Tokens or Token Introspection responses (see [RFC7662] and [I-D.ietf-oauth-jwt-introspection-response]) to provide resource servers with verified Claims.¶

This extension is intended to be truly international and support identity assurance across different jurisdictions and across jurisdictions. The extension is therefore extensible to support various trust frameworks, verification methods, and identity evidence.¶

In order to give implementors as much flexibility as possible, this extension can be used in conjunction with existing OpenID Connect Claims and other extensions within the same OpenID Connect assertion (e.g., ID Token or UserInfo response) utilized to convey Claims about End-Users.¶

For example, OpenID Connect [OpenID] defines Claims for representing family name and given name of an End-User without a verification status. Those Claims can be used in the same OpenID Connect assertion beside verified Claims represented according to this extension.¶

In the same way, existing Claims to inform the RP of the verification status of the phone_number and email Claims can be used together with this extension.¶

Even for representing verified Claims, this extension utilizes existing OpenID Connect Claims if possible and reasonable. The extension will, however, ensure RPs cannot (accidentally) interpret unverified Claims as verified Claims.¶

4. Claims

5. verified_claims Element

This specification defines a generic mechanism to add verified claims to JSON-based assertions. The basic idea is to use a container element, called verified_claims to provide the RP with a set of Claims along with the respective metadata and verification evidence related to the verification of these claims. This way RPs cannot mix up verified and unverified Claims and accidentally process unverified Claims as verified Claims.¶

The following example¶

{
  "verified_claims": {
    "verification": {
      "trust_framework": "ial_example_gold"
    },
    "claims": {
      "given_name": "Max",
      "family_name": "Meier"
    }
  }
}

would assert to the RP that the OP has verified the claims provided (given_name and family_name) according to an example trust framework ial_example_gold.¶

The normative definition is given in the following.¶

verified_claims: Object or array containing one or more verified claims objects.¶

A single verified_claims object consists of the following sub-elements:¶

• verification: REQUIRED. Object that contains data about the verification process.¶

• claims: REQUIRED. Object that is the container for the verified Claims about the End-User.¶

Note: Implementations MUST ignore any sub-element not defined in this specification or extensions of this specification.¶

Note: If not stated otherwise, every sub-element in verified_claims is defined as optional. Extensions of this specification, including trust framework definitions, can define further constraints on the data structure.¶

A machine-readable syntax definition of verified_claims is given as JSON schema in [verified_claims.json]. It can be used to automatically validate JSON documents containing a verified_claims element.¶

{
  "verified_claims": {
    "verification": {
      "trust_framework":"eidas_ial_substantial",
      "evidence": [
        {
          "type": "id_document",
          "method": "pipp",
          "time": "2012-04-22T11:30Z",
          "document": {
            "type": "idcard",
            "issuer": {
              "name": "Stadt Augsburg",
              "country": "DE"
            },
            "number": "53554554",
            "date_of_issuance": "2010-03-23",
            "date_of_expiry": "2020-03-22"
          },
          "attachments": [
            {
              "desc": "Front of id document",
              "content_type": "image/png",
              "content": "Wkd0bWFtVnlhWFI2Wlc0Mk16VER2RFUyY0RRMWFUbDBNelJ1TlRjd31dzdaM1pTQXJaWGRsTXpNZ2RETmxDZwo="
            },
            {
              "desc": "Back of id document",
              "content_type": "image/png",
              "content": "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAADSFsjdkhjwhAABJRU5ErkJggg=="
            }
          ]
        }
      ]
    },
    "claims": {
      "given_name": "Max",
      "family_name": "Mustermann",
      "birthdate": "1956-01-28"
    }
  }
}

{
  "verified_claims": {
    "verification": {
      "trust_framework":"eidas_ial_substantial",
      "evidence": [
        {
          "type": "id_document",
          "method": "pipp",
          "time": "2012-04-22T11:30Z",
          "document": {
            "type": "idcard",
            "issuer": {
              "name": "Stadt Augsburg",
              "country": "DE"
            },
            "number": "53554554",
            "date_of_issuance": "2010-03-23",
            "date_of_expiry": "2020-03-22"
          },
          "attachments": [
            {
              "desc": "Front of id document",
              "digest": {
                "alg": "SHA-256",
                "value": "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg="
              },
              "url": "https://example.com/attachments/pGL9yz4hZQ",
              "access_token": "ksj3n283dke"
            },
            {
              "desc": "Back of id document",
              "digest": {
                "alg": "SHA-256",
                "value": "/WGgOvT3fYcPwh4F5+gGeAlcktgIz7O1wnnuBMdKyhM="
              },
              "url": "https://example.com/attachments/4Ag8IpOf95"
            }
          ]
        }
      ]
    },
    "claims": {
      "given_name": "Max",
      "family_name": "Mustermann",
      "birthdate": "1956-01-28"
    }
  }
}

{
  "iss": "https://server.example.com",
  "sub": "248289761001",
  "email": "janedoe@example.com",
  "email_verified": true,
  "_claim_names": {
    "verified_claims": "src1"
  },
  "_claim_sources": {
    "src1": {
      "JWT": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3NlcnZlci5vdGhlcm9wLmNvbSIsInN1YiI6ImU4MTQ4NjAzLTg5MzQtNDI0NS04MjViLWMxMDhiOGI2Yjk0NSIsInZlcmlmaWVkX2NsYWltcyI6eyJ2ZXJpZmljYXRpb24iOnsidHJ1c3RfZnJhbWV3b3JrIjoiaWFsX2V4YW1wbGVfZ29sZCJ9LCJjbGFpbXMiOnsiZ2l2ZW5fbmFtZSI6Ik1heCIsImZhbWlseV9uYW1lIjoiTWVpZXIiLCJiaXJ0aGRhdGUiOiIxOTU2LTAxLTI4In19fQ.FArlPUtUVn95HCExePlWJQ6ctVfVpQyeSbe3xkH9MH1QJjnk5GVbBW0qe1b7R3lE-8iVv__0mhRTUI5lcFhLjoGjDS8zgWSarVsEEjwBK7WD3r9cEw6ZAhfEkhHL9eqAaED2rhhDbHD5dZWXkJCuXIcn65g6rryiBanxlXK0ZmcK4fD9HV9MFduk0LRG_p4yocMaFvVkqawat5NV9QQ3ij7UBr3G7A4FojcKEkoJKScdGoozir8m5XD83Sn45_79nCcgWSnCX2QTukL8NywIItu_K48cjHiAGXXSzydDm_ccGCe0sY-Ai2-iFFuQo2PtfuK2SqPPmAZJxEFrFoLY4g"
    }
  }
}

{
  "iss": "https://server.example.com",
  "sub": "248289761001",
  "email": "janedoe@example.com",
  "email_verified": true,
  "_claim_names": {
    "verified_claims": "src1"
  },
  "_claim_sources": {
    "src1": {
      "endpoint": "https://server.yetanotherop.com/claim_source",
      "access_token": "ksj3n283dkeafb76cdef"
    }
  }
}

{
  "iss": "https://server.example.com",
  "sub": "248289761001",
  "email": "janedoe@example.com",
  "email_verified": true,
  "_claim_names": {
    "verified_claims": [
      "src1",
      "src2"
    ]
  },
  "_claim_sources": {
    "src1": {
      "JWT": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3NlcnZlci5vdGhlcm9wLmNvbSIsInN1YiI6ImU4MTQ4NjAzLTg5MzQtNDI0NS04MjViLWMxMDhiOGI2Yjk0NSIsInZlcmlmaWVkX2NsYWltcyI6eyJ2ZXJpZmljYXRpb24iOnsidHJ1c3RfZnJhbWV3b3JrIjoiaWFsX2V4YW1wbGVfZ29sZCJ9LCJjbGFpbXMiOnsiZ2l2ZW5fbmFtZSI6Ik1heCIsImZhbWlseV9uYW1lIjoiTWVpZXIiLCJiaXJ0aGRhdGUiOiIxOTU2LTAxLTI4In19fQ.FArlPUtUVn95HCExePlWJQ6ctVfVpQyeSbe3xkH9MH1QJjnk5GVbBW0qe1b7R3lE-8iVv__0mhRTUI5lcFhLjoGjDS8zgWSarVsEEjwBK7WD3r9cEw6ZAhfEkhHL9eqAaED2rhhDbHD5dZWXkJCuXIcn65g6rryiBanxlXK0ZmcK4fD9HV9MFduk0LRG_p4yocMaFvVkqawat5NV9QQ3ij7UBr3G7A4FojcKEkoJKScdGoozir8m5XD83Sn45_79nCcgWSnCX2QTukL8NywIItu_K48cjHiAGXXSzydDm_ccGCe0sY-Ai2-iFFuQo2PtfuK2SqPPmAZJxEFrFoLY4g"
    },
    "src2": {
      "endpoint": "https://server.yetanotherop.com/claim_source",
      "access_token": "ksj3n283dkeafb76cdef"
    }
  }
}

6. Requesting Verified Claims

Making a request for verified claims and related verification data can be explicitly requested on the level of individual data elements by utilizing the claims parameter as defined in Section 5.5 of the OpenID Connect specification [OpenID].¶

It is also possible to use the scope parameter to request one or more specific pre-defined claim sets as defined in Section 5.4 of the OpenID Connect specification [OpenID].¶

Note: The OP MUST NOT provide the RP with any data it did not request. However, the OP MAY at its discretion omit claims from the response.¶

{
  "userinfo": {
    "verified_claims": {
      "verification": {
        "trust_framework": null
      },
      "claims": {
        "given_name": null,
        "family_name": null,
        "birthdate": null
      }
    }
  }
}

{
  "userinfo": {
    "verified_claims": {
      "verification": {
        "trust_framework": null
      },
      "claims": {
        "given_name": {
          "essential": true
        },
        "family_name": {
          "essential": true
        },
        "birthdate": null
      }
    }
  }
}

{
  "userinfo": {
    "verified_claims": {
      "verification": {
        "trust_framework": null
      },
      "claims": {
        "given_name": {
          "essential": true,
          "purpose": "To make communication look more personal"
        },
        "family_name": {
          "essential": true
        },
        "birthdate": {
          "purpose": "To send you best wishes on your birthday"
        }
      }
    }
  }
}

{
  "userinfo": {
    "verified_claims": {
      "verification": {
        "trust_framework": null,
        "time": null
      },
      "claims": {
        "given_name": null,
        "family_name": null,
        "birthdate": null
      }
    }
  }
}

{
  "userinfo": {
    "verified_claims": {
      "verification": {
        "trust_framework": null,
        "time": null,
        "evidence": [
          {
            "type": {
              "value": "id_document"
            },
            "method": null,
            "document": {
              "type": null
            }
          }
        ]
      },
      "claims": {
        "given_name": null,
        "family_name": null,
        "birthdate": null
      }
    }
  }
}

{
  "userinfo": {
    "verified_claims": {
      "verification": {
        "trust_framework": null,
        "time": null,
        "evidence": [
          {
            "type": {
              "value": "id_document"
            },
            "method": null,
            "document": {
              "type": null,
              "issuer": {
                "country": null,
                "name": null
              },
              "number": null,
              "date_of_issuance": null
            }
          }
        ]
      },
      "claims": {
        "given_name": null,
        "family_name": null,
        "birthdate": null
      }
    }
  }
}

{
  "userinfo": {
    "verified_claims": {
      "verification": {
        "trust_framework": null,
        "attachments": null
      },
      "claims": {
        "given_name": null,
        "family_name": null,
        "birthdate": null
      }
    }
  }
}

{
  "userinfo": {
    "verified_claims": {
      "verification": {
        "trust_framework": {
          "values": [
            "silver",
            "bronze"
          ]
        }
      },
      "claims": {
        "given_name": null,
        "family_name": null
      }
    }
  }
}

{
  "userinfo": {
    "verified_claims": {
      "verification": {
        "trust_framework": {
          "value": "de_aml"
        },
        "evidence": [
          {
            "type": {
              "value": "id_document"
            },
            "method": {
              "value": "pipp"
            },
            "document": {
              "type": {
                "values": [
                  "idcard",
                  "passport"
                ]
              }
            }
          }
        ]
      },
      "claims": {
        "given_name": null,
        "family_name": null,
        "birthdate": null
      }
    }
  }
}

{
  "userinfo": {
    "verified_claims": {
      "verification": {
        "trust_framework": {
          "value": "jp_aml"
        },
        "time": {
          "max_age": 63113852
        }
      },
      "claims": {
        "given_name": null,
        "family_name": null,
        "birthdate": null
      }
    }
  }
}

{
  "userinfo": {
    "verified_claims": [
      {
        "verification": {
          "trust_framework": {
            "value": "eidas"
          },
          "identity_assurance_level": {
            "value": "high"
          }
        },
        "claims": {
          "given_name": null,
          "family_name": null
        }
      },
      {
        "verification": {
          "trust_framework": {
            "value": "eidas"
          },
          "identity_assurance_level":{
            "values":[
              "high",
              "substantial"
            ]
          }
        },
        "claims": {
          "birthdate": null
        }
      }
    ]
  }
}

{
  "userinfo": {
    "verified_claims": [
      {
        "verification": {
          "trust_framework": {
            "value": "gold"
          },
          "evidence": [
            {
              "type": {
                "value": "id_document"
              }
            }
          ]
        },
        "claims": {
          "given_name": null,
          "family_name": null
        }
      },
      {
        "verification": {
          "trust_framework": {
            "values": [
              "silver",
              "bronze"
            ]
          },
          "evidence": [
            {
              "type": {
                "value": "utility_bill"
              }
            }
          ]
        },
        "claims": {
          "given_name": null,
          "family_name": null
        }
      }
    ]
  }
}

7. Examples

The following sections show examples of responses containing verified_claims.¶

The first and second sections show JSON snippets of the general identity assurance case, where the RP is provided with verification evidence for different verification methods along with the actual Claims about the End-User.¶

The third section illustrates how the contents of this object could look like in case of a notified eID system under eIDAS, where the OP does not need to provide evidence of the identity verification process to the RP.¶

Subsequent sections contain examples for using the verified_claims Claim on different channels and in combination with other (unverified) Claims.¶

{
  "verified_claims": {
    "verification": {
      "trust_framework": "de_aml",
      "time": "2012-04-23T18:25Z",
      "verification_process": "f24c6f-6d3f-4ec5-973e-b0d8506f3bc7",
      "evidence": [
        {
          "type": "id_document",
          "method": "pipp",
          "time": "2012-04-22T11:30Z",
          "document": {
            "type": "idcard",
            "issuer": {
              "name": "Stadt Augsburg",
              "country": "DE"
            },
            "number": "53554554",
            "date_of_issuance": "2010-03-23",
            "date_of_expiry": "2020-03-22"
          }
        }
      ]
    },
    "claims": {
      "given_name": "Max",
      "family_name": "Meier",
      "birthdate": "1956-01-28",
      "place_of_birth": {
        "country": "DE",
        "locality": "Musterstadt"
      },
      "nationalities": [
        "DE"
      ],
      "address": {
        "locality": "Maxstadt",
        "postal_code": "12344",
        "country": "DE",
        "street_address": "An der Weide 22"
      }
    }
  }
}

{
  "verified_claims": {
    "verification": {
      "trust_framework": "de_aml",
      "time": "2012-04-23T18:25Z",
      "verification_process": "513645-e44b-4951-942c-7091cf7d891d",
      "evidence": [
        {
          "type": "id_document",
          "method": "pipp",
          "time": "2012-04-22T11:30Z",
          "document": {
            "type": "de_erp_replacement_idcard",
            "issuer": {
              "name": "Stadt Augsburg",
              "country": "DE"
            },
            "number": "53554554",
            "date_of_issuance": "2010-04-23",
            "date_of_expiry": "2020-04-22"
          }
        },
        {
          "type": "utility_bill",
          "provider": {
            "name": "Stadtwerke Musterstadt",
            "country": "DE",
            "region": "Niedersachsen",
            "street_address": "Energiestrasse 33"
          },
          "date": "2013-01-31"
        }
      ]
    },
    "claims": {
      "given_name": "Max",
      "family_name": "Meier",
      "birthdate": "1956-01-28",
      "place_of_birth": {
        "country": "DE",
        "locality": "Musterstadt"
      },
      "nationalities": [
        "DE"
      ],
      "address": {
        "locality": "Maxstadt",
        "postal_code": "12344",
        "country": "DE",
        "street_address": "An der Weide 22"
      }
    }
  }
}

{
  "verified_claims": {
    "verification": {
      "trust_framework": "eidas_ial_substantial"
    },
    "claims": {
      "given_name": "Max",
      "family_name": "Meier",
      "birthdate": "1956-01-28",
      "place_of_birth": {
        "country": "DE",
        "locality": "Musterstadt"
      },
      "nationalities": [
        "DE"
      ]
    }
  }
}

{
  "verified_claims": [
    {
      "verification": {
        "trust_framework": "eidas",
        "identity_assurance_level": "substantial"
      },
      "claims": {
        "given_name": "Max",
        "family_name": "Meier",
        "birthdate": "1956-01-28",
        "place_of_birth": {
          "country": "DE",
          "locality": "Musterstadt"
        },
        "nationalities": [
          "DE"
        ]
      }
    },
    {
      "verification": {
        "trust_framework": "de_aml",
        "time": "2012-04-23T18:25Z",
        "verification_process": "f24c6f-6d3f-4ec5-973e-b0d8506f3bc7",
        "evidence": [
          {
            "type": "id_document",
            "method": "pipp",
            "time": "2012-04-22T11:30Z",
            "document": {
              "type": "idcard"
            }
          }
        ]
      },
      "claims": {
        "address": {
          "locality": "Maxstadt",
          "postal_code": "12344",
          "country": "DE",
          "street_address": "An der Weide 22"
        }
      }
    }
  ]
}

{
  "userinfo": {
    "verified_claims": {
      "verification": {
        "trust_framework": null
      },
      "claims": {
        "given_name": null,
        "family_name": null,
        "birthdate": null
      }
    }
  }
}

{
  "sub": "248289761001",
  "email": "janedoe@example.com",
  "email_verified": true,
  "verified_claims": {
    "verification": {
      "trust_framework": "de_aml"
    },
    "claims": {
      "given_name": "Max",
      "family_name": "Meier",
      "birthdate": "1956-01-28"
    }
  }
}

{
  "id_token": {
    "email": null,
    "preferred_username": null,
    "picture": null,
    "verified_claims": {
      "verification": {
        "trust_framework": null,
        "time": null,
        "verification_process": null,
        "evidence": [
          {
            "type": {
              "value": "id_document"
            },
            "method": null,
            "time": null,
            "document": {
              "type": null,
              "issuer": {
                "name": null,
                "country": null
              },
              "number": null,
              "date_of_issuance": null,
              "date_of_expiry": null
            }
          }
        ]
      },
      "claims": {
        "given_name": null,
        "family_name": null,
        "birthdate": null
      }
    }
  }
}

{
  "iss": "https://server.example.com",
  "sub": "24400320",
  "aud": "s6BhdRkqt3",
  "nonce": "n-0S6_WzA2Mj",
  "exp": 1311281970,
  "iat": 1311280970,
  "auth_time": 1311280969,
  "acr": "urn:mace:incommon:iap:silver",
  "email": "janedoe@example.com",
  "preferred_username": "j.doe",
  "picture": "http://example.com/janedoe/me.jpg",
  "verified_claims": {
    "verification": {
      "trust_framework": "de_aml",
      "time": "2012-04-23T18:25Z",
      "verification_process": "f24c6f-6d3f-4ec5-973e-b0d8506f3bc7",
      "evidence": [
        {
          "type": "id_document",
          "method": "pipp",
          "time": "2012-04-22T11:30Z",
          "document": {
            "type": "idcard",
            "issuer": {
              "name": "Stadt Augsburg",
              "country": "DE"
            },
            "number": "53554554",
            "date_of_issuance": "2010-03-23",
            "date_of_expiry": "2020-03-22"
          }
        }
      ]
    },
    "claims": {
      "given_name": "Max",
      "family_name": "Meier",
      "birthdate": "1956-01-28"
    }
  }
}

{
  "iss": "https://server.example.com",
  "sub": "248289761001",
  "email": "janedoe@example.com",
  "email_verified": true,
  "verified_claims": {
    "verification": {
      "trust_framework": "ial_example_gold"
    },
    "claims": {
      "given_name": "Max",
      "family_name": "Meier"
    }
  },
  "_claim_names": {
    "verified_claims": [
      "src1",
      "src2"
    ]
  },
  "_claim_sources": {
    "src1": {
      "JWT": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3NlcnZlci5vdGhlcm9wLmNvbSIsInN1YiI6ImU4MTQ4NjAzLTg5MzQtNDI0NS04MjViLWMxMDhiOGI2Yjk0NSIsInZlcmlmaWVkX2NsYWltcyI6eyJ2ZXJpZmljYXRpb24iOnsidHJ1c3RfZnJhbWV3b3JrIjoiaWFsX2V4YW1wbGVfZ29sZCJ9LCJjbGFpbXMiOnsiZ2l2ZW5fbmFtZSI6Ik1heCIsImZhbWlseV9uYW1lIjoiTWVpZXIiLCJiaXJ0aGRhdGUiOiIxOTU2LTAxLTI4In19fQ.FArlPUtUVn95HCExePlWJQ6ctVfVpQyeSbe3xkH9MH1QJjnk5GVbBW0qe1b7R3lE-8iVv__0mhRTUI5lcFhLjoGjDS8zgWSarVsEEjwBK7WD3r9cEw6ZAhfEkhHL9eqAaED2rhhDbHD5dZWXkJCuXIcn65g6rryiBanxlXK0ZmcK4fD9HV9MFduk0LRG_p4yocMaFvVkqawat5NV9QQ3ij7UBr3G7A4FojcKEkoJKScdGoozir8m5XD83Sn45_79nCcgWSnCX2QTukL8NywIItu_K48cjHiAGXXSzydDm_ccGCe0sY-Ai2-iFFuQo2PtfuK2SqPPmAZJxEFrFoLY4g"
    },
    "src2": {
      "endpoint": "https://server.yetanotherop.com/claim_source",
      "access_token": "ksj3n283dkeafb76cdef"
    }
  }
}

{
  "iss": "https://self-issued.me",
  "sub": "248289761001",
  "preferred_username": "superman445",
  "_claim_names": {
    "verified_claims": [
      "src1",
      "src2"
    ]
  },
  "_claim_sources": {
    "src1": {
      "JWT": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3NlcnZlci5vdGhlcm9wLmNvbSIsInN1YiI6ImU4MTQ4NjAzLTg5MzQtNDI0NS04MjViLWMxMDhiOGI2Yjk0NSIsInZlcmlmaWVkX2NsYWltcyI6eyJ2ZXJpZmljYXRpb24iOnsidHJ1c3RfZnJhbWV3b3JrIjoiaWFsX2V4YW1wbGVfZ29sZCJ9LCJjbGFpbXMiOnsiZ2l2ZW5fbmFtZSI6Ik1heCIsImZhbWlseV9uYW1lIjoiTWVpZXIiLCJiaXJ0aGRhdGUiOiIxOTU2LTAxLTI4In19fQ.FArlPUtUVn95HCExePlWJQ6ctVfVpQyeSbe3xkH9MH1QJjnk5GVbBW0qe1b7R3lE-8iVv__0mhRTUI5lcFhLjoGjDS8zgWSarVsEEjwBK7WD3r9cEw6ZAhfEkhHL9eqAaED2rhhDbHD5dZWXkJCuXIcn65g6rryiBanxlXK0ZmcK4fD9HV9MFduk0LRG_p4yocMaFvVkqawat5NV9QQ3ij7UBr3G7A4FojcKEkoJKScdGoozir8m5XD83Sn45_79nCcgWSnCX2QTukL8NywIItu_K48cjHiAGXXSzydDm_ccGCe0sY-Ai2-iFFuQo2PtfuK2SqPPmAZJxEFrFoLY4g"
    },
    "src2": {
      "endpoint": "https://op.mymno.com/claim_source",
      "access_token": "ksj3n283dkeafb76cdef"
    }
  }
}

8. OP Metadata

The OP advertises its capabilities with respect to verified Claims in its openid-configuration (see [OpenID-Discovery]) using the following new elements:¶

verified_claims_supported: Boolean value indicating support for verified_claims, i.e. the OpenID Connect for Identity Assurance extension.¶

trust_frameworks_supported: JSON array containing all supported trust frameworks.¶

evidence_supported: JSON array containing all types of identity evidence the OP uses.¶

id_documents_supported: JSON array containing all identity documents utilized by the OP for identity verification.¶

id_documents_verification_methods_supported: JSON array containing the ID document verification methods the OP supports as defined in Section 5.1.¶

claims_in_verified_claims_supported: JSON array containing all claims supported within verified_claims.¶

attachments_supported: JSON array containing all attachment types supported by the OP. Possible values are external and embedded. If the list is empty, the OP does not support attachments.¶

digest_algorithms_supported: JSON array containing all supported digest algorithms which can be used as alg property within the digest object of external attachments. If the OP supports external attachments, at least the algorithm sha-256 MUST be supported by the OP as well. The list of possible digest/hash algorithm names is maintained by IANA in [hash_name_registry] (established by [RFC6920]).¶

This is an example openid-configuration snippet:¶

{
...
   "verified_claims_supported":true,
   "trust_frameworks_supported":[
     "nist_800_63A_3"
   ],
   "evidence_supported": [
      "id_document",
      "utility_bill",
      "electronic_signature"
   ],
   "id_documents_supported": [
       "idcard",
       "passport",
       "driving_permit"
   ],
   "id_documents_verification_methods_supported": [
       "pipp",
       "sripp",
       "eid"
   ],
   "claims_in_verified_claims_supported": [
      "given_name",
      "family_name",
      "birthdate",
      "place_of_birth",
      "nationalities",
      "address"
   ],
  "attachments_supported": [
    "external",
    "embedded"
  ],
  "digest_algorithms_supported": [
    "sha-256"
  ],
...
}

The OP MUST support the claims parameter and needs to publish this in its openid-configuration using the claims_parameter_supported element.¶

If the OP supports distributed and/or aggregated claim types in verified_claims, the OP MUST advertise this in its metadata using the claim_types_supported element.¶

9. Client Registration and Management

During Client Registration (see [OpenID-Registration]) as well as during Client Management [RFC7592] the following additional properties are available:¶

digest_algorithm: String value representing the chosen digest algorithm (for external attachments). The value MUST be one of the digest algorithms supported by the OP as advertised in the OP metadata. If this property is not set, sha-256 will be used by default.¶

10. Transaction-specific Purpose

This specification introduces the request parameter purpose to allow an RP to state the purpose for the transfer of End-User data it is asking for.¶

purpose: OPTIONAL. String describing the purpose for obtaining certain End-User data from the OP. The purpose MUST NOT be shorter than 3 characters and MUST NOT be longer than 300 characters. If these rules are violated, the authentication request MUST fail and the OP returns an error invalid_request to the RP.¶

The OP MUST display this purpose in the respective End-User consent screen(s) in order to inform the End-User about the designated use of the data to be transferred or the authorization to be approved.¶

In order to ensure a consistent UX, the RP MAY send the purpose in a certain language and request the OP to use the same language using the ui_locales parameter.¶

If the parameter purpose is not present in the request, the OP MAY utilize a description that was pre-configured for the respective RP.¶

Note: In order to prevent injection attacks, the OP MUST escape the text appropriately before it will be shown in a user interface. The OP MUST expect special characters in the URL decoded purpose text provided by the RP. The OP MUST ensure that any special characters in the purpose text cannot be used to inject code into the web interface of the OP (e.g., cross-site scripting, defacing). Proper escaping MUST be applied by the OP. The OP SHALL NOT remove characters from the purpose text to this end.¶

11. Privacy Consideration

Timestamps with a time zone component can potentially reveal the person's location. To preserve the person's privacy timestamps within the verification element and verified claims that represent times SHOULD be represented in Coordinated Universal Time (UTC), unless there is a specific reason to include the time zone, such as the time zone being an essential part of a consented time related claim in verified data.¶

The use of scopes is a potential shortcut to request a pre-defined set of claims, however, the use of scopes might result in more data being returned to the RP than is strictly necessary and not achieving the goal of data minimisation. The RP SHOULD only request End-User claims and metadata it requires.¶

12. Security Considerations

This specification focuses on mechanisms to carry End-User claims and accompanying metadata in JSON objects and JSON web tokens, typically as part of an OpenID Connect protocol exchange. Since such an exchange is supposed to take place in security sensitive use cases, implementers MUST combine this specification with an appropriate security profile for OpenID Connect.¶

This specification does not define or require a particular security profile since there are several security profiles and new security profiles under developmewnt. Implementers shall be given flexibility to select the security profile that best suits their needs. Implementers might consider [FAPI-1-RW] or [FAPI-2-BL].¶

Implementers are recommended to select a security profile that has a certification program or other resources that allow both OpenID Providers and Relying Parties to ensure they have complied with the profile's security and interoperability requirements, such as the OpenID Foundation Certification Program, https://openid.net/certification/.¶

The integrity and authenticity of the issued assertions MUST be ensured in order to prevent identity spoofing.¶

The confidentiality of all End-User data exchanged between the protocol parties MUST be ensured using suitable methods at transport or application layer.¶

13. Predefined Values

This specification focuses on the technical mechanisms to convey verified claims and thus does not define any identifiers for trust frameworks, id documents, or verification methods. This is left to adopters of the technical specification, e.g. implementers, identity schemes, or jurisdictions.¶

Each party defining such identifiers MUST ensure the collision resistance of those identifiers. This is achieved by including a domain name under the control of this party into the identifier name, e.g. https://mycompany.com/identifiers/cool_verification_method.¶

The eKYC and Identity Assurance Working Group maintains a wiki page [predefined_values_page] that can be utilized to share predefined values with other parties.¶

Appendix A. IANA Considerations

Appendix B. Acknowledgements

The following people at yes.com and partner companies contributed to the concept described in the initial contribution to this specification: Karsten Buch, Lukas Stiebig, Sven Manz, Waldemar Zimpfer, Willi Wiedergold, Fabian Hoffmann, Daniel Keijsers, Ralf Wagner, Sebastian Ebling, Peter Eisenhofer.¶

We would like to thank Julian White, Bjorn Hjelm, Stephane Mouy, Alberto Pulido, Joseph Heenan, Vladimir Dzhuvinov, Kosuke Koiwai, Azusa Kikuchi, Naohiro Fujie, Takahiko Kawasaki, Sebastian Ebling, Marcos Sanz, Tom Jones, Mike Pegman, Michael B. Jones, Jeff Lombardo, Taylor Ongaro, and Mark Haine for their valuable feedback and contributions that helped to evolve this specification.¶

Appendix C. Notices

Copyright (c) 2020 The OpenID Foundation.¶

The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.¶

The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.¶

Appendix D. Document History

[[ To be removed from the final specification ]]¶

-12¶

• added support to attach document artifacts¶

• changed evidence type qes to electronic_signature¶

• Added claim also_known_as¶

• Added text regarding security profiles¶

• Editorial improvements¶

• Added further co-authors¶

• Added identity_assurance_level field¶

-11¶

• Added support for requesting different sets of claims with different requirements regarding trust_framework and other verification elements (e.g. evidence)¶

• added msisdn claim¶

• clarified scope of this specification¶

-10¶

• Editorial improvements¶

• Improved JSON schema (alignment with spec and bug fix)¶

-09¶

• verified_claims element may contain one or more verified claims objects¶

• an individual assertion may contain verified_claims elements in the assertion itself and any aggregated or distributed claims sets it includes or refers to, respectively¶

• moved all definitions of pre-defined values for trust frameworks, id documents and verification methods to a wiki page as non-normative overview¶

• clarified and simplified request syntax¶

• reduced mandatory requirement verified_claims to bare minimum¶

• removed JSON schema from draft and added reference to JSON schema file instead¶

• added request JSON schema¶

• added IANA section with JSON Web Token Claims Registration¶

• integrated source into single md file¶

• added privacy considerations regarding time zone data, enhanced syntax definition of time and date-time fields in spec and response schema¶

• fixed typos¶

-08¶

• added uripp verification method¶

• small fixes to examples¶

-07¶

• fixed typos¶

• changed nationality String claim to nationalities String array claim¶

• replaced agent in id_document verifier element by txn element¶

• qes method: fixed error in description of issuer¶

• qes method: changed issued_at to created_at since this field applies to the signature (that is created and not issued)¶

• Changed format of nationalities and issuing country to ICAO codes¶

• Changed date in verification element to time¶

• Added Japanese trust frameworks to pre-defined values¶

• Added Japanese id documents to pre-defined values¶

• adapted JSON schema and examples¶

-06¶

• Incorporated review feedback by Marcos Sanz and Adam Cooper¶

• Added text on integrity, authenticity, and confidentiality for data passed between OP and RP to Security Considerations section¶

• added purpose field to claims parameter¶

• added feature to let the RP explicitly requested certain verification data¶

-05¶

• incorporated review feedback by Mike Jones¶

• Added OIDF Copyright Notices¶

• Moved Acknowledgements to Appendix A¶

• Removed RFC 2119 keywords from scope & requirements section and rephrased section¶

• rephrased introduction¶

• replaced birth_name with birth_family_name, birth_given_name, and birth_middle_name¶

• replaced transaction_id with txn from RFC 8417¶

• added references to eIDAS, ISO 3166-1, ISO 3166-3, and ISO 8601-2004¶

• added note on purpose and locales¶

• changed file name and document title to include 1.0 version id¶

• corrected evidence plural¶

• lots of editorial fixes¶

• Alignment with OpenID Connect Core wording¶

• Renamed id to verification_process¶

• Renamed verified_person_data to verified_claims¶

-04¶

• incorporated review feedback by Marcos Sanz¶

-03¶

• enhanced draft to support multiple evidence¶

• added a JSON Schema for assertions containing the verified_person_data Claim¶

• added more identity document definitions¶

• added region field to place_of_birth Claim¶

• changed eidas_loa_substantial/high to eidas_ial_substantial/high¶

• fixed typos in examples¶

• uppercased all editorial occurences of the term claims to align with OpenID Connect Core¶

-02¶

• added new request parameter purpose¶

• simplified/reduced number of verification methods¶

• simplfied identifiers¶

• added identity_documents_supported to metadata section¶

• improved examples¶

-01¶

• fixed some typos¶

• remove organization element (redundant) (issue 1080)¶

• allow other Claims about the End-User in the claims sub element (issue 1079)¶

• changed legal_context to trust_framework¶

• added explanation how the content of the verification element is determined by the trust framework¶

• added URI-based identifiers for trust_framework, identity_document and (verification) method¶

• added example attestation for notified/regulated eID system¶

• adopted OP metadata section accordingly¶

• changed error behavior for max_age member to alig with OpenID Core¶

• Added feature to let the RP express requirements for verification data (trust framework, identity documents, verification method)¶

• Added privacy consideration section and added text on legal basis for data exchange¶

• Added explanation about regulated and un-regulated eID systems¶

-00 (WG document)¶

• turned the proposal into a WG document¶

• changed name¶

• added terminology section and reworked introduction¶

• added several examples (ID Token vs UserInfo, unverified & verified claims, aggregated & distributed claims)¶

• incorporated text proposal of Marcos Sanz regarding max_age¶

• added IANA registration for new error code unable_to_meet_requirement¶

Authors' Addresses