Skip to content

Emphasize best practices for public certificates #612

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

Merged
monfresh merged 3 commits into from
May 14, 2026
Merged

Emphasize best practices for public certificates #612

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
eccdbe7
Emphasize best practices for public certificates
monfresh May 8, 2026
a80d7ef
Move cert best practices to a better section
monfresh May 8, 2026
d3a4226
Add link to NIST 800-57
monfresh May 8, 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
8 changes: 0 additions & 8 deletions _includes/snippets/oidc/certificates.md
View file
Open in desktop

This file was deleted.

10 changes: 3 additions & 7 deletions _pages/oidc/certificates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,18 +24,14 @@ sidenav:
Login.gov's public key, used to verify signed JWTs (such as the `id_token`), is available in [JWK](https://tools.ietf.org/html/rfc7517){:class="usa-link--external"} format at the `/api/openid_connect/certs` endpoint.

This public key is rotated periodically (on at least an annual basis). It is important to assume the `/api/openid_connect/certs` endpoint could contain multiple JWKs when rotating application signing keys. Be sure to use the JWK endpoint dynamically through [auto-discovery](/oidc/getting-started/#auto-discovery) rather than hardcoding the public key. This ensures that your application will not require manual intervention when the Login.gov public key is rotated.

For your own public/private keypair used to sign your JWT, please refer to the [Creating a public certificate](/testing/#creating-a-public-certificate) section of our Testing documentation.
{% endcapture %}

<div class="grid-row grid-gap">
<div class="desktop:grid-col-8 mobile:grid-col-full">
{{ content | markdownify }}
<a href="{{ '/oidc/logout/' | prepend: site.baseurl }}" class="usa-link margin-top-4 mobile:display-none desktop:display-block">Next step: Logout</a>
</div>
<div class="usa-layout-docs__main code-snippet-column desktop:grid-col-4">
<section id="pkce" class="code-snippet-section">
<span class="code-button code-button__selected margin-left-2">OpenSSL Command</span>
{% include snippets/oidc/certificates.md %}
</section>
</div>
<a href="{{ '/oidc/logout/' | prepend: site.baseurl }}" class="usa-link mobile:display-block desktop:display-none margin-top-2">Next step: Logout</a>
<a href="{{ '/oidc/logout/' | prepend: site.baseurl }}" class="usa-link mobile:display-block desktop:display-none margin-top-2">Next step: Logout</a>
</div>
2 changes: 1 addition & 1 deletion _pages/oidc/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ You are able to test authentication methods in real time with a testing account

If you chose to integrate your app using the OIDC private_key_jwt protocol, you will need to create a private key that will be used to sign your request to our token endpoint, and a corresponding public certificate that you will upload to your app in the Partner Portal. Login.gov will use your public certificate to verify the signature in your request.

More details on how to create this public/private keypair are available in the [Creating a public certificate](https://developers.login.gov/testing/#creating-a-public-certificate) section of our Testing documentation.
More details on how to create this public/private keypair are available in the [Creating a public certificate](/testing/#creating-a-public-certificate) section of our Testing documentation.
Copy link
Copy Markdown
Contributor

@h-m-m h-m-m May 8, 2026

Choose a reason for hiding this comment

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

Nice improvement



### Auto-discovery
Expand Down
5 changes: 5 additions & 0 deletions _pages/production.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,11 @@ Make sure you have the following items ready before you start the deployment pro

- You must include an agency logo for your application. [Learn more about our logo guidelines.](/user-experience/agency-logo/)

- A public certificate that adheres to these standard best practices:
- Expiration date of 1 to 3 years depending on use and risk factors (see [NIST 800-57 Part 1 Rev. 5](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57pt1r5.pdf)). We recommend 1 year or less to be on the safe side.
- Positive serial number at least 16 characters in length
- Signed by a trusted Certificate Authority

Depending on your agency’s integration additional items may be needed:

- **If this is a SAML integration (not OpenID Connect), then please ensure that:**
Expand Down
2 changes: 1 addition & 1 deletion _pages/testing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ Login.gov does not manage user accounts. If you have lost access to a team:

### Creating a public certificate

You can use the following OpenSSL command to generate a self-signed 2048-bit PEM-encoded public certificate for your testing/sandbox application (with a 1-year validity period). Self-signed certificates should be for testing/sandbox purposes only. We recommend using Certificate Authority (CA) issued certificates for your production integration.
You can use the following OpenSSL command to generate a self-signed 2048-bit PEM-encoded public certificate for your testing/sandbox application (with a 1-year validity period). Self-signed certificates should be for testing/sandbox purposes only. **For security reasons, we highly recommend using Certificate Authority (CA) issued certificates for your production integration.**
Copy link
Copy Markdown
Contributor

@h-m-m h-m-m May 8, 2026

Choose a reason for hiding this comment

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

This change makes sense to me

Copy link
Copy Markdown
Contributor

@mmagsa mmagsa May 8, 2026

Choose a reason for hiding this comment

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

I suspect that bolding (alone) will have little effect here. Is there some resource we can link to that could help with procuring a CA-issued certificate, especially in a government setting?

Copy link
Copy Markdown
Contributor Author

@monfresh monfresh May 8, 2026

Choose a reason for hiding this comment

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

Yes! I have some high level steps but wasn't sure where to put them.

Copy link
Copy Markdown
Contributor

@mmagsa mmagsa May 11, 2026

Choose a reason for hiding this comment

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

What do you think about adding the process / steps here and linking to it from this paragraph?

Copy link
Copy Markdown
Contributor Author

@monfresh monfresh May 11, 2026

Choose a reason for hiding this comment

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

That works!

Copy link
Copy Markdown
Contributor Author

@monfresh monfresh May 14, 2026

Choose a reason for hiding this comment

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

I've been asking a few partners what they had to do to get their certs signed by a CA, and I'm waiting to hear back from them. In the meantime, I will merge this PR to get these improvements deployed, and once I have more robust steps for CA-signed certs, I will open a new PR.


```
openssl req -nodes -x509 -days 365 -newkey rsa:2048 -keyout private.pem -out public.crt
Expand Down
Loading