Set up the Customer Edge
This section explains how to set up the customer edge network. The specifics of configuring different edge networks are out of the scope of this document. For more information, see the custom domains documentation.
The customer’s edge domain must match the registered custom domain. If mTLS endpoint aliases are enabled, the customer edge must also accept requests on the subdomain used by the mTLS aliases. All requests that arrive at the mTLS subdomain should request a client TLS certificate and verify that the certificate is registered for use. For more information, see Verify the client certificate.
The mTLS handshake occurs before the edge infrastructure can determine the requested path. Once the TLS session is established, the customer may wish to inspect the path and only forward requests for the following endpoints:
/oauth/token/oauth/par/userinfo
If your installation aims for FAPI compliance, additional requirements related to TLS are placed on your edge network. For more information, see the FAPI1 Baseline, FAPI1 Advanced, and FAPI2 Baseline specifications.
Verify the client certificate
The customer edge network performs validations that depend on the expected type of the client certificate. To avoid common security problems and pitfalls, use a well-vetted certificate validation library when possible. When the client certificate fails validation, the expected behavior is dependent on the installation and outside of the scope of this document.
CA-signed certificates
When a certificate is signed by a certificate authority, the trust chain of the certificate must be verified, including the root certificate. The certificate may also be compared against an allow or deny list to ensure the certificate is registered and has not been revoked. Do not use a public certificate authority (e.g. LetsEncrypt) to sign your client certificates, as there is a risk of impersonating your clients.
Self-signed certificates
Self-signed certificates are not backed by a chain of trust so a certificate chain cannot be checked. Instead, the certificate thumbprint could be checked against a registered certificate database or forwarded directly to Auth0 to perform this check.
Forward the request
Once the certificate is verified, requests are forwarded along with several special headers from the customer to the same endpoint on the custom domain’s forwarding target at Auth0's edge network. The forwarded request must include the following headers:
The Custom Domain API key as the
cname-api-keyheader.The client certificate as the
client-certificateheader. Note: Since HTTP headers must be text, the certificate must be converted to a URL component encoded PEM. The header value is limited to 4096 bytes. Therefore, only the first certificate in the chain should be forwarded to Auth0.The client certificate CA verification status as the
client-certificate-ca-verifiedheader. Theclient-certificate-ca-verifiedheader can have the following values:SUCCESS: indicates that the client certificate is valid and has been verified by a certificate authority.
FAILED: indicates that the presented client certificate is valid, however the certificate's trust chain has NOT been verified by a certificate authority. In other words, it’s a self-signed certificate. May include an optional failure reason.
If your configuration supports only CA-signed certificates, you don't need to forward self-signed certificates to the Auth0 edge network, and you can terminate the request earlier. However, if your clients are configured to authenticate using self-signed certificates, Auth0 expects your network edge to send a client-certificate-ca-verified:FAILED header. Depending on this header value, Auth0 knows which client authentication method has been used and which client credentials need to be verified against.