openid-connect-authority-1_0 November 2024
Haine & White Standards Track [Page]
Workgroup:
eKYC_IDA
Published:
Authors:
M. Haine
considrd.consulting
J. White
Beruku

OpenID Connect Authority claims extension

Abstract

This document defines an extension of OpenID Connect for providing Relying Parties with verified claims about the relationships between legal persons (humans and other humans or organisations), in a secure way, using OIDC and OAuth 2.0 protocols. This extension is intended to be used to communicate a relationship between a natural person and another natural person or legal entity in a way that can be relied upon.

▲

Table of Contents

1. Introduction

Building upon the work done in the OIDF [OpenID] eKYC & IDA Working group on verified claims for natural persons there is a need to be able to deliver verified claims about the authority a natural person has to act on behalf of another natural person or legal entity. As described in Section 1 of the OpenID Connect specification [OpenID], OpenID Connect "enables clients to verify the identity of the end-user" This extension will therefore focus on communicating details of a natural person's authority over another natural person or legal entity.

Note: Work to define how direct claims of a legal entity are transferred could use elements of eKYC & IDA specifications such as the structure of the verified_claims element and there are specific claims added as part of this document to enable legal entities to be uniquely defined.

1.1. Terminology

This section defines some terms relevant to the topic covered in this document

Legal person: - Cornell Law School "Legal person refers to a human or non-human entity that is treated as a person for limited legal purposes. Typically, a legal persons can sue and be sued, own property, and enter into contracts."

Natural person: - Termly "A natural person (also sometimes referred to as a physical person) is a title used to identify an individual human being. This is different from a legal person, which can be an individual or a company."

Legal entity: - Cambridge dictionary "a company or organization that has legal rights and responsibilities" - ISO 17442 "legal entities, which include, but are not limited to, unique parties that are legally or financially responsible for the performance of financial transactions or have the legal right in their jurisdiction to enter independently into legal contracts, regardless of whether they are incorporated or constituted in some other way (e.g. trust, partnership, contractual). It includes governmental organizations, supranationals and individuals when acting in a business capacity, but excludes natural persons." Note: the term "legal entity" is used in this specification to mean an organisation, rather than "legal person", since "legal person" can also refer to a "natural person".

Authority: - Britannica Dictionary "the power or right to direct or control someone or something" Note: the "someone" for the purposes of this specification is a "natural person", and the "something" is a "legal entity".

This specification uses the terms: * "Access Token", * "Authorization Code", * "Authorization Endpoint", * "Authorization Grant", * "Authorization Server", * "Client", * "Client Authentication", * "Client Identifier", * "Client Secret", * "Grant Type", * "Protected Resource", * "Redirection URI", * "Refresh Token", * "Response Type", * and "Token Endpoint" defined by [RFC6749]

the terms: * "Claim Name", * "Claim Value" * and "JSON Web Token (JWT)" defined by [RFC7519]

the terms: * "Header Parameter", * "JOSE Header" * and "JSON Web Signature (JWS)" defined by [RFC7519]

the term "User Agent" defined by [RFC2616]

the terms: * "Authentication", * "Authentication Request", * "Authorization Request", * "Claim", * "Claim Type", * "Claims Provider", * "Credential", * "End-User", * "Entity", * "ID Token", * "Identifier", * "Identity", * "Issuer", * "OpenID Provider (OP)", * "Request Object", * "Request URI", * "Relying Party (RP)", * "UserInfo Endpoint", * "Validation", * "Verification" defined by OpenID Connect [OpenID]

This specification also use to the following terms:

OpenID
References to "openid" in this documentation are about OpenID connect specification [OpenID]

2. Scope and Requirements

Use cases relating to legal entities and initiated by an end-user relate to "authority to act" where the end-user themselves is authorizing the presentation of the claims. In one example a director of a company has the authority to act on its behalf. When communicating data in this example there will be data about the authority including:

2.1. In Scope Use Cases

