Address client_id_scheme problems (fixes #124)

[awoie]

This PR is still WIP.

This PR removes client_id_scheme by trying to crystalize the common features of existing client ID schemes (authentication, and validating redirect/response_uris) on top of existing client metadata retrieval mechanisms such as DCR, OpenID Federation or the new client_metadata parameter.

I figured that an activity diagram might help framing the discussion on Thursday's DCP WG call (thanks @javereec for this idea).

NOTE: a wallet does not have to support each method. I will make this more clear.

[javereec]

Below is a diagram to potentially facilitate the discussion on how to verify these requests.

flowchart TD
    
    RS{Request Signed?} -->|Yes| URI{Client ID URI?}

    URI --> |Yes| X509
    URI --> |No| PRE

    X509{x5c,x5t header?} --> |Yes| X509A[X.509 Certificates]
    X509{x5c,x5t header?} --> |No| FED
    
    FED{Client ID URL?} --> |Yes| FEDA[OpenID Federation]
    FED{Client ID URL?} --> |No| DID
    
    DID{Client ID DID?} --> |Yes| DIDA[DID Resolution]
    DID{Client ID DID?} --> |No| PRE

    RS{Request Signed?} -->|No| PRE
    PRE{Client ID Pre-Registered?} --> |No| POL[Redirect URI = Client ID<br>Wallet Policy decision]
    PRE{Client ID Pre-Registered?} --> |Yes| PREA[Pre Registered <br>RFC6749]

Loading

[danielfett]

For completeness, can you please expand the X.509 Certificates item?

[tlodderstedt]

@awoie can you please remove all occurrences of client_id_scheme? It feels like not all parts of the processing rules are adopted yet.

[danielfett]

As discussed on the call, the PR in its current form does not address how to process a request (if more than one method is supported). Clearly defined processing rules that ensure that a request can never be modified by a third party such that the signature verification can be skipped or a signature can be replaced are the core of the problem in my opinion.

[awoie]

As discussed on the call, the PR in its current form does not address how to process a request (if more than one method is supported). Clearly defined processing rules that ensure that a request can never be modified by a third party such that the signature verification can be skipped or a signature can be replaced are the core of the problem in my opinion.

@danielfett Could you provide an example of a downgrade attack based on the existing language?

For signed requests, the request parameters are integrity protected:

• Signed by X.509 certificates (included in request object) with SAN(s) that match the client_id and ensure linkage to the redirect_uri or response_uri.
• Signed by DIDs that match the client_id, though there's no linkage to the redirect_uri or response_uri (which I believe is a potential issue).
• Signed by cnf of Verifier attestations, attested by a trusted entity (such as an attestation issuer), which may include linkage to the redirect_uri or response_uri.
• Signed by key obtained from OpenID Federation, where client metadata—including redirect_uris and jwks containing the verification key—is fetched from an authoritative source (via entity statements). The require_signed_request_object parameter could be set to enforce signing although probably not needed since OpenID Fed requires signing.
• Pre-registered clients that provided their jwks and redirect_uri or response_uri during registration. Here, too, require_signed_request_object could be set to enforce signing.

For unsigned requests, the request parameters are either fetched from an authoritative source (pre-registered, perhaps with require_signed_request_object not enabled), or the client_id must match the redirect_uri or response_uri for simpler requests. In the latter case, a downgrade attack wouldn't make sense. To downgrade signed to unsigned, we could even require that for these in-band registrations (DID, X509, verifier attestation), client_id != redirect_uri.

Browser API is a different conversation.

A wallet would only enforce one of these methods if they were considered to be secure or even equally secure. The same applies to the verifier.

[nemqe]

Just a note regarding DIDs and the comment about linkage to redirect_uri/response_uri.

Signed by DIDs that match the client_id, though there's no linkage to the redirect_uri or response_uri (which I believe is a potential issue).

For this I think it could be a mandate that linkage credentials need to be used (linked domains) so you have a direct link between the did-diddoc-domain.

[awoie]

Just a note regarding DIDs and the comment about linkage to redirect_uri/response_uri.

Signed by DIDs that match the client_id, though there's no linkage to the redirect_uri or response_uri (which I believe is a potential issue).

For this I think it could be a mandate that linkage credentials need to be used (linked domains) so you have a direct link between the did-diddoc-domain.

IMO, it is also questionable if this linkage is required for in-band request object authentication, i.e., where the client_id is authenticated by things included in the request object. Because if the request object is trusted to originate from the client_id, the redirect_uri/response_uri might NOT have to be linked to other things such as X.509 SAN(s), DID linked domain, or redirect_uris in the verifier attestation but this is separate discussion.

[awoie]

Perhaps a better visualization of the PR which shows that all of the request object authentication methods don't have to be applied in a particular order. The diagram below does not include redirect/response_uri validation yet but the bullet points above show how this can be done. Perhaps in-band registration is the better term for x.509/DID/verifier attestation where the request object is authenticated against the client ID using parameters that are provided in band and additional client metadata is typically provided using the client_metadata parameter.

flowchart TD
    start --> pre
    start --> fed
    start --> inband
    
    pre[Pre-registered] -->|client_id is pre-registered| prev
    fed[OpenID Federation] -->|client_id is OpenID Federation Entity ID,<br>i.e., URI with OpenID Fed well-known| fedv[Verify signature using<br>resolved OpenID Fed metadata] --> con[Continue]
        
    inband[Inband registration] -->IS{is request signed?}-->|No| usv
    IS -->|Yes|II{client_id matches<br>redirect/response_uri?} -->|Yes| rej[Reject]
    II -->|No| inbandss[Determine verification key]
    inbandss -->|x5c, x5t in JAR| x509v[Verify signature using<br>corresponding certificate] --> con
    inbandss -->|jwt/verifier attestation in JAR| vav[Verify signature using<br>cnf claim] --> con
    inbandss -->|client_id is a DID| didv[Verify signature<br>using key from DID Document] --> con

    prev[Fetch client metadata] --> B{Is request<br>signed?} -->|Yes| C[Verify signature using<br>jwks from client metadata] --> con
    B -->|No| D{Is require<br>request object<br>signing set?} -->|Yes| con
    D -->|No| rej

    usv{client_id matches<br>redirect/response_uri?} -->|Yes| con

Loading

[javereec]

@awoie regarding the diagram.

When the request is not signed and client_id = redirect_uri/response_uri I think we must continue, not reject.

When a request comes in, I think we can be more clear about what we need to evaluate first. Is this the client_id or wether the request is signed or not. The entry point is not quite clear.

[awoie]

@awoie regarding the diagram.

When the request is not signed and client_id = redirect_uri/response_uri I think we must continue, not reject.

Indeed, that was just a bug in the diagram. I fixed it.

[awoie]

@awoie regarding the diagram.

When a request comes in, I think we can be more clear about what we need to evaluate first. Is this the client_id or wether the request is signed or not. The entry point is not quite clear.

IMO, this is a wallet policy since it is also a wallet policy which methods to support at all. It should make no difference if we prescribed a specific order or not unless I'm missing something.

[selfissued]

Approved with editorial suggestions.

[nemqe]

Note that the Wallet determines whether the Client is pre-registered.

out of curiosity, do we need this note, isn't it implied?

[awoie]

It is implied but I remember we had a discussion about this topic, so I kept that language for clarity.

[danielfett]

If enabled together, how does the wallet distinguish between a pre-registered client https://example.com from one authenticating with an x509 cert for that URL?

[awoie]

We can add that wallets and wallet providers MUST implement the OAuth Security BCP that suggests to use random client IDs where there is no clash possible.

[martijnharing]

It should be stated that this requirement only applies if the client_id is present.

[jogu]

I'm not convinced this matters, isn't client_id mandatory in all cases where redirect_uri or response_uri can be used? (i.e. I think you can only omit client_id in unsigned browser API requests, where redirect_uri and response_uri aren't permitted to be used).

[martijnharing]

It states that the following mechanisms MAY be used, but the mechanisms themselves contain MUST. What does this mean exactly, some options:

1. It's optional to use these mechanisms even when the conditions are applicable, but if the mechanism is used by the wallet, the requirements have to be followed.
2. When the conditions are applicable the mechanism MUST be used, otherwise an error must be given.
3. When the conditions are applicable the mechanism MUST be used, otherwise the client is considered not authenticated, with the consequences being out of scope.

Something else?

[awoie]

The PR aims to allow for Option 1. I agree that the combination of MAY and MUST is not clear.

[danielfett]

What happens if the request has contradicting properties, e.g., fulfills the rules in X.509 and Federation at the same time?

[martijnharing]

X.509 certificates should not be required to contain a SAN. It's possible to authenticate a client, without that authentication being bound to a SAN. (as an example, this is also what is used for in-person relying party authentication)

In case of the browser api, the requirement that the client_id must match the response_uri is not applicable and this should be stated as such.

[awoie]

I agree with this. It is questionable what the value add of SAN is in this context if the root is trusted.

[awoie]

I believe client_id must match response_uri should not be a requirement. It might be useful though that redirect_uri/response_uri (or via FQDN) is included in the SAN in some way but it shouldn't be required. Since Browser API doesn't have redirect_uri/response_uri, this wouldn't apply to browser API.

[danielfett]

How does the Wallet identify if the client_id is an Entity Identifier?

[awoie]

If the wallet supports OpenID Federation, the wallet would check if the client_id is a HTTPS URI and try to fetch OpenID Federation well-known.

[danielfett]

This is completely insufficient. Why do we allow using more than one method if it is seemingly insecure to do so?

[awoie]

Perhaps the language can be improved but a Client would not support options and set parameters in the request if they were not equally secure.

[danielfett]

What are the constraints for those new rules in order to safely work with the rules defined above?

[awoie]

Good point, I would assume they should do 1 or 2 things like the other in-band client registration methods do:

1. authenticate the request that it was originated by the client_id; this is typically done by verifying the signature on the signed request; for browser API, this might be based on origin.
2. optionally check if the redirect_uri/response_uri is linked to the client_id; but this requirement is kind of not consistently achieved in the current version of the spec either, so I would assume it is optional;

[danielfett]

Is this method always enabled?

[awoie]

No, it is not. We need to adapt the language, also @martijnharing had a similar comment here #237 (comment)

[danielfett]

As above, how is a pre-registered client did:bla:blub distinguished from one using did:bla:blub as a did?

[awoie]

A pre-registered client would not include a DID for the kid value.

Independently, if a wallet supports both DID and pre-registered clients, the wallet would check their preferred way to authenticate the request first. This might be DID-based or based on pre-registered client metadata.

[danielfett]

To reiterate what I said on the call, the current PR does not ensure that

• the verifier's expectation on what was actually checked when it receives a presentation with its client id in the "aud" claim matches what the wallet checked, and
• two implementations of this draft that, for example, allow x509 and pre-registered clients, behave the same way and do the same checks.

This is an extremely critical part of the spec and therefore we need to ensure to get it right.

[awoie]

To reiterate what I said on the call, the current PR does not ensure that

• the verifier's expectation on what was actually checked when it receives a presentation with its client id in the "aud" claim matches what the wallet checked, and

This can only be guaranteed if the public verification key is included in the VP, e.g., aud=<jwk-thumbprint>:<client_id>. This would also mitigate the concern that even within an existing client ID scheme, e.g., x509, verifier attestation etc., and if the client ID scheme was included in the response, the verifier does not know which credential (certificate, or verifier attestation etc.) was used to authenticate the client ID if a verifier supports multiple in-band client credentials of the same type but adhering to different security levels or ecosystem requirements. Note that it is possible that a verifier obtains multiple credentials for the same client ID.

• two implementations of this draft that, for example, allow x509 and pre-registered clients, behave the same way and do the same checks.

This is a performance concern, not a security concern, if we consider my comment above. We can suggest an order in the PR to guide wallets.

[awoie]

This is a performance concern, not a security concern, if we consider my comment above. We can suggest an order in the PR to guide wallets.

For example, we could suggest the following order if performance is a concern.

If the request is signed:

• Public keys in the client_metadata parameter MUST NOT be used to verify the signature of the signed request.

• Pre-registered Clients:

  • Wallets or Wallet Providers must implement the security OAuth Best Current Practice (BCP) that ensures random client IDs for pre-registered clients.
  • If the wallet supports pre-registered clients, and the client ID is pre-registered, retrieve the public key from the client metadata to verify the signature of the request.

• x509 Certificate:

  • If an x5c, x5t, or x5t#S256 JWT header is present, validate the X.509 certificate chain and resolve the public key from the corresponding leaf certificate to verify the signed request.

• Verifier Attestations:

  • If the wallet supports verifier attestations and if the signed request contains a verifier attestation in the JWT header indicated by the typ JWT header , verify the verifier attestation is trusted and resolve the public key from the cnf claim of the verifier attestation to verify the signed request.

• DID Document:

  • If the wallet supports Decentralized Identifiers (DIDs), and the client ID is a DID indicated by the client ID starting with the did: URI scheme, attempt to resolve the public key using the DID resolution process to verify the signature of the signed request.

• OpenID Federation:

  • If the wallet supports OpenID Federation, and the client ID is a HTTPS URI, retrieve the public key from the resolved OpenID Federation metadata to verify the signature of the signed request.

• Ecosystem-specific Support:

  • Other mechanisms that are out of scope of this specification MAY be used to obtain a public key to verify the signature of the request object, if the wallet can verify that public key is authoritative for the provided client ID protected by the signed request.

• Verification Failure:

  • If the signature of the signed request cannot be verified, the request MUST be rejected.

If the request is not signed:

• Pre-registered Clients:

  • If the wallet supports pre-registered clients, and the client ID is pre-registered, ensure that require_request_object_signing is set to false or omitted from the client metadata. The request MUST be rejected if require_request_object_signing is true.

• Client ID is Redirect URI:

  • If the request was not received via the Digital Credentials API as defined in Appendix A, verify the client_id equals redirect_uri or response_uri. Otherwise, the request MUST be rejected.

If the request was received via the browser API:

• Check that origin received via the platform matches one of the expected_origins. Otherwise, the request MUST be rejected. (this probably does not have to go into the section since it is covered in Appendix A).

[nemqe]

small typo

Suggested change

* Verifier Attestations: If supported by the Walletm the request is signed, and the signed request contains a `jwt` JWT header that is a Verifier Attestation JWT, the Wallet MUST use the public key in the `cnf` claim in the Verifier Attestation JWT to verify the signatuer of the signed request. This serves as proof of possession of this key. Additionally, the `client_id` MUST equal the `sub` claim value in the Verifier Attestation JWT. The Wallet MUST validate the signature on the Verifier Attestation JWT. The `iss` claim value of the Verifier Attestation JWT MUST identify a party the Wallet trusts for issuing Verifier Attestation JWTs. If the issuer of the Verifier Attestation JWT includes a `redirect_uris` claim in the Verifier Attestation, the Wallet MUST verify that the `redirect_uri` or `response_uri` request parameter value exactly matches one of the `redirect_uris` array values. If either of the checks fail, the Wallet MUST reject the request, otherwise processing continues.

* Verifier Attestations: If supported by the Wallet, the request is signed, and the signed request contains a `jwt` JWT header that is a Verifier Attestation JWT, the Wallet MUST use the public key in the `cnf` claim in the Verifier Attestation JWT to verify the signatuer of the signed request. This serves as proof of possession of this key. Additionally, the `client_id` MUST equal the `sub` claim value in the Verifier Attestation JWT. The Wallet MUST validate the signature on the Verifier Attestation JWT. The `iss` claim value of the Verifier Attestation JWT MUST identify a party the Wallet trusts for issuing Verifier Attestation JWTs. If the issuer of the Verifier Attestation JWT includes a `redirect_uris` claim in the Verifier Attestation, the Wallet MUST verify that the `redirect_uri` or `response_uri` request parameter value exactly matches one of the `redirect_uris` array values. If either of the checks fail, the Wallet MUST reject the request, otherwise processing continues.

[nemqe]

This section confuses me a bit, but I am easily confused. Seems a bit like "can you repeat to me what I said so I am sure you understood it".

Am a getting it right? I might be missing a smallish example of possible vectors and surfaces that we are trying to mitigate i.e. the reasoning behind this "proof of computation".

[jogu]

I think we've achieved consensus around #266 so I think this PR is no longer needed and hence closing it to clean up the PR list - many thanks go to Oliver/Tobias/etc for help moving the conversation along!