Self-Issued OpenID Provider V2, draft 03

2.1. Resilience against Sudden or Planned OP Unavailability

An OpenID Provider's infrastructure may become unavailable or even destroyed due to natural disasters such as hurricanes, tsunamis and fires, or may be removed from service as a planned business decision. As Self-Issued OPs are local to the End-user environment, there is resilience against such events simultaneously affecting a significant portion of otherwise unimpacted End-Users.¶

2.2. Authentication at the edge

As internet-connected smartphones have risen in availability, traditionally in-person interactions and services have begun to be optimized with digital alternatives. These services often have requirements for digital authentication and for other identity credentials. Self-Issued OPs can provide this authentication directly, without needing to delegate to remote, hosted OPs. This potentially allows for increased efficiency as well as allowing for authentication in environments which may have reduced connectivity.¶

2.3. Sharing credentials from several issuers in one transaction

When End-users apply to open a banking account online, in most countries they are required to submit scanned versions of the required documents. These documents are usualy issued by different authorities, and hard to be verified in a digital form. A Self-issued OP directly representing the user may have access to a greater set of such information as credentials, while a traditional OP may not have a business relationship which enables access to such a breadth of information. Self-Issued OPs could aggregate credentials from multiple sources, then release them within a single transaction to a relying party. The relying party can then verify the authenticity of the information to make the necessary business decisions.¶

2.4. Aggregation of multiple personas under one Self-Issued OP

End-users often use several hosted OpenID Providers for different Relying Parties. While there are many reasons to do this, often this is done to have separately maintained identities, such as keeping a work-related persona separate from a personal persona. An End-user may do this to specifically represent different sets of claims, or because they what to prevent relying parties from correlating their activities by using the same OP. The usage of multiple OPs can create friction later, as the end-user may return later having forgot which OP they used for the relying party.¶

A single Self-Issued OP can be chosen by the End-user based on its capability to meet specific needs and privacy concerns. The separately-defined ability to present third-party credentials allows the RP to accept Self-Issued ID Tokens while still evaluating attributes using reputational trust of the credential issuers.¶

4.1. Abbreviations

• Self-Issued OP: Self-Issued OpenID Provider¶

• RP: Relying Party¶

• OP: OpenID Provider¶

6.1. Self-Issued OpenID Provider Discovery

When the End-user first interacts with the RP there are no established means to signal where to direct the request for an available Self-Issued OP application. Even if possible, such signals may be susceptible to fingerprinting and passive tracking of the End-user.¶

The RP is therefore responsible for selecting where to direct the request URL. When the RP wants to support the End-user's choice oto select from multiple possible Self-Issued OP applications, it MAY present a static list of the available choices. This is very similar to the process of supporting multiple different social networks.¶

Alternatively the RP MAY belong to at least one trust framework. The trust framework is then responsible for hosting a public website that maintains the latest platform specific metadata for all supported Self-Issued OP applications, known as app-link or universal link at the time of publication. The RP forms the request URL to that shared website and any of the supported installed applications will instead be launched and given the request to process. If none are available, the website will be displayed with the static list for the End-user to choose from to install or use.¶

The trust framework MAY be operated by just one RP, but due to the required maintenance of every application's metadata (which may change frequently) this burden SHOULD be shared across multiple RPs. The same trust framework MAY also be used to host metadata about the supported RPs such that the Self-Issued OP applications can verify the origin of the incoming request as part of the framework as well.¶

The legacy usage of custom protocol schemas such as openid: as a way to invoke any installed Self-Issued OP is NOT RECOMMENDED due to the security issues (see (invocation-using-custom-schema) in Privacy Considerations section).¶

  {
   "authorization_endpoint":
    "openid:",
   "issuer":
    "https://self-issued.me/v2",
   "response_types_supported":
    ["id_token"],
   "scopes_supported":
    ["openid", "profile", "email", "address", "phone"],
   "subject_types_supported":
    ["pairwise"],
    "id_token_signing_alg_values_supported":
    ["ES256", "ES256K"],
   "request_object_signing_alg_values_supported":
    ["ES256", "ES256K"]
  }

6.2. Relying Party Registration

Relying Party must communicate which metadata parameters it supports. If Self-Issued OP and RP mutually support a compatible set of parameters, Self-Issued OP flow continues. If they do not, Self-Issued OP returns an error. Metadata parameters should preferrably be sent by reference as a URI, but when RP cannot host a webserver, they can be sent by value.¶

