Updated documentation, test cases and parameter type for dpop nonce

Author: rmad17

README.md

@@ -229,9 +229,12 @@ challenge = await my_account.enroll_authentication_method(
 
 For the full enroll/verify ceremony, listing, updating, deleting, and error handling, see [examples/MyAccountAuthenticationMethods.md](examples/MyAccountAuthenticationMethods.md).
 
-### 8. DPoP — Sender-Constrained Tokens
+### 8. DPoP — Sender-Constrained Tokens (Passkeys & MyAccount)
 
-Bind tokens to a key your server holds ([RFC 9449](https://www.rfc-editor.org/rfc/rfc9449)) so a stolen token alone cannot be replayed. Generate an EC P-256 key and pass it to passkey sign-in or any My Account API call:
+Bind tokens to a key your server holds ([RFC 9449](https://www.rfc-editor.org/rfc/rfc9449)) so a stolen token alone cannot be replayed. Generate an EC P-256 key and pass it to passkey sign-in or to the authentication-methods/factors calls on `MyAccountClient`:
+
+> [!NOTE]
+> `dpop_key` is currently supported only for `signin_with_passkey` and the authentication-methods/factors methods on `MyAccountClient` (enroll, verify, list, get, update, delete, get factors). It is **not yet supported for Connected Accounts** — see [examples/ConnectedAccounts.md](examples/ConnectedAccounts.md).
 
 ```python
 from jwcrypto import jwk
@@ -246,7 +249,7 @@ result = await auth0.signin_with_passkey(
 )
 ```
 
-`dpop_key` is a Tier 0 secret you generate, keep in your secret store, and reuse for the bound token's lifetime — pass the **same** key to passkey sign-in and every My Account API call. For usage, see [examples/Passkeys.md](examples/Passkeys.md#3-dpop-bound-passkey-tokens-optional) and [examples/MyAccountAuthenticationMethods.md](examples/MyAccountAuthenticationMethods.md#dpop).
+`dpop_key` is a Tier 0 secret you generate, keep in your secret store, and reuse for the bound token's lifetime — pass the **same** key to passkey sign-in and to the `MyAccountClient` authentication-methods/factors calls listed above. For usage, see [examples/Passkeys.md](examples/Passkeys.md#3-dpop-bound-passkey-tokens-optional) and [examples/MyAccountAuthenticationMethods.md](examples/MyAccountAuthenticationMethods.md#dpop).
 
 ### 9. Session Expiry from the Upstream IdP
 

examples/MyAccountAuthenticationMethods.md

@@ -27,7 +27,7 @@ The [My Account API](https://auth0.com/docs/manage-users/my-account-api) lets a
 2. [Configure MRRT](https://auth0.com/docs/secure/tokens/refresh-tokens/multi-resource-refresh-token) so your refresh-token policy can mint tokens for the My Account audience (`https://{yourDomain}/me/`) with the authentication-methods scopes.
 3. Passkey enrollment additionally requires a [Custom Domain](https://auth0.com/docs/customize/custom-domains) and the native passkey feature on your tenant.
 
-The scopes for this surface (note the **hyphens**):
+See [Auth0 Docs → Scope](https://auth0.com/docs/manage-users/my-account-api#scope) for the full scope reference. The scopes for this surface (note the **hyphens**):
 
 | Operation | Scope |
 |-----------|-------|
@@ -42,7 +42,7 @@ The scopes for this surface (note the **hyphens**):
 
 ## Obtaining a scoped token
 
-`MyAccountClient` is **stateless** — it takes a correctly-scoped user access token on every call. Obtain that token from your `ServerClient` session via MRRT, then construct the client:
+`MyAccountClient` is **stateless** — it takes a correctly-scoped user access token on every call. Obtain that token from your `ServerClient` session via MRRT, then construct the client. See [Auth0 Docs → Get an access token](https://auth0.com/docs/manage-users/my-account-api#get-an-access-token) for the underlying token requirements.
 
 ```python
 from auth0_server_python.auth_server.my_account_client import MyAccountClient
@@ -67,7 +67,7 @@ for factor in factors.factors:
 
 ## 2. Enroll an authentication method (passkey)
 
-Enrollment is a **two-step** ceremony, mirroring sign-in: request a challenge, sign it in the browser, then verify.
+Enrollment is a **two-step** ceremony, mirroring sign-in: request a challenge, sign it in the browser, then verify. See [Auth0 Docs → Enrollment flow](https://auth0.com/docs/manage-users/my-account-api#enrollment-flow) (and, for passkeys specifically, [Embedded login with native passkeys](https://auth0.com/docs/manage-users/my-account-api#embedded-login-with-native-passkeys)) for the platform-level description of this ceremony.
 
 ### Step 1 — Start enrollment
 
@@ -122,6 +122,8 @@ print(f"Enrolled: {method.id} ({method.type})")
 
 ## 3. List authentication methods
 
+See [Auth0 Docs → List authentication methods](https://auth0.com/docs/manage-users/my-account-api#list-authentication-methods).
+
 ```python
 all_methods = await my_account.list_authentication_methods(access_token=access_token)
 
@@ -163,6 +165,8 @@ method = await my_account.update_authentication_method(
 
 ## 6. Delete an authentication method
 
+See [Auth0 Docs → Delete an authentication method](https://auth0.com/docs/manage-users/my-account-api#delete-an-authentication-method).
+
 ```python
 await my_account.delete_authentication_method(
     access_token=access_token,

examples/Passkeys.md

@@ -25,15 +25,6 @@ A passkey ceremony is always **two steps**, because the WebAuthn signature happe
 2. **Browser** — your front end passes those options to `navigator.credentials.create()` (signup) or `navigator.credentials.get()` (login). The authenticator produces a signed credential.
 3. **Verify / sign-in** — the SDK exchanges the signed credential for tokens (`signin_with_passkey`) and **creates a server-side session**, exactly like every other login path.
 
-```
-ServerClient.passkey_*_challenge()  ──►  auth_session + authn_params_public_key
-                                              │
-              navigator.credentials.create()/get()  (browser signs)
-                                              │
-ServerClient.signin_with_passkey()  ◄──  signed authn_response
-        └─► tokens validated, session persisted → PasskeyLoginResult
-```
-
 ## Prerequisites
 
 ```python

src/auth0_server_python/auth_schemes/dpop_auth.py

@@ -2,6 +2,7 @@
 import hashlib
 import time
 import uuid
+from typing import Optional
 
 import httpx
 from jwcrypto import jwk
@@ -20,7 +21,9 @@ def _validate_dpop_key(key: "jwk.JWK") -> dict:
     return public_jwk
 
 
-def make_dpop_proof_for_token_endpoint(key: "jwk.JWK", method: str, url: str, nonce: str = None) -> str:
+def make_dpop_proof_for_token_endpoint(
+    key: "jwk.JWK", method: str, url: str, nonce: Optional[str] = None
+) -> str:
     """
     Build a DPoP proof JWT for use at the token endpoint (RFC 9449 §4.2).
     Unlike resource-server proofs, token-endpoint proofs do NOT include `ath`
@@ -69,15 +72,14 @@ def auth_flow(self, request: httpx.Request):
         response = yield request
 
         # RFC 9449 §8.2 — server-nonce retry
-        if (
-            response.status_code == 401
-            and response.headers.get("DPoP-Nonce")
-        ):
+        if response.status_code == 401 and response.headers.get("DPoP-Nonce"):
             nonce = response.headers["DPoP-Nonce"]
-            request.headers["DPoP"] = self._make_proof(request.method, str(request.url), nonce=nonce)
+            request.headers["DPoP"] = self._make_proof(
+                request.method, str(request.url), nonce=nonce
+            )
             yield request
 
-    def _make_proof(self, method: str, url: str, nonce: str = None) -> str:
+    def _make_proof(self, method: str, url: str, nonce: Optional[str] = None) -> str:
         htu = url.split("?")[0].split("#")[0]
         ath = _base64url(hashlib.sha256(self._token.encode("ascii")).digest())
 

src/auth0_server_python/auth_server/server_client.py

@@ -2800,9 +2800,6 @@ async def signin_with_passkey(
         This is step 2 of 2: call passkey_signup_challenge or passkey_login_challenge
         first to obtain auth_session and the WebAuthn challenge options.
 
-        Uses Content-Type: application/json (required for nested authn_response).
-        Persists the session to the state store (same as complete_interactive_login).
-
         Args:
             auth_session: Session credential from passkey_signup_challenge or passkey_login_challenge.
             authn_response: Serialized WebAuthn credential from navigator.credentials.create/get.
@@ -2823,6 +2820,9 @@ async def signin_with_passkey(
         Raises:
             MissingRequiredArgumentError: If auth_session or authn_response is missing.
             PasskeyError: If token exchange or session creation fails.
+            OrganizationTokenValidationError: If an organization was requested but the
+                token response included no ID token, or the ID token's org claim does
+                not match.
         """
         if not auth_session:
             raise MissingRequiredArgumentError("auth_session")
@@ -2920,6 +2920,12 @@ async def signin_with_passkey(
                         f"got '{token_response.token_type}'",
                     )
 
+            if resolved_org and not token_response.id_token:
+                raise OrganizationTokenValidationError(
+                    "Organization was requested but the token response included no ID token; "
+                    "cannot verify organization membership"
+                )
+
             # Extract user claims from ID token if present
             user_claims = None
             sid = PKCE.generate_random_string(32)

src/auth0_server_python/tests/test_server_client.py

@@ -57,6 +57,7 @@
     MissingTransactionError,
     OrganizationTokenValidationError,
     PasskeyError,
+    PasskeyErrorCode,
     PollingApiError,
     SessionExpiredError,
     StartLinkUserError,
@@ -5455,7 +5456,7 @@ async def test_passkey_signup_challenge_api_error(mocker):
         await client.passkey_signup_challenge(
             user_profile=PasskeyUserProfile(email="test@example.com")
         )
-    assert "access_denied" in str(exc.value) or "Passkey not enabled" in str(exc.value)
+    assert exc.value.code == "access_denied"
 
 
 @pytest.mark.asyncio
@@ -5476,7 +5477,7 @@ async def test_passkey_signup_challenge_non_json_error(mocker):
 
     with pytest.raises(PasskeyError) as exc:
         await client.passkey_signup_challenge()
-    assert "502" in str(exc.value) or "passkey_challenge_error" in str(exc.value)
+    assert exc.value.code == PasskeyErrorCode.CHALLENGE_FAILED
 
 
 @pytest.mark.asyncio
@@ -5494,7 +5495,7 @@ async def test_passkey_signup_challenge_network_error(mocker):
 
     with pytest.raises(PasskeyError) as exc:
         await client.passkey_signup_challenge()
-    assert "Passkey signup challenge failed" in str(exc.value)
+    assert exc.value.code == PasskeyErrorCode.CHALLENGE_FAILED
 
 
 @pytest.mark.asyncio
@@ -6150,7 +6151,7 @@ async def test_signin_with_passkey_dpop_rejects_bearer_downgrade(mocker):
             authn_response=_make_passkey_authn_response(),
             dpop_key=dpop_key,
         )
-    assert "DPoP" in str(exc.value) or "token_type" in str(exc.value).lower()
+    assert exc.value.code == PasskeyErrorCode.TOKEN_EXCHANGE_FAILED
 
 
 @pytest.mark.asyncio
@@ -6179,12 +6180,11 @@ async def test_signin_with_passkey_missing_issuer_in_metadata(mocker):
     mock_response.json = MagicMock(return_value=_PASSKEY_TOKEN_RESPONSE)
     mock_post.return_value = mock_response
 
-    with pytest.raises(Exception) as exc:
+    with pytest.raises(IssuerValidationError):
         await client.signin_with_passkey(
             auth_session="session_xyz",
             authn_response=_make_passkey_authn_response(),
         )
-    assert "issuer" in str(exc.value).lower()
 
 
 @pytest.mark.asyncio
@@ -6691,6 +6691,40 @@ async def test_signin_with_passkey_call_arg_overrides_client_default_organizatio
     assert kwargs["json"]["organization"] == "org_override"
 
 
+@pytest.mark.asyncio
+async def test_signin_with_passkey_org_requested_no_id_token_raises_and_no_session_stored(mocker):
+    """Organization requested but token response has no id_token: fail closed, no session stored."""
+    state_store = AsyncMock()
+    client = ServerClient(
+        domain="auth0.local",
+        client_id="test_client_id",
+        client_secret="test_client_secret",
+        state_store=state_store,
+        transaction_store=AsyncMock(),
+        secret="test-secret-value",
+    )
+    mocker.patch.object(
+        client,
+        "_get_oidc_metadata_cached",
+        return_value={"token_endpoint": "https://auth0.local/oauth/token", "issuer": "https://auth0.local/"},
+    )
+    mocker.patch.object(client, "_get_jwks_cached", return_value={})
+    mock_post = mocker.patch("httpx.AsyncClient.post", new_callable=AsyncMock)
+    mock_response = AsyncMock()
+    mock_response.status_code = 200
+    mock_response.json = MagicMock(return_value={**_PASSKEY_TOKEN_RESPONSE, "id_token": None})
+    mock_post.return_value = mock_response
+
+    with pytest.raises(OrganizationTokenValidationError):
+        await client.signin_with_passkey(
+            auth_session="session_xyz",
+            authn_response=_make_passkey_authn_response(),
+            organization="org_expected",
+        )
+
+    state_store.set.assert_not_awaited()
+
+
 @pytest.mark.asyncio
 async def test_signin_with_passkey_org_id_mismatch_raises_and_no_session_stored(mocker):
     """org_id in ID token not matching raises OrganizationTokenValidationError; session not stored."""