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.

Relying Party Federation Endpoint¶

Entity Configuration of Relying Parties¶

According to Section Configuration of the Federation, as a Federation Entity, the Relying Party is required to maintain a well-known endpoint that hosts its Entity Configuration. The Entity Configuration of Relying Parties MUST contain the parameters defined in the Sections Entity Configuration Leaves and Intermediates and Entity Configurations Common Parameters.

The Relying Parties MUST provide the following metadata types:

federation_entity

openid_credential_verifier

The federation_entity metadata MUST contain the claims as defined in Section Metadata of federation_entity Leaves.

Metadata for openid_credential_verifier¶

The openid_credential_verifier metadata MUST contain the following parameters.

Claim	Description
client_id	It MUST contain an HTTPS URL that uniquely identifies the RP. See RFC 7591#section-3.2.1 and OpenID Connect Dynamic Client Registration 1.0 Section 3.2.
client_name	Human-readable string name of the RP. See RFC 7591#section-2.
application_type	String indicating the type of application. It MUST be set to "web" value. See OpenID Connect Dynamic Client Registration 1.0 Section 2.
request_uris	JSON Array of request_uri values that are pre-registered by the RP. These URLs MUST use the https scheme. See OpenID Connect Dynamic Client Registration 1.0 Section 2.
response_uris	JSON Array of response URI strings to which the Wallet Instance MUST send the Authorization Response using an HTTP POST request as defined by the Response Mode `direct_post` and `direct_post.jwt` (see OpenID4VP Draft 20 Sections 6.2 and 6.3).
authorization_signed_response_alg	String representing the signing [RFC 7515] alg algorithm that MUST be used for signing authorization responses. The algorithm "none" MUST NOT be used. See JARM.
authorization_encrypted_response_alg	Algorithm used to encrypt the authorization response. It specifies to the Wallet Instance the asymmetric encryption algorithm. See JARM.
authorization_encrypted_response_enc	Encryption algorithm used for the authorization response. It specifies to the Wallet Instance the symmetric encryption algorithm. See JARM.
vp_formats	JSON object defining the formats and proof types of Verifiable Presentations and Verifiable Credentials the RP supports. It consists of a list of name/value pairs, where each name uniquely identifies a supported type. The RP MUST support at least "dc+sd-jwt". The value associated with each name/value pair MUST be a JSON object "sd-jwt_alg_values" that MUST contain a JSON array containing identifiers of cryptographic algorithms the RP supports for protection of a SD-JWT. The alg JOSE header (as defined in RFC 7515) of the presented SD-JWT MUST match one of the array values. See also OpenID4VP Draft 20 Section 9.1.
jwks	JSON Web Key Set document, passed by value, containing the protocol specific keys for the Relying Party. See JARM Section 3, OID-FED Draft 41 Section 5.2.1 and JWK.
erasure_endpoint	[CONDITIONAL] JSON String that represents the URI to which the Wallet Instance can request deletion of Users’ attributes. This URL MUST use the https scheme. This endpoint MUST be present whenever the Relying Parties requested attributes that can uniquely identify Users such as the tax_id_code claim of the PID.

Note

The parameters response_uris and erasure_endpoint are introduced in this specification.

Example of a Relying Party Entity Configuration¶

Below a non-normative example of the request made by the Wallet Instance to the openid-federation well-known endpoint to obtain the Relying Party Entity Configuration:

GET /.well-known/openid-federation HTTP/1.1
HOST: relying-party.example.org

Below is a non-normative response example:

{
    "iat": 1718207217,
    "exp": 1749743216,
    "iss": "https://relying-party.example.org",
    "sub": "https://relying-party.example.org",
    "authority_hints": [
        "https://trust-anchor.example.org"
    ],
    "jwks": {
        "keys": [
            {
                "kid": "FANFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs",
                "kty": "EC",
                "crv": "P-256",
                "x": "jE2RpcQbFQxKpMqehahgZv6smmXD0i/LTP2QRzMADk4",
                "y": "qkMx5iqt5PhPu5tfctS6HsP+FmLgrxfrzUV2GwMQuh8"
            }
        ]
    },
    "metadata": {
        "federation_entity": {
            "homepage_uri": "https://relying-party.example.org",
            "organization_name": "Organization Name",
            "contacts": [
                "informazioni@example.it",
                "protocollo@pec.example.it"
            ],
            "tos_uri": "https://relying-party.example.org/public/info_policy.html",
            "policy_uri": "https://relying-party.example.org/public/privacy_policy.html",
            "logo_uri": "https://relying-party.example.org/public/logo.svg"
        },
        "openid_credential_verifier": {
            "application_type": "web",
            "client_id": "https://relying-party.example.org",
            "client_name": "Organization Name",
            "contacts": [
                "informazioni@example.it",
                "protocollo@pec.example.it"
            ],
            "request_uris": [
                "https://relying-party.example.org/request_uri"
            ],
            "response_uris": [
                "https://relying-party.example.org/response_uri"
            ],
            "redirect_uris": [
                "https://relying-party.example.org/cb"
            ],
            "authorization_signed_response_alg": "ES256",
            "vp_formats": {
                "dc+sd-jwt": {
                    "sd-jwt_alg_values": [
                        "ES256",
                        "ES384",
                        "ES512"
                    ]
                }
            },
            "jwks": {
                "keys": [
                    {
                        "kid": "f10aca0992694b3581f6f699bfc8a2c6cc687725",
                        "kty": "EC",
                        "crv": "P-256",
                        "x": "jE2RpcQbFQxKpMqehahgZv6smmXD0i/LTP2QRzMADk4",
                        "y": "qkMx5iqt5PhPu5tfctS6HsP+FmLgrxfrzUV2GwMQuh8"
                    }
                ]
            }
        }
    }
}

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 Response sections, respectively.

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.

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.

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.

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.

Relying Party Access Certificate Endpoint¶

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

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..."
}

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).

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.

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

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.