There are a number of use cases that were considered when writing this document as detailed below. However, this document is to deliver a specification for "authority to act" related use cases.

2.1.2. Get authority of natural person over another natural person

"As a relying party I require specific attributes about the relationship a natural person has to a another natural person and how the details of the relationship were established"

  • Key attributes relating to the natural person who has the authority e.g.

    • name
    • address
    • date of birth
    • personal identification number (e.g. social security number)

  • Key attributes relating to the natural person to which the authority applies e.g.

    • name
    • address
    • date of birth
    • personal identification number (e.g. social security number)

  • The nature of the relationship between the natural persons

    • The scope of the authority e.g.

      • financial
      • medical
      • familial
      • legal

    • Any limitations of the authority e.g.

      • time (e.g. can only use authority on weekdays)
      • audience (e.g. tax authority or accountant)
      • budget (e.g. up to £5000)
      • other dependencies (e.g. 2nd approver)

    • How the authority was granted

      • delegated by the natural person to whom the authority applies to (e.g. giving authority to a spouse to access an account)
      • appointed by a legal process (e.g. power of attorney)
      • asserted by a person (e.g. parent of a minor)

This use case is the secondary focus of this document

2.2. Out of Scope Use Cases

3. Claims

In order to fulfill the requirements of some jurisdictions on identity assurance, this specification defines the following claims for conveying data in addition to the claims defined in the OpenID Connect specification [OpenID]:

3.2. authority element

This specification defines a generic mechanism to allow communication of authority claims via JSON-based assertions. The basic idea is to use a container element, called authority to provide the RP with a set of claims that expresses the authority that may exist of one entity over another. This set of authority claims are presented as claims about the end-user and it allows for the use of the sub-elements applies_to, permission, and granted_by.

The following example uses the verified claims structure from the draft eKYC & Identity assurance specification:

{
    "sub": "BSmith",
    "email": "bobsmith@example.com",
    "verified_claims": {
      "verification": {
        "trust_framework": "authority_claims_example_framework",
        "time":"2020-04-23T18:25Z",
        "verification_process":"f24c6f-6d3f-4ec5-973e-b0d8506f3bc7"
      },
      "claims": {
        "given_name": "Bob",
        "family_name": "Smith",
        "birthdate": "1981-01-26",
        "authority": [ {
            "applies_to": {
                "organization_name": "Example Company Limited",
                "trading_as": "XAmple",
                "registered_address": "123 Acacia Avenue, Newtown, UK",
                "registration_number": "12351235",
                "registration_authority_code": "RA000585",
                "legal_jurisdiction": "GB",
                "entity_legal_form": "H0PO",
                "organisation_status": "Active",
                "incorporation_date": "2000-01-01",
                "organization_identifiers": [{
                    "identifier_type": "LEI",
                    "identifier": "H7FNTJ4851HG0EXQ1Z70",
                    "issuer": "RapidLEI"
                    },
                    {
                    "identifier_type": "DUNS",
                    "identifier": "123456789",
                    "issuer": "Dun & Bradstreet"
                    },
                    {
                    "identifier_type": "FRN",
                    "identifier": "928911",
                    "issuer": "FCA"
                    }
                ]
            },
            "permission": [ {
                "role": "Director",
                "validity":[ {
                    "start": "2018-03-02T10:00Z"
                    }]
            }],
            "granted_by": {
                "method": "appointment",
                "granting_body": "Companies House",
                "reason": "Official company officer"
            }
        }]
      }
    }
}

This would assert to the RP that the OP has verified the claims provided (given_name, family_name, birthdate, and the authority sub-element) according to an example trust framework authority_claims_example_framework.

The normative definition is given of the following.

authority: Object or array containing one or more authority objects.

A single authority object consists of the following sub-elements:

  • applies_to: Required. Object that contains data about the entity that the authority applies to.
  • permission: Required. Object that is the container used for defining the actions that the end-user is permitted to take in relation to the entity defined in the applies_to sub element of authority.
  • granted_by: Optional. Object that is the container for definition of how the authority was granted to the end-user.

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

