12.1.4. Relying Party Endpoints¶

The Relying Party MUST expose a trust endpoint adhering to the OpenID Federation 1.0 Wallet Architecture specification, facilitating the Relying Party's identity and metadata distribution. In addition, in case the Relying Party supports proximity presentation, it MUST expose a set of endpoints for handling the lifecycle of Relying Party Instances (e.g., by providing nonce generation, hardware key registration, integrity validation, and Access Certificate issuance); their specific implementation details are left to the Relying Party's discretion.

12.1.4.1. Relying Party Federation Endpoint¶

The Relying Party MUST provide its Entity Configuration through the /.well-known/openid-federation endpoint, according to Section Entity Configuration. Technical details are provided in Section Entity Configuration of Relying Parties.

12.1.4.2. Relying Party Nonce Endpoint¶

The Relying Party Nonce Endpoint allows the Relying Party Instance to request a cryptographic nonce from the Relying Party Backend. The nonce serves as an unpredictable, single-use challenge to ensure freshness and prevent replay attacks.

Further details on the Nonce Request and Response are provided in the Mobile Application Nonce Request and Mobile Application Nonce Request Sections, respectively.

12.1.4.3. Relying Party Instance Initialization Endpoint¶

The Relying Party Instance Initialization Endpoint allows for the initialization of Relying Party Instances, consisting in the registration of a pair of long-lived, securely stored Cryptographic Hardware Keys.

Further details on the Relying Party Instance Initialization Request and Response are provided in the Mobile Application Instance Initialization Request and Mobile Application Instance Initialization Response Sections, respectively.

12.1.4.4. Relying Party Key Binding Endpoint¶

The Relying Party Key Binding Endpoint enables Relying Party Instances to bind the newly created pair of keys, which will be associated with an Access Certificate, to the Relying Party Instance, by relying on a proof of possession of the Cryptographic Hardware Keys generated during the Mobile Application Instance Initialization phase. Before completing the process, the Relying Party Backend also needs to verify the integrity of the Relying Party Instance.

12.1.4.4.1. Relying Party Key Binding Request¶

Further details on the Relying Party Key Binding Request are provided in the Mobile Application Key Binding Request section.

The typ header of the Integrity Request JWT assumes the value rp-kb+jwt.

12.1.4.4.2. Relying Party Key Binding Response¶

Upon a successful request, the Relying Party Backend provides an HTTP Response with a 204 No Content status code.

Below is a non-normative example of a Key Binding Request Response.

HTTP/1.1 204 No content

If any errors occur during the process, an error response is returned. Further details on the error response are provided in the Mobile Application Key Binding Error Response section.

12.1.4.5. Relying Party Access Certificate Endpoint¶

The Relying Party Access Certificate Endpoint enables Relying Party Instances to obtain an Access Certificate.

12.1.4.5.1. Relying Party Access Certificate Request¶

The Access Certificate Request uses the HTTP POST method with Content-Type set to application/json.

The request includes the following body parameter:

Parameter	Description	Reference
csr	The CSR generated by the Relying Party Instance, encoded in the `base64url` format as defined in RFC 2511.

Below is a non-normative example of an Access Certificate Request.

POST /access-certificate HTTP/1.1
Host: relying-party.example.org
Content-Type: application/json

{
  "csr": "MIIBvzCCAa..."
}

12.1.4.5.2. Relying Party Access Certificate Response¶

Upon a successful request, the Relying Party Access Certificate Endpoint provides an HTTP Response with a 200 OK status code and the Access Certificate. The Access Certificate Response, which uses application/json as the Content-Type, includes the following body parameters:

Parameter	Description	Reference
access_certificate	The Access Certificate generated by the CSR.	This specification.

Below is a non-normative example of an Access Certificate Response.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_certificate": "hajdnhaghSDGns..."
}

If any errors occur, the Relying Party Access Certificate Endpoint returns an error response. The response uses application/json as the content type and includes the following parameters:

error. The error code.

error_description. Text in human-readable form providing further details to clarify the nature of the error encountered.

Below is a non-normative example of an Access Certificate Error Response.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "error": "invalid_request",
    "error_description": "The public key in the CSR is different from the one associated with the Cryptographic Hardware Keys."
}

The following table lists HTTP Status Codes and related error codes that MUST be supported for the error response, unless otherwise specified:

HTTP Status Code	Error Code	Description
`400 Bad Request`	`bad_request`	The request is malformed, missing required parameters (e.g., header parameters or integrity assertion), or includes invalid and unknown parameters.
`403 Forbidden`	`invalid_request`	The public key in the CSR does not match the public key associated with the Cryptographic Hardware Keys.
`500 Internal Server Error`	`server_error`	The request cannot be fulfilled because the Endpoint encountered an internal problem.
`503 Service Unavailable`	`temporarily_unavailable`	The request cannot be fulfilled because the Endpoint is temporarily unavailable (e.g., due to maintenance or overload).

12.1.4.6. Relying Party Erasure Endpoint¶

The Erasure Endpoint, which is described in Metadata for openid_credential_verifier, allows Wallet Instances to request deletion of attributes presented to the Relying Party. It MUST be authenticated, i.e., the Relying Party MUST request User authentication before proceeding with the attribute deletion.

12.1.4.6.1. Erasure Request¶

The Erasure Request MUST be a GET request to the Erasure Endpoint. The Wallet Instance MUST also support a call back mechanism which enables the User-Agent to notify the Wallet Instance (and thus the User) once the Erasure Response is returned.

Below is a non-normative example of an Erasure Request where the call back URL is passed as a query parameter.

GET /erasure-endpoint?callback_url=https://wallet-instance/erasure_response HTTP/1.1
Host: relying-party.example.org

12.1.4.6.2. Erasure Response¶

If the deletion of all attributes bound to the User have been successful, the Erasure Response MUST return a 204 HTTP status code.

If instead the attributes deletion procedure fails due any circumstances, the Relying Party MUST return an error response with application/json as the content type and MUST include the following parameters:

error: The error code.

error_description: Text in human-readable form providing further details to clarify the nature of the error encountered.

The following table lists the HTTP Status Codes and related error codes that MUST be supported for the error response:

Status Code	Error Code	Description
`400 Bad Request`	`bad_request`	The request is malformed, missing required parameters (e.g., header parameters or integrity assertion), or includes invalid and unknown parameters.
`401 Unauthorized`	`unauthorized`	The request could not be carried fulfilled due to invalid authentication by the User.
`500 Internal Server Error`	`server_error`	The request cannot be fulfilled because the Erasure Endpoint encountered an internal problem. (RFC 6749#section-4.1.2.1).
`503 Service Unavailable`	`temporarily_unavailable`	The request cannot be fulfilled because the Erasure Endpoint is temporarily unavailable (e.g., due to maintenance or overload). (RFC 6749#section-4.1.2.1).

The following is an example of an error response from Erasure Endpoint:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
 "error": "server_error",
 "error_description": "The request cannot be fulfilled due to an internal server error."
}

Upon receiving an error response, the Wallet Instance which made the Erasure Request MUST inform the User of the error condition in an appropriate manner.