From eccdbe72654c052b117705c4683c8680efbd5ccd Mon Sep 17 00:00:00 2001 From: Moncef Belyamani Date: Fri, 8 May 2026 13:08:44 -0400 Subject: [PATCH 1/3] Emphasize best practices for public certificates After auditing our partners' public certs in production, I noticed that quite a few do not adhere to standard best practices. And just today, we had a partner who thought that the OpenSSL command in our OIDC Certificates page was all they needed for their production config. This PR aims to clarify those best practices by making the following improvements: - Remove the OpenSSL command snippet from the OIDC Certificates page since that page relates to the Login.gov cert, not the partner's cert - Add a blurb in the OIDC Certificates page that links to the instructions for generating the partner's public/private keypair - In the instructions for generating a public/private keypair, emphasize that for production configs, the cert should be signed by a Certificate Authority - Add a checklist item in the "Before Deployment" section for the three main best practices for public certificates --- _includes/snippets/oidc/certificates.md | 8 -------- _pages/oidc/certificates.md | 10 +++------- _pages/oidc/getting-started.md | 2 +- _pages/production.md | 5 +++++ _pages/testing.md | 2 +- 5 files changed, 10 insertions(+), 17 deletions(-) delete mode 100644 _includes/snippets/oidc/certificates.md diff --git a/_includes/snippets/oidc/certificates.md b/_includes/snippets/oidc/certificates.md deleted file mode 100644 index bd7e1361..00000000 --- a/_includes/snippets/oidc/certificates.md +++ /dev/null @@ -1,8 +0,0 @@ -{% capture ssl %} -``` -openssl req -nodes -x509 -days 365 -newkey rsa:2048 -keyout private.pem -out public.crt -``` -{% endcapture %} -
-{{ ssl | markdownify }} -
diff --git a/_pages/oidc/certificates.md b/_pages/oidc/certificates.md index 879e4dbc..896c416f 100644 --- a/_pages/oidc/certificates.md +++ b/_pages/oidc/certificates.md @@ -24,6 +24,8 @@ 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 %}
@@ -31,11 +33,5 @@ This public key is rotated periodically (on at least an annual basis). It is imp {{ content | markdownify }} Next step: Logout
-
-
- OpenSSL Command - {% include snippets/oidc/certificates.md %} -
-
- Next step: Logout + Next step: Logout diff --git a/_pages/oidc/getting-started.md b/_pages/oidc/getting-started.md index 8b1b1b1c..ffb56f12 100644 --- a/_pages/oidc/getting-started.md +++ b/_pages/oidc/getting-started.md @@ -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. ### Auto-discovery diff --git a/_pages/production.md b/_pages/production.md index c307b7bb..cab59c71 100644 --- a/_pages/production.md +++ b/_pages/production.md @@ -63,6 +63,11 @@ Depending on your agency’s integration additional items may be needed: - **If this is an integration requesting identity proofed attributes, you must include a Failure to Proof URL.** Users will be redirected to this URL if they fail to complete the identity verification process. This page should communicate your agency and/or departments alternate methods of accessing your application. +- A public certificate that adheres to these industry standard best practices: + - Expiration date of one year or less + - Positive serial number at least 16 characters in length + - Signed by a trusted Certificate Authority + If you have questions after reviewing this page, submit a technical support ticket through the [Partner Support Help Desk]({{ site.baseurl}}/support/#contacting-partner-support). You will need a [Login.gov production account](https://secure.login.gov) to submit technical support tickets. Your Login.gov production account and Login.gov sandbox (test environment) accounts are separate. diff --git a/_pages/testing.md b/_pages/testing.md index 79c33f8b..94892050 100644 --- a/_pages/testing.md +++ b/_pages/testing.md @@ -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.** ``` openssl req -nodes -x509 -days 365 -newkey rsa:2048 -keyout private.pem -out public.crt From a80d7ef857a86970510d5a33dcc264df90399d1e Mon Sep 17 00:00:00 2001 From: Moncef Belyamani Date: Fri, 8 May 2026 13:54:00 -0400 Subject: [PATCH 2/3] Move cert best practices to a better section --- _pages/production.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/_pages/production.md b/_pages/production.md index cab59c71..f4993041 100644 --- a/_pages/production.md +++ b/_pages/production.md @@ -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 industry standard best practices: + - Expiration date of one year or less + - 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:** @@ -63,11 +68,6 @@ Depending on your agency’s integration additional items may be needed: - **If this is an integration requesting identity proofed attributes, you must include a Failure to Proof URL.** Users will be redirected to this URL if they fail to complete the identity verification process. This page should communicate your agency and/or departments alternate methods of accessing your application. -- A public certificate that adheres to these industry standard best practices: - - Expiration date of one year or less - - Positive serial number at least 16 characters in length - - Signed by a trusted Certificate Authority - If you have questions after reviewing this page, submit a technical support ticket through the [Partner Support Help Desk]({{ site.baseurl}}/support/#contacting-partner-support). You will need a [Login.gov production account](https://secure.login.gov) to submit technical support tickets. Your Login.gov production account and Login.gov sandbox (test environment) accounts are separate. From d3a4226f238324b5fc45351261529376dc6da256 Mon Sep 17 00:00:00 2001 From: Moncef Belyamani Date: Fri, 8 May 2026 15:36:18 -0400 Subject: [PATCH 3/3] Add link to NIST 800-57 --- _pages/production.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_pages/production.md b/_pages/production.md index f4993041..f3fb4485 100644 --- a/_pages/production.md +++ b/_pages/production.md @@ -51,8 +51,8 @@ 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 industry standard best practices: - - Expiration date of one year or less +- 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