Skip to content
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

Jump to bottom

Updates code_challenge documentation #468

Merged
merged 1 commit into from
Mar 26, 2024
Merged

Updates code_challenge documentation #468

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
39 changes: 16 additions & 23 deletions _pages/oidc/authorization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,12 +37,11 @@ Correct Example
```ruby
code_verifier = SecureRandom.hex
=> "5787d673fb784c90f0e309883241803d"
code_challenge = Digest::SHA256.digest(code_verifier) # binary data
code_challenge = Digest::SHA256.digest(code_verifier)
=> "\xD4\x15)\xC7-\xFBJ\x82\x0F\x98\xAC=\xEB\x06\xDD\xE8\xC0\xDC\xBD\xAC\x8Ebm\xE9\xB5?\xB3m\xEE\x8B\xFF3" # binary digest
url_safe_code_challenge = Base64.urlsafe_encode64(code_challenge)
# RFC 4648 URL-safe Base64 encoding replaces "+" with "-" and "/" with "_" and trims trailing "="
=> "1BUpxy37SoIPmKw96wbd6MDcvayOYm3ptT-zbe6L_zM"
Base64.encode64(code_challenge) # wrong and URL-unsafe encoding
=> "1BUpxy37SoIPmKw96wbd6MDcvayOYm3ptT+zbe6L/zM=" # wrong and URL-unsafe encoding
# RFC 4648 URL-safe Base64 encoding replaces "+" with "-" and "/" with "_"
=> "1BUpxy37SoIPmKw96wbd6MDcvayOYm3ptT-zbe6L_zM="
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[question] if we want to remove the trailing = we can do that by adding padding: false as an option to Base64.urlsafe_encode64 but it was unclear to me if that was necessary. does anyone know offhand?

Copy link
Contributor

@Jeremy1026 Jeremy1026 Mar 25, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if we need it or not, but since it works with it (based on my test integration I made forever ago) I'd be inclined to leave it in our docs.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it looks like we remove the padding if it exists, so it doesn't matter.

https://github.com/18F/identity-idp/blob/main/app/forms/openid_connect_token_form.rb#L191-L195

```

Incorrect Example
Expand All @@ -53,13 +52,7 @@ Base64.encode64(code_challenge) # wrong and URL-unsafe encoding
=> "1BUpxy37SoIPmKw96wbd6MDcvayOYm3ptT+zbe6L/zM=" # wrong and URL-unsafe encoding
```
{% endcapture %}
{% capture code_challenge_incorrect %}
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this capture is unused

```ruby
=> "1BUpxy37SoIPmKw96wbd6MDcvayOYm3ptT-zbe6L_zM"
Base64.encode64(code_challenge) # wrong and URL-unsafe encoding
=> "1BUpxy37SoIPmKw96wbd6MDcvayOYm3ptT+zbe6L/zM=" # wrong and URL-unsafe encoding
```
{% endcapture %}

{% capture scope_possible_values %}
Possible values are:
- `openid`
Expand Down Expand Up @@ -113,8 +106,8 @@ In an **unsuccessful authorization**, the URI will contain the parameters `error
<div class="grid-row grid-gap">
<div class="desktop:grid-col-9 mobile:grid-col-full">
<h2 class="margin-top-neg-1">Authorization</h2>
<p>The authorization endpoint handles authentication and authorization of a user.
To present the Login.gov authorization page to a user, direct them to the
<p>The authorization endpoint handles authentication and authorization of a user.
To present the Login.gov authorization page to a user, direct them to the
<code class="language-plaintext highlighter-rouge">/openid_connect/authorize</code>. View an example for <strong>private_key_jwt</strong> or <strong>PKCE</strong> in the side panel.</p>
<h3 class="margin-top-4" id="request-parameters">Request Parameters</h3>
<ul class="doc-sub-nav">
Expand All @@ -139,7 +132,7 @@ In an **unsuccessful authorization**, the URI will contain the parameters `error
{% include accordion.html content=loa_values accordion_id="loa_accordion" title="Level of Assurance (LOA) Values (Deprecated)" id="loa_values" %}
</div>
<p id="fn:1">
1. Login.gov continues to work toward achieving certification of compliance with NIST’s IAL2 standard from a third-party assessment organization.
1. Login.gov continues to work toward achieving certification of compliance with NIST’s IAL2 standard from a third-party assessment organization.
<a href="#fnref:1">↩</a>1 <a href="#fnref:1:2">↩</a>2 <a href="#fnref:1:3">↩</a>3
</p>
</div>
Expand All @@ -157,12 +150,12 @@ In an **unsuccessful authorization**, the URI will contain the parameters `error
<h4 class="parameters clearfix">code_challenge</h4><span class="float-left text-italic">required for PKCE</span>
</div>
<div class="grid-col-7 padding-bottom-2">
The <a class="usa-link usa-link--external" href="https://datatracker.ietf.org/doc/html/rfc4648">RFC 4648</a> URL-safe Base64 encoding of the SHA256 digest of a random value generated by the client. The original random value is referred to as the <code class="language-plaintext highlighter-rouge">code_verifier</code> and is later used with the token endpoint. Generating these values in Ruby might look like this, for example:
The <a class="usa-link usa-link--external" href="https://datatracker.ietf.org/doc/html/rfc4648">RFC 4648</a> URL-safe Base64 encoding of the SHA256 binary digest of a random value generated by the client. The original random value is referred to as the <code class="language-plaintext highlighter-rouge">code_verifier</code> and is later used with the token endpoint. Generating these values in Ruby might look like this, for example:
</div>
</div>
<div class="grid-row">
<div class="usa-accordion padding-top-2">
{% include accordion.html content=code_challenge accordion_id="code_challenge_accordion" title="Code Challenge Example" id="code_challenge" %}
{% include accordion.html content=code_challenge accordion_id="code_challenge_accordion" title="Code Challenge Example" id="code_challenge" %}
</div>
</div>
</div>
Expand Down Expand Up @@ -231,12 +224,12 @@ In an **unsuccessful authorization**, the URI will contain the parameters `error
<h4 class="parameters clearfix">nonce</h4>
</div>
<div class="grid-col-7">
A unique value, at least 22 characters in length, used to verify the integrity
of the <code class="language-plaintext highlighter-rouge">id_token</code> and mitigate
<a class="usa-link usa-link usa-link--external" href="https://en.wikipedia.org/wiki/Replay_attack">replay attacks</a>.
This value should include per-session state and be unguessable by attackers. This value will be present in the
<code class="language-plaintext highlighter-rouge">id_token</code> of the <a class="usa-link" href="{{ '/oidc/token/#token-response' | prepend: site.baseurl }}">token endpoint response</a>,
where clients will verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request.
A unique value, at least 22 characters in length, used to verify the integrity
of the <code class="language-plaintext highlighter-rouge">id_token</code> and mitigate
<a class="usa-link usa-link usa-link--external" href="https://en.wikipedia.org/wiki/Replay_attack">replay attacks</a>.
This value should include per-session state and be unguessable by attackers. This value will be present in the
<code class="language-plaintext highlighter-rouge">id_token</code> of the <a class="usa-link" href="{{ '/oidc/token/#token-response' | prepend: site.baseurl }}">token endpoint response</a>,
where clients will verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request.
Read more about <a class="usa-link usa-link--external" href="https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes">nonce implementation</a> in the spec.
</div>
</div>
Expand Down
Loading