Feat/docs 5414 dpop for enterprise connections

main/docs.json

@@ -849,7 +849,8 @@
                               "docs/authenticate/enterprise-connections/user-attribute-profile"
                             ]
                           },
-                          "docs/authenticate/enterprise-connections/private-key-jwt-client-auth"
+                          "docs/authenticate/enterprise-connections/private-key-jwt-client-auth",
+                          "docs/authenticate/enterprise-connections/enable-dpop-enterprise-connections"
                         ]
                       },
                       {

main/docs/authenticate/enterprise-connections/enable-dpop-enterprise-connections.mdx

@@ -0,0 +1,216 @@
+---
+description: Learn how to secure OIDC and Okta Enterprise connections with cryptographic token binding.
+title: Configure Enterprise Connections with Demonstrating Proof-of-Possession (DPoP)
+---
+
+<Warning>
+Enterprise Connections with Demonstrating Proof-of-Possession (DPoP) is currently in Early Access. By using this feature, you agree to the applicable Free Trial terms in [Okta’s Master Subscription Agreement](https://www.okta.com/legal). To learn more about product release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
+</Warning>
+
+Demonstrating Proof-of-Possession (DPoP) is an [OAuth 2.0 framework extension](https://datatracker.ietf.org/doc/draft-ietf-oauth-dpop/). To learn more about DPoP protocol and how it is used to sender constrain tokens, read [Demonstrating Proof-of-Possession (DPoP)](/docs/secure/sender-constraining). If you use Okta or OpenID Connect (OIDC) as your identity provider (IdP) and have configured them as an Enterprise connection in Auth0, then you can enable and configure DPoP to bind access tokens from your IdP to cryptographic keys. Using DPoP prevents token replay attacks and helps meet compliance requirements, such as [Interoperability Profiling for Secure Identity in the Enterprise (IPSIE) OIDC](https://openid.net/specs/ipsie-openid-connect-sl1-profile-1_0.html) Security Level 1 or [Financial-grade API (FAPI) 2.0](https://openid.net/specs/fapi-security-profile-2_0-final.html).
+
+To learn more about DPoP, read [Demonstrating Proof-of-Possession (DPoP)](/docs/secure/sender-constraining/demonstrating-proof-of-possession-dpop).
+
+<Card title="Before you start">
+
+Before you enable DPoP in Auth0:
+
+* Your upstream identity provider must support DPoP according to specification [RFC-9449](https://www.rfc-editor.org/rfc/rfc9449.html).
+* You must have an existing OIDC or Okta Enterprise connection or be able to create one. To learn how to create an Enterprise connection in Auth0, read [Enterprise Connections](/docs/authenticate/enterprise-connections).
+* The connection must not be configured to use [Token Vault](/docs/secure/call-apis-on-users-behalf/token-vault/configure-token-vault).
+* The connection should use Proof Key for Code Exchange (PKCE) [Authorization Code Flow + PKCE](docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce#authorization-code-flow-with-proof-key-for-code-exchange-pkce), which is enabled upstream if your identity provider supports PKCE.
+* The connection must be type `back_channel`.
+
+</Card>
+
+## Verify upstream IdP support
+
+Examine your IdP's OIDC discovery document to determine the DPoP support:
+
+```curl
+curl https://YOUR_IDP_DOMAIN/.well-known/openid-configuration
+```
+
+In the response, search for the DPoP supported value `dpop_signing_alg_values_supported`.
+
+**Example**
+
+```
+{
+  "dpop_signing_alg_values_supported": ["ES256", "Ed25519", "RS256"] 
+},
+```
+
+## Choose a signing algorithm
+
+Before you configure DPoP, choose a supported [signing algorithm](/docs/get-started/applications/signing-algorithms) from the options:
+
+| **Algorithm** | **Description** | **When to use** |
+| ------- | ------- | ------- |
+| ES256 | ECDSA with P-256 curve and SHA-256 | Your identity provider supports ES256. |
+| Ed25519 | EdDSA with Curve25519 | Your identity provider requires Ed25519 for compliance. |
+
+Choose ES256 unless your identity provider specifically requires Ed25519. Most identity providers support ES256, and it provides equivalent security with broad compatibility.
+
+## Enable DPoP
+
+Use the Management API to configure the DPoP JWT claim, `alg`, the signing algorithm for your Enterprise connection. To use the Management API, you need to get a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens).
+
+Make a `PATCH` request to the [Update a connection](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) endpoint with `dpop_signing_alg_values_supported` in the `options` object:
+
+```curl
+PATCH https://YOUR_DOMAIN/api/v2/connections/YOUR_CONNECTION_ID
+Content-Type: application/json
+Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN
+
+{
+  "options": {
+    "dpop_signing_alg": "ES256"
+  }
+}
+```
+<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
+ If you `PATCH` the `options` parameter, the entire `options` object is overridden. To avoid partial data or other issues, ensure all wanted properties are present when you PATCH `option`.
+</Callout>
+
+Replace the placeholder values:
+
+* **YOUR_DOMAIN**: Your Auth0 tenant domain. Example: `travel0.us.auth0.com`.
+* **YOUR_CONNECTION_ID**: The ID of your OIDC or Okta Enterprise connection.
+* **YOUR_MANAGEMENT_API_TOKEN**: A Management API token with `update:connections` scope
+
+## Test DPoP
+
+After enabling DPoP, test the configuration by initiating a login flow:
+
+1. Navigate to your application.
+2. Start the login flow using your configured Enterprise connection.
+3. Complete login with your upstream identity provider.
+4. [Check Auth0 logs](/docs/deploy-monitor/logs#logs) by navigating to [**Auth0 Dashboard > Monitoring > Logs**](https://manage.auth0.com/#/logs) for confirmation.
+
+A sucessful transaction in a log entry should be similar to:
+
+```
+{
+  "type": "s",
+  "description": "Success Login",
+  "details": {
+    "dpop_signing_alg": "ES256",
+    "idp_token_type": "dpop"
+   }
+}
+```
+
+Both values, `dpop_signing_alg` and `idp_token_type: "dpop"` confirm Auth0 sent a DPoP proof using the configured algorithm and your IdP issued DPoP-bound tokens.
+
+## Disable DPoP
+
+To disable DPoP, remove the `dpop_signing_alg` property from your connection configuration:
+
+```curl
+PATCH https://YOUR_DOMAIN/api/v2/connections/YOUR_CONNECTION_ID
+Content-Type: application/json
+Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN
+
+{
+  "options": {
+
+  }
+}
+```
+
+<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
+ If you `PATCH` the `options` parameter, the entire `options` object is overridden. To avoid partial data or other issues, ensure all wanted properties are present when you PATCH `option`.
+</Callout>
+
+## Troubleshoot
+
+Use the following recommendations to help diagnose and resolve issues with DPoP configuration for OIDC and Okta enterprise connections.
+
+### Check Auth0 configuration
+
+Before you start to troubleshoot, verify your DPoP configuration in Auth0.
+
+1. Navigate to [**Auth0 Dashboard > Authentication > Enterprise**](https://manage.auth0.com/#/connections/enterprise).
+2. Select your Okta or OIDC connection.
+3. Verify the connection is **not** configured with Token Vault by navigating to **Advanced Settings > Grant Types**. Make sure Token Vault is not selected.
+4. Use Management API's [Update a connection](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) endpoint to check the `dpop_signing_alg` setting:
+
+```curl
+GET https://YOUR_DOMAIN/api/v2/connections/YOUR_CONNECTION_ID
+Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN
+```
+In the `dpop_signing_alg` response, check for the following:
+
+* Verify the algorithm is one of the supported values: **ES256** or **Ed25519**.
+* Verify that the connection uses back-channel token exchange using [Authorization Code Flow + PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce). DPoP is not supported for front-channel communications as in [Implicit Flow](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post) and is silently disabled when the connection uses the front-channel.
+
+#### DPoP fields missing in tenant logs
+
+If Auth0 success (`s`) or failure (`f`) logs for the enterprise connection do not contain `dpop_signing_alg` or `idp_token_type` fields, it could be due to one of the following causes:
+
+* DPoP is not configured. Verify `dpop_signing_alg` is set in the connection `options` object using the Management API's [Update a connection](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) endpoint as described above.
+* Unsupported algorithm.  Auth0 supports ES256 and Ed25519 during Early Access. If `dpop_signing_alg` is set to an unsupported value (for example, RS256), DPoP is silently disabled. No error is logged. Update the connection to use ES256 or Ed25519.
+* Front-channel connection. DPoP requires a connection type of `back_channel` token exchange. You may need to [update the grant type](/docs/get-started/applications/update-grant-types#update-grant-types) to a back-channel flow like Authorization Code Flow or Authorization Code Flow + PKCE.
+
+### Authentication fails after enabling DPoP
+
+Review the following troubleshooting techniques if your users cannot complete authentication after you have enabled DPoP on your Okta or OIDC enterprise connection. 
+
+Tenant logs should display a failure (`f`) event with `dpop_signing_alg` similar to:
+
+```bash
+{
+  "type": "f",
+  "description": "Failed Login",
+  "details": {
+    "error": "dpop_signing_alg"
+  }
+}
+```
+
+Note the failure does not include the `idp_token_type` because Auth0 did not recieve a token from your IdP.
+
+#### Identity provider rejects DPoP proof
+
+The IdP may actively reject the DPoP proof Auth0 sends during token exchange. The IdP may return an `invalid_dpop_proof` error, causing authentication to fail.
+
+Check the IdP supports DPoP and if the configured algorithm (either ES256 or Ed25519) is in the supported list. You can find out by accessing the IdP's OpenID Connect discovery document:
+
+```curl
+curl https://YOUR_IDP_DOMAIN/.well-known/openid-configuration
+```
+
+In the IdP response, look for `dpop_signing_alg_values_supported`. If this field is missing, the IdP may not support DPoP. If the field lists only algorithms that Auth0 does not support (for example, only RS256), DPoP cannot be used with this connection during Early Access. You should disable DPoP for this connection or contact your IdP to enable support for ES256 or Ed25519.
+
+#### Token exchange fails for a non-DPoP reason
+
+If you find a failure log with `dpop_signing_alg` present, this does not necessarily mean DPoP caused the failure. Auth0 attaches DPoP metadata to all failure logs when DPoP is configured, even if the root cause is unrelated. For example, authentication could fail due to an expired authorization code or invalid client credentials.
+
+Examine the error description in the failure log to determine the actual cause. Common non-DPoP errors include: `invalid_grant`, `invalid_client`, and ID token signature verification failures.
+
+#### DPoP key generation fails
+
+Auth0 generates an ephemeral key pair for each DPoP proof. If key generation fails, authentication fails before the token request is sent. This is a transient server-side issue. Ask the user to retry authentication.
+
+#### IdP token binding
+
+If user authentication succeeds, but Auth0 tenant logs show `"idp_token_type": "bearer"`, then your IdP might not bind tokens with DPoP even when Auth0 sends DPoP proofs. Per RFC-9449, this is compliant behavior. The IdP has full control over whether to issue DPoP-bound tokens and may not bind tokens because:
+
+* The IdP's policy does not require DPoP for the requested resource or application.
+* The IdP does not support DPoP despite accepting the proof without error.
+* The IdP encountered an internal issue processing the DPoP proof.
+
+Auth0 tracks this as a "downgrade" event. Authentication completes successfully with standard Bearer tokens.
+
+If you require DPoP-bound tokens for compliance, we recommend you contact your IdP to understand why tokens are not being bound. Auth0 cannot enforce DPoP binding on the identity provider's token response.
+
+#### DPoP nonce handling
+
+Some IdP's require a `nonce` in the [DPoP proof per §8](https://www.rfc-editor.org/rfc/rfc9449.html#name-authorization-server-provid). When your IdP returns HTTP `400` with a `DPoP-Nonce` response header, Auth0 automatically retries the token request with the provided nonce. This is handled transparently and does not appear as a failure in tenant logs.
+
+The `use_dpop_nonce` error code is an internal protocol signal between Auth0 and the IdP. It does not indicate a problem. You should not see `use_dpop_nonce` as the reason for a failure log entry. If the retry with the nonce also fails (for example, the identity provider returns `invalid_dpop_proof` on the second attempt), the ultimate error is what appears in the failure log.
+
+If you observe repeated authentication failures on a connection where the identity provider requires nonces, check network connectivity between Auth0 and the identity provider. Nonce exchange requires two round-trips to the token endpoint, which increases sensitivity to network timeouts.
+
+