Note: If not stated otherwise, the sub-elements in authority are as defined above. Extensions of this specification, including trust framework definitions, can define further constraints on the data structure by changing granted_by from "optional" to "required".

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

3.3. applies_to element

The applies_to sub-element is intended to convey claims that allow unique identification of the entity that the authority applies to. The applies_to sub-element contains a number of different claims and those will depend on the particular use case and will, in particular, depend on whether the applies_to sub-element is identifying a legal entity or a natural person.

In the case that the authority applies to a legal entity the applies_to element may contain one or more of the claims in the 'Claims about a legal entity' section above (and others as required) providing it allows for sufficient confidence that the legal entity can be uniquely identified from that set of claims.

In the case that the authority applies to a natural person the applies_to element may contain one or more of the following claims (and others as required) providing it allows for sufficient confidence that the natural person can be uniquely identified from that set of claims:

Table 2
Claim Type Description
sub String Subject Identifier as defined in Section 2 of the OpenID Connect specification [OpenID]. This can be used when the natural person can be identified by the same IdP providing the authority claim.
name String as defined in Section 5.1 of the OpenID Connect specification [OpenID]
given_name String as defined in Section 5.1 of the OpenID Connect specification [OpenID]
middle_name String as defined in Section 5.1 of the OpenID Connect specification [OpenID]
family_name String as defined in Section 5.1 of the OpenID Connect specification [OpenID]
birthdate String as defined in Section 5.1 of the OpenID Connect specification [OpenID]
address JSON object as defined in Section 5.1 of the OpenID Connect specification [OpenID]
aka JSON object as defined in Section 5 of the OpenID Connect Account Porting specification [OpenID-AccountPorting]. This can be used when the natural person can be identified by the sub value of other IdP.

Other attributes not in the list may also be used if they allow for unique identification.

3.4. permission element

The permission sub-element is intended to convey the range of actions that the end-user is allowed to take when acting for the entity identified in the applies_to sub-element.

The permission sub-element consists of an array of objects that contain the following objects and may contain further objects that describe any additional extensions or restrictions of the authority over the target entity:

  • role: Required. Object that reflects the role held by the end-user in relation to the target entity, e.g., roles defined by GLEIF based on [ISO5009]
  • validity: Optional. Object that contains an array that shall have either a start or end and can optionally have both. Both the start and end objects are a reference date in [ISO8601-2004] YYYY-MM-DD format that is used to represent and are used to define the date limits of the authority being conveyed.
  • budget: Optional. Object that contains an array that shall have both value and currency elements. This object is intended to describe the maximum extent of the end-user's financial authority. The value object will be a string that includes a decimal point and accurate to two decimal places. The currency object will contain the alphabetic format defined in [ISO4217-2015] (Currency codes) and defines which financial currency the value is in.
  • audience: Optional. Limitation of the scope of entity or entities that the end-user communicates with when acting on behalf of the entity defined in the applies_to element
  • function: Optional. Limitation of the scope of action that the end-user takes by functional domain.
  • may_delegate: Optional. A boolean value that indicates whether the authority or components of the authority can be delegated by the subject to other entities or not.

3.5. granted_by element

The granted_by sub-element is intended to convey the manner in which the permission came to be associated with the end-user. The granted_by sub-element may contain the claims described below and may contain further objects that describe any additional data about how the authority was vested in the end-user:

  • method: Required. The method claim is a definition of how the authority came to lie with the end-user. In an implementation there should be a defined set of valid values, these values may include:

    • "delegated": Where a holder of authority passes some or all of their authority on to the end-user. e.g. director of company delegates some authority to a member of staff
    • "appointed": Where a legal authority such as a court of law defined that the authority will be vested in the end-user. e.g. administrators are appointed by the court to manage a company in difficulties or social services are appointed as guardians of a vulnerable person
    • "self-asserted": Where the end-user themselves has stated that the authority belongs to them. e.g. the claim of parenthood over a child
  • granting_body: Optional. The granting_body claim is used to identify the body that vested the authority in the end-user. e.g. The High Court of London or another member of staff at the end-user's employer that already has the authority and has the authority to delegate that authority.
  • reason: Optional. The reason claim is a description of why the authority was granted to the end-user.