OpenID Connect defines the following negotiation parameters to enable Relying Party to provide information about itself to a Self-Issued OP that would normally be provided to an OP during Dynamic Client Registration:¶

registration OPTIONAL. This parameter enables RP Registration Metadata to be passed in a single, self-contained parameter. The value is a JSON object containing RP Registration Metadata values.¶

registration_uri OPTIONAL. This parameter enables RP Registration Metadata to be passed by reference, rather than by value. The request_uri value is a URL using the https scheme referencing a resource containing RP Negotiation Metadata values.¶

RP MUST use either of there parameters, but if one of these parameters is used, the other MUST NOT be used in the same request.¶

RP Negotiation metadata values are defined in Section 4.3 and Section 2.1 of the OpenID Connect Dynamic RP Registration 1.0 [OpenID.Registration] specification.¶

If Self-Issued OP supports the same parameters, Self-Issued OpenID Provider flow continues, if Self-Issued OP does not support, it returns an error.¶

If no error is returned, the RP must proceed as if it had obtained the following Client Registration Response:¶

• client_id¶

  • redirect_uri value of the Client.¶

• clientsecretexpires_at¶

  • 0¶

Metadata parameters should preferably be sent by reference as a URI using registration_uri parameter, but when RP cannot host a webserver, metadata parameters should be sent by value using registration parameter.¶

registration and registration_uri parameters SHOULD NOT be used when the OP is not a Self-Issued OP.¶

  {
   "subject_identifier_types_supported":
    ["did", "jkt"],
    "did_methods_supported":
    ["did:key:", "did:example:"]
  }

6.3. Sub Types

A sub type is used by Self-Issued OP to advertise which types of identifiers are supported for the sub claim. Two types are defined by this specification:¶

• jkt¶

  • JWK Thumbprint Subject sub type. When this subject sub type is used, the sub claim value MUST be the base64url encoded representation of the thumbprint of the key in the sub_jwk claim [RFC7638], and sub_jwk MUST be included in the Self-Issed OP response.¶

• did¶

  • Decentralized Identifier sub type. When this subject type is used, the sub value MUST be a DID defined in [DID-CORE], and sub_jwk MUST NOT be included in the Self-Issed OP response. The subject type MUST be cryptographicaly verified against the resolved DID Document as defined in Self-Issued OP Validation.
    ¶

NOTE: Consider adding a subject type for OpenID Connect Federation entity statements.¶

6.4. Relying Party Registration Metadata Error Response

This extension defines the following error codes that MUST be returned when Self-Issued OP does not support all of the Relying Party Registration metadata values received from the Relying Party in the registration parameter:¶

• did_methods_not_supported¶

  • The Self-Issued OP does not support all of the DID methods included in did_methods_supported parameter.¶

• subject_identifier_types_not_supported¶

  • The Self-Issued OP does not support all of the subject identifier types included in subject_identifier_types_supported parameter.¶

• credential_formats_not_supported¶

  • The Self-Issued OP does not support all of the credential formats included in credential_formats_supported parameter.¶

• value_not_supported¶

  • The Self-Issued OP does not support more than one of the RP Registration Metadata values defined in Section 4.3. When not supported metadata values are DID methods, subject identifier types, or credential formats, more specific error message must be used.¶

• invalid_registration_uri¶

  • The registration_uri in the Self-Issued OpenID Provider request returns an error or contains invalid data.¶

• invalid_registration_object¶

  • The registration parameter contains an invalid RP Registration Metadata Object.¶

Error response must be made in the same manner as defined in Section 3.1.2.6.¶

7.1. Self-Issued OpenID Provider Request

The RP sends the Authentication Request to the Authorization Endpoint with the following parameters:¶

• scope¶

  • REQUIRED. scope parameter value, as specified in Section 3.1.2.¶

• response_type¶

  • REQUIRED. Constant string value id_token.¶

• client_id¶

  • REQUIRED. Client ID value for the Client, which in this case contains the redirect_uri value of the RP.¶

• redirect_uri¶

  • REQUIRED. MUST equal to client_id value. MUST be included for compatibility reasons.¶

• id_token_hint¶

  • OPTIONAL. idtokenhint parameter value, as specified in Section 3.1.2. If the ID Token is encrypted to the Self-Issued OP, the sub (subject) of the signed ID Token MUST be sent as the kid (Key ID) of the JWE.¶

