Skip to content

Update Diagram and Primer to reflect iss check #257

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
uvdsl wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update Diagram and Primer to reflect iss check #257

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ae1d19b
update primer
uvdsl Jun 24, 2026
470d4c4
update diagram
uvdsl Jun 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 19 additions & 10 deletions primer/index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -360,18 +360,27 @@ id, the [=code challenge=], the user's webid, their desired response types, and
}
```

<h4 id="authorization-code-pkce-flow-step-11" class="no-num">11. Send authorization code to redirect url</h4>
<h4 id="authorization-code-pkce-flow-step-11" class="no-num">11. Send authorization code and `iss` parameter to redirect url</h4>

Once Alice successfully logs in, the OP redirects back to the application via the provided
redirect uri, including useful information with it:
redirect uri. The OP includes the authorization code as well as its own issuer identifier as the iss parameter to protect against mix-up attacks:

```http
302 redirect to: https://decentphotos.example/callback?code=m-OrTPHdRsm8W_e9P0J2Bt
302 redirect to: https://decentphotos.example/callback?code=m-OrTPHdRsm8W_e9P0J2Bt&iss=https%3A%2F%2Fsecureauth.example
```

This redirect gives decentphotos the [=authorization code=] that it will exchange for requested tokens.
This redirect gives decentphotos the [=authorization code=] that it will exchange for requested tokens, along with the issuer identifier required for the next validation step.

<h4 id="authorization-code-pkce-flow-step-12" class="no-num">12. Generates a DPoP Client Key Pair</h4>
<h4 id="authorization-code-pkce-flow-step-12" class="no-num">12. Validate `iss` Parameter</h4>

Before proceeding to exchange the code for tokens, decentphotos must verify the `iss` parameter.
This ensures the application is receiving the code from the exact OP it intended to communicate with.

The application checks that the `iss` value (`https://secureauth.example`) matches the issuer URL it resolved in Step 3.
If the `iss` parameter is missing or does not match the expected OP, decentphotos must reject the response, abort the authentication flow, and optionally display an error to Alice.
In our example, the issuer matches, so we may safely continue.

<h4 id="authorization-code-pkce-flow-step-13" class="no-num">13. Generates a DPoP Client Key Pair</h4>

Solid-OIDC depends on
[Demonstration of Proof-of-Possession (DPoP) tokens](https://tools.ietf.org/html/draft-ietf-oauth-dpop).
Expand Down Expand Up @@ -410,7 +419,7 @@ The public key looks like:
}
```

<h4 id="authorization-code-pkce-flow-step-13" class="no-num">13. Generates a DPoP Header</h4>
<h4 id="authorization-code-pkce-flow-step-14" class="no-num">14. Generates a DPoP Header</h4>

Now that we generated a private key for the client, we need to generate the DPoP header. To do
so, we create a [JSON Web Token](https://jwt.io/introduction/) and sign it using the key we
Expand Down Expand Up @@ -459,7 +468,7 @@ Token Body:
that can optionally be used by the server to defend against replay attacks
- `"iat": 1603306128`: The date the token was issued, in this case October 21, 2020 15:52:33 GMT.

<h4 id="authorization-code-pkce-flow-step-14" class="no-num">14. Token request with code and code verifier</h4>
<h4 id="authorization-code-pkce-flow-step-15" class="no-num">15. Token request with code and code verifier</h4>

Now, we have everything we need to make an auth request. No need to redirect the web browser
for this one. We only need to make an AJAX request to the `token` endpoint as defined in the
Expand Down Expand Up @@ -495,7 +504,7 @@ Body:

Once this request is completed decentphotos can remove the code verifier from session storage.

<h4 id="authorization-code-pkce-flow-step-15" class="no-num">15. Validate code verifier</h4>
<h4 id="authorization-code-pkce-flow-step-16" class="no-num">16. Validate code verifier</h4>

The OP looks up the [=authorization code=] that was saved earlier in a keystore. It checks to see that the client
id in the keystore corresponds to the client id from the request. If it does not, it must
Expand All @@ -511,13 +520,13 @@ BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) == code_challenge
If they do not correspond the OP must reject the request with a 400 HTTP status and `invalid_grant`
error code.

<h4 id="authorization-code-pkce-flow-step-16" class="no-num">16. Validates DPoP Token Signature</h4>
<h4 id="authorization-code-pkce-flow-step-17" class="no-num">17. Validates DPoP Token Signature</h4>

The OP extracts the client's public key from the DPoP header (at header.jwk). It confirms that
the DPoP token has a valid signature. If not, the OP must reject the request with a 400 HTTP
status and `invalid_dpop_proof` error code.

<h4 id="authorization-code-pkce-flow-step-17" class="no-num">17. Converts the DPoP public key to a JWK thumbprint</h4>
<h4 id="authorization-code-pkce-flow-step-18" class="no-num">18. Converts the DPoP public key to a JWK thumbprint</h4>

Currently the DPoP token contains a JWK public key, but before we place it inside the access
token, it needs to be converted into a [JWK thumbprint](https://tools.ietf.org/html/rfc7638).
Expand Down
17 changes: 9 additions & 8 deletions primer/primer-login.mmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,13 +17,14 @@ sequenceDiagram
note over OP: 8. Validates redirect url with Client ID Document
note over OP: 9. Alice Logs In
note over OP: 10. Generates an authorization code
OP->>Client: 11. Send authorization code to redirect url
note over Client: 12. Generates DPoP Client Key Pair
note over Client: 13. Generates a DPoP Header
Client->>OP: 14. Token request with code and code verifier
note over OP: 15. Validates code verifier
note over OP: 16. Validates DPoP Token signature
note over OP: 17. Converts the DPoP public key to a JWK thumbprint
OP->>Client: 11. Send authorization code and iss parameter to redirect url
note over Client: 12 Validates that the returned iss matches the expected OP issuer
note over Client: 13. Generates DPoP Client Key Pair
note over Client: 14. Generates a DPoP Header
Client->>OP: 15. Token request with code and code verifier
note over OP: 16. Validates code verifier
note over OP: 17. Validates DPoP Token signature
note over OP: 18. Converts the DPoP public key to a JWK thumbprint
note over OP: 19. Generates id token
note over OP: 20. Generates refresh token
OP->>Client: 21. Send tokens
OP->>Client: 21. Send tokens
3 changes: 2 additions & 1 deletion sequence.mmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@ sequenceDiagram
OP->> ClientID: get Client ID document
ClientID->> OP: ClientID document
Note over OP: compare redirect_uri
OP ->> C: return Authorization Code
OP ->> C: return Authorization Code and iss parameter
Note over C: Validate iss matches expected OP
C ->> OP: present Authorization Code and DPoP proof
Note over OP: ⚙️ Client is authenticated ✅
OP ->> C: return DPoP bound OIDC ID Token
Expand Down