** Question - should there be a chain of authority built or should it just be a summary of the overall grant process? perhaps with clearer definition in the trust framework **

4. Requesting authority claims

Making a request for authority 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 predefined claim sets as defined in Section 5.4 of the OpenID Connect specification [OpenID].

4.1. Error Handling

The OP has the discretion to decide whether the requested verification data is to be provided to the RP. An OP shall not return an error in case it cannot return a requested verification data, even if it was marked as essential, regardless of the data being unavailable or the end-user not authorizing its release.

5. Examples

Incomplete, insert 'company director, power of attorney idToken & userInfo response examples here

5.1. Responses

5.1.1. Parent and Child

In this example a parent with the parent/guardian responsibility is represented in the following JSON that would be returned in a UserInfo response.

{
    "sub": "KMcCallister",
    "email": "kmcc@example.com",
    "verified_claims": {
      "verification": {
        "trust_framework": "authority_claims_example_framework",
        "time":"2020-04-23T18:25Z",
        "verification_process":"f24c6f-6d3f-4ec5-973e-b0d8506f3bc7"
      },
      "claims": {
        "given_name": "Kate",
        "family_name": "McCallister",
        "birthdate": "1992-01-26",
        "authority": [ {
            "applies_to": {
                "given_name": "Kevin",
                "family_name": "McCallister",
                "birthdate": "2016-01-26"
            },
            "permission": [ {
                "role": "Legal Guardian"
            }]
        }]
      }
    }
}

6. OP Metadata

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

authority_claims_supported: Boolean value indicating support for authority, i.e. the OpenID Connect authority claims extension.

authority_permissions_supported: JSON array containing all values for the role claim utilized by the OP for authority permissions.

authority_granted_methods_supported: JSON array containing all values for the method claim utilized by the OP for commmunicating how authority was confered.

authority_claims_supported: JSON array containing all claims supported within authority.

This is an example openid-configuration snippet:

{
...
   "authority_claims_supported":true,
   "authority_permissions_supported":[
     "Director",
     "Finance Officer",
     "Member of Staff"
   ],
   "authority_granted_methods_supported":[
      "delegated",
      "appointed",
      "self-asserted"
   ],
   "documents_supported":[
       "idcard",
       "passport",
       "driving_permit"
   ],
   "document_check_methods_supported":[
       "pipp",
       "sripp",
       "eid"
   ],
   "authority_claims_supported":[
         { "applies_to": [
                "organization_name",
                "registration_number",
                "legal_jurisdiction"
            ]
         },
        { "permission": [
                "role",
                { "validity":[
                    "start",
                    "end"
                    ]
                }
            ],
        }
        { "granted_by": [
                "method",
                "granting_body",
                "reason"
                ]
        }
   ],
...
}

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

7. Privacy Consideration

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.

8. 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 shall 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 development. 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 should 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 shall be ensured in order to prevent identity spoofing. The claims source shall therefore cryptographically sign all assertions.

The confidentiality of all end-user data exchanged between the protocol parties shall be ensured using suitable methods at transport or application layer.

9. Predefined Values

This specification focuses on the technical mechanisms to convey authority 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 shall 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_check_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.

10. Normative References