• claims¶

  • OPTIONAL. claims parameter value, as specified in Section 5.5.¶

• registration¶

  • OPTIONAL. This parameter is used by the RP to provide information about itself to a Self-Issued OP that would normally be provided to an OP during Dynamic RP Registration, as specified in Section 2.2.1.
    ¶

• registration_uri¶

  • OPTIONAL. This parameter is used by the RP to provide information about itself to a Self-Issued OP that would normally be provided to an OP during Dynamic RP Registration, as specified in Section 2.2.2.¶

• request¶

  • OPTIONAL. Request Object value, as specified in Section 6.1. The Request Object MAY be encrypted to the Self-Issued OP by the RP. In this case, the sub (subject) of a previously issued ID Token for this RP MUST be sent as the kid (Key ID) of the JWE.¶

• request_uri¶

  • OPTIONAL. URL where Request Object value can be retrieved from, as specified in Section 6.2.¶

When request or request_uri parameters are NOT present, registration or registration_uri parameters MUST be present in the request. When request or request_uri parameters are present, registration or registration_uri parameters MUST be included in either of those parameters.¶

Since it is an Implicit Flow response, nonce Claim MUST be present.¶

Other parameters MAY be sent. Note that all Claims are returned in the ID Token.¶

The entire URL MUST NOT exceed 2048 ASCII characters.¶

The following is a non-normative example HTTP 302 redirect response by the RP, which triggers the User Agent to make an Authentication Request to the Self-Issued OP (with line wraps within values for display purposes only):¶

  HTTP/1.1 302 Found
  Location: openid://?
    response_type=id_token
    &client_id=https%3A%2F%2Fclient.example.org%2Fcb
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
    &scope=openid%20profile
    &state=af0ifjsldkj
    &nonce=n-0S6_WzA2Mj
    &registration=%7B%22logo_uri%22%3A%22https%3A%2F%2F
      client.example.org%2Flogo.png%22%7D

7.2. Self-Issued OpenID Provider Response

Self-Issued OpenID Provider Response is returned when Self-Issued OP supports all of the Relying Party Registration metadata values received from the Relying Party in the registration parameter. If even one of the Relying Party Registration Metadata Values is not supported, Self-Issued OP MUST return an error according to Section 4.4.¶

This extension defines the following claims to be included in the ID token for use in Self-Issued OpenID Provider Responses:¶

• sub¶

  • REQUIRED. Subject identifier value, represented by a URI. When sub type is jkt, the value is the base64url encoded representation of the thumbprint of the key in the sub_jwk Claim. When sub type is did, the value is a decentralized identifier. The thumbprint value is computed as the SHA-256 hash of the octets of the UTF-8 representation of a JWK constructed containing only the REQUIRED members to represent the key, with the member names sorted into lexicographic order, and with no white space or line breaks. For instance, when the kty value is RSA, the member names e, kty, and n are the ones present in the constructed JWK used in the thumbprint computation and appear in that order; when the kty value is EC, the member names crv, kty, x, and y are present in that order. Note that this thumbprint calculation is the same as that defined in the JWK Thumbprint [RFC7638] specification.¶

• sub_jwk¶

  • REQUIRED. a secure binding between the subject of the verifiable credential and the subject identifier (and related keys) of the holder who creates the presentation. When subr type is jkt, the key is a bare key in JWK [JWK] format (not an X.509 certificate value). When sub type is did, subjwk MUST contain a kid that is a DID URL referring to the verification method in the Self-Issued OP's DID Document that can be used to verify the JWS of the idtoken directly or indirectly. The sub_jwk value is a JSON object. Use of the sub_jwk Claim is NOT RECOMMENDED when the OP is not Self-Issued.¶

Whether the Self-Issued OP is a mobile client or a web client, response is the same as the normal Implicit Flow response with the following refinements. Since it is an Implicit Flow response, the response parameters will be returned in the URL fragment component, unless a different Response Mode was specified.¶

1. The iss (issuer) Claim Value is https://self-issued.me/v2.¶

2. The sub (subject) Claim value is either the base64url encoded representation of the thumbprint of the key in the sub_jwk Claim or a decentralized identifier.¶

3. When sub Claim value is the base64url encoded representation of the thumbprint, a sub_jwk Claim is present, with its value being the public key used to check the signature of the ID Token.¶

4. No Access Token is returned for accessing a UserInfo Endpoint, so all Claims returned MUST be in the ID Token.¶

7.3. Verifiable Presentation Support

Self-Issued OP and the RP that wish to support request and presentation of Verifiable Presentations MUST be compliant with OpenID Connect for Verifiable Presentations [OIDC4VP] and W3C Verifiable Credentials Specification [VC-DATA-MODEL].¶

Verifiable Presentation is a tamper-evident presentation encoded in such a way that authorship of the data can be trusted after a process of cryptographic verification. Certain types of verifiable presentations might contain data that is synthesized from, but do not contain, the original verifiable credentials (for example, zero-knowledge proofs). [VC-DATA-MODEL]¶

See [OIDC4VP] on how to support multiple credential formats such as JWT and Linked Data Proofs.¶

7.4. Self-Issued ID Token Validation

To validate the ID Token received, the RP MUST do the following:¶

1. The Relying Party (RP) MUST validate that the value of the iss (issuer) Claim is https://self-isued.me. If iss contains a different value, the ID Token is not Self-Issued, and instead it MUST be validated according to Section 3.1.3.¶

2. The RP MUST validate that the aud (audience) Claim contains the value of the redirect_uri that the RP sent in the Authentication Request as an audience.¶

3. The RP MUST validate the signature of the ID Token. When sub type isjkt, validation is done according to JWS [JWS] using the algorithm specified in the alg Header Parameter of the JOSE Header, using the key in the sub_jwk Claim. When sub type isdid, validation is done using the key derived as a result of DID Resolution as defined in [DID-CORE]. The key is a bare key in JWK format (not an X.509 certificate value) when sub type isjkt or may be another key format when sub type is did.¶

4. Default alg value is RS256. It MAY also be ES256, ES256K or EdDSA.¶

5. The RP MUST validate thesub value. When sub type isjkt, the RP MUST validate that the sub claim value equals to the base64url encoded representation of the thumbprint of the key in the sub_jwk Claim, as specified in Section 6 of [OpenID]. When sub type is did, the RP MUST validate that sub claim value equals to the key in the verification method property of the DID Document. Since DID Document can contain mulitple keys, the validation MUST be performed against the key identified by the kid in the header. DID Document MUST be obtained by resolving decentralized identifier included in the sub claim.¶

6. The current time MUST be before the time represented by the exp Claim (possibly allowing for some small leeway to account for clock skew). The iat Claim can be used to reject tokens that were issued too far away from the current time, limiting the amount of time that nonces need to be stored to prevent attacks. The acceptable range is RP specific.¶

7. The RP MUST validate that a nonce Claim is present and is the same value as the one that was sent in the Authentication Request. The Client SHOULD check the nonce value for replay attacks. The precise method for detecting replay attacks is RP specific.¶

The following is a non-normative example of a base64url decoded Self-Issued ID Token (with line wraps within values for display purposes only):¶

  {
   "iss": "https://self-issued.me/v2",
   "sub": "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs",
   "aud": "https://client.example.org/cb",
   "nonce": "n-0S6_WzA2Mj",
   "exp": 1311281970,
   "iat": 1311280970,
   "sub_jwk": {
     "kty":"RSA",
     "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx
     4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs
     tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2
     QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI
     SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb
     w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
     "e":"AQAB"
    }
　}

The following is a non-normative example of an ID token containing a verfiable presentation (with line wraps within values for display purposes only):¶

  {
   "iss": "https://self-issued.me/v2",
   "sub": "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs",
   "aud": "https://client.example.org/cb",
   "nonce": "n-0S6_WzA2Mj",
   "exp": 1311281970,
   "iat": 1311280970,
   "sub_jwk": {
     "kty":"RSA",
     "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx
     4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs
     tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2
     QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI
     SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb
     w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
     "e":"AQAB"
    },
    "verifiable_presentations":[
      {
         "format":"vp_jwt",
         "presentation":"ewogICAgImlzcyI6Imh0dHBzOi8vYm9vay5pdHNvdXJ3ZWIub...IH0="
      }
   ],
　}

Note: Further processing steps are required if the authentication response contains verifiable presentations - see [OIDC4VP].¶

7.5. Security Considerations

7.6. Privacy Considerations