[GLEIF-ELF]
Global Legal Entity Identifier Foundation, "GLEIF Entity Legal Forms", , <https://www.gleif.org/en/about-lei/code-lists/iso-20275-entity-legal-forms-code-list#>.
[GLEIF-LJ]
Global Legal Entity Identifier Foundation, "GLEIF Legal Jurisdictions", , <https://www.gleif.org/en/about-lei/code-lists/gleif-accepted-legal-jurisdictions-code-list#>.
[GLEIF-RA]
Global Legal Entity Identifier Foundation, "GLEIF Registration Authorities", , <https://www.gleif.org/en/about-lei/code-lists/gleif-registration-authorities-list#>.
[ISO17442-1-2020]
ISO, "ISO 17442-1:2020. Financial services — Legal entity identifier (LEI) — Part 1: Assignment", , <https://www.iso.org/standard/78829.html>.
[ISO20275]
ISO, "ISO 20275. Financial services — Entity legal forms (ELF)", , <https://www.iso.org/obp/ui/#iso:std:iso:20275:ed-1:v1:en>.
[ISO4217-2015]
ISO, "ISO 4217:2015. Codes for the representation of currencies", , <https://www.iso.org/en/contents/data/standard/06/47/64758.html>.
[ISO5009]
ISO, "ISO 5009. Financial services — Official organizational roles — Scheme for official organizational roles", , <https://www.iso.org/standard/80603.html>.
[ISO8601-2004]
ISO, "ISO 8601:2004. Data elements and interchange formats - Information interchange - Representation of dates and times", , <http://www.iso.org/iso/catalogue_detail?csnumber=40874>.
[OpenID]
Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0 incorporating errata set 1", , <http://openid.net/specs/openid-connect-core-1_0.html>.
[OpenID-AccountPorting]
Manger, J., Lodderstedt, T., and A. Gleditsch, "OpenID Connect Account Porting", , <https://openid.net/specs/openid-connect-account-porting-1_0.html>.
[OpenID-Discovery]
Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID Connect Discovery 1.0 incorporating errata set 1", , <https://openid.net/specs/openid-connect-discovery-1_0.html>.
[RFC2616]
Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, DOI 10.17487/RFC2616, , <https://www.rfc-editor.org/info/rfc2616>.
[RFC6749]
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/info/rfc6749>.
[RFC7519]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, , <https://www.rfc-editor.org/info/rfc7519>.
[authority.json]
OpenID Foundation, "JSON Schema for assertions using authority claims", , <https://openid.net/schemas/authority-00.json>.
[predefined_values_page]
OpenID Foundation, "Overview page for predefined values", , <https://openid.net/wg/ekyc-ida/identifiers/>.

11. Informative References

[FAPI-1-RW]
OpenID Foundation's Financial API (FAPI) Working Group, "Financial-grade API - Part 2: Read and Write API Security Profile", , <https://bitbucket.org/openid/fapi/src/master/Financial_API_WD_002.md>.
[FAPI-2-BL]
OpenID Foundation's Financial API (FAPI) Working Group, "FAPI 2.0 Baseline Profile", , <https://bitbucket.org/openid/fapi/src/master/FAPI_2_0_Baseline_Profile.md>.

Appendix A. IANA Considerations

A.1. JSON Web Token Claims Registration

This specification requests registration of the following value in the IANA "JSON Web Token Claims Registry" established by [RFC7519].

Appendix B. Acknowledgements

The following people at Considrd.consulting, partner companies and OpenID Foundation contributed to the the initial draft of this specification: Edmund Sutcliffe, Seinar Noem, Ben Helps, Torsten Lodderstedt, Alberto Pulido, Taylor Ongaro, Tom Jones, Adam Cooper, Jim Willeke, Don Thibeau, Nat Sakimura and Kai Lehmann.

We would also like to thank Naohiro Fujie, Bjorn Hjelm, Stephane Mouy, Joseph Heenan, Vladimir Dzhuvinov, Kosuke Koiwai, Takahiko Kawasaki, Edmund Jay, and Hodari McClain 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

-00 (Initial draft of the specification document)

Authors' Addresses

Mark Haine
considrd.consulting
Julian White
Beruku