Add expiration and IDs for SSH CA (#49724)

Co-authored-by: Zachary Sierakowski <zacharysierakowski@github.com>
Co-authored-by: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com>

content/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise.md

@@ -95,6 +95,20 @@ Deleting a CA cannot be undone. If you want to use the same CA in the future, yo
 {% data reusables.enterprise-accounts.settings-tab %}
 {% data reusables.enterprise-accounts.security-tab %}
 {% data reusables.organizations.delete-ssh-ca %}
+{% ifversion ssh-ca-expires %}
+
+## Upgrading an SSH certificate authority
+
+CAs uploaded to your enterprise {% ifversion ghec %}prior to March 27th, 2024,{% elsif ghes %}before {% data variables.product.prodname_ghe_server %} version 3.13{% endif %} allow the use of non-expiring certificates. To learn more about why expirations are now required for new CAs, see "[AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities#issuing-certificates)." You can upgrade an existing CA to prevent it from issuing non-expiring certificates. For best security, we strongly recommend upgrading all your CAs once you validate you're not reliant on non-expiring certificates.
+
+{% data reusables.enterprise-accounts.access-enterprise %}
+{% data reusables.enterprise-accounts.settings-tab %}
+{% data reusables.enterprise-accounts.security-tab %}
+1. Under "SSH Certificate Authorities", to the right of the CA you want to upgrade, click **Upgrade**.
+1. Read the warning, then click **Upgrade**.
+
+After upgrading the CA, non-expiring certificates signed by that CA will be rejected.
+{% endif %}
 
 {% ifversion sso-redirect %}
 

content/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities.md

@@ -41,7 +41,7 @@ If your organization doesn't require SSH certificates, members can continue to u
 
 ## Issuing certificates
 
-When you issue each certificate, you must include an extension that specifies which {% data variables.product.product_name %} user the certificate is for. For example, you can use OpenSSH's `ssh-keygen` command, replacing KEY-IDENTITY with your key identity and USERNAME with a {% data variables.product.product_name %} username. The certificate you generate will be authorized to act on behalf of that user for any of your organization's resources. Make sure you validate the user's identity before you issue the certificate.
+When you issue each certificate, you must include an extension that specifies which {% data variables.product.product_name %} user the certificate is for. You can reference the user using their login handle{% ifversion ssh-ca-expires %} or their user ID{% endif %}. For example, you can use OpenSSH's `ssh-keygen` command, replacing KEY-IDENTITY with your key identity and USERNAME with a {% data variables.product.product_name %} username{% ifversion ssh-ca-expires %} or user ID{% endif %}. The certificate you generate will be authorized to act on behalf of that user for any of your organization's resources. Make sure you validate the user's identity before you issue the certificate.
 
 {% note %}
 
@@ -49,16 +49,34 @@ When you issue each certificate, you must include an extension that specifies wh
 
 {% endnote %}
 
+To use the `login` to identify the user, use `extension:login`:
+
 ```shell
 ssh-keygen -s ./ca-key -V '+1d' -I KEY-IDENTITY -O extension:login@{% data variables.product.product_url %}=USERNAME ./user-key.pub
 ```
 
+{% ifversion ssh-ca-expires %}
+To use the user ID, use `extension:id`:
+
+```shell
+ssh-keygen -s ./ca-key -V '+1d' -I KEY-IDENTITY -O extension:id@{% data variables.product.product_url %}=ID ./user-key.pub
+```
+
+{% endif %}
 {% warning %}
 
-**Warning**: After a certificate has been signed and issued, the certificate cannot be revoked. Make sure to use the -`V` flag to configure a lifetime for the certificate, or the certificate can be used indefinitely.
+**Warning**: After a certificate has been signed and issued, the certificate cannot be revoked.
 
 {% endwarning %}
 
+For CAs uploaded {% ifversion ghec %}after March 27th, 2024{% elsif ghes %}to {% data variables.product.prodname_ghe_server %} version 3.13 or later{% endif %}, you {% ifversion ghes < 3.13 %}will need to{% else %}must{% endif %} use the `-V` flag to configure a lifetime less than 366 days for the certificate. For CAs uploaded {% ifversion ghec %}before this date{% elsif ghes %}before version 3.13{% endif %}, the `-V` flag is optional, and you can create certificates that are irrevocable and live forever.
+
+{% ifversion ssh-ca-expires %}
+If you have legacy CAs that are exempt from the expiration requirement, you can upgrade the CA to enforce the requirement. To learn more, see "[AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities)" and "[AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise#managing-ssh-certificate-authorities-for-your-enterprise)."
+
+If you use a username as the login extension, {% data variables.product.company_short %} validates that the named user has not been renamed since the certificate was issued. This prevents a rename attack, where a certificate issued for a username is valid even if the underlying user account changes. To enforce this, the certificate must include the `valid_after` claim, which tells us when the certificate was issued. This field is often missing if an expiration is not required for the certificate, which is why expirations are now required.
+{% endif %}
+
 To issue a certificate for someone who uses SSH to access multiple {% data variables.product.company_short %} products, you can include two login extensions to specify the username for each product. For example, the following command would issue a certificate for USERNAME-1 for the user's account for {% data variables.product.prodname_ghe_cloud %}, and USERNAME-2 for the user's account on {% data variables.product.prodname_ghe_server %} at HOSTNAME.
 
 ```shell

content/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities.md

@@ -38,3 +38,17 @@ If you require SSH certificates for your enterprise, enterprise members should u
 {% data reusables.profile.org_settings %}
 {% data reusables.organizations.security %}
 {% data reusables.organizations.delete-ssh-ca %}
+{% ifversion ssh-ca-expires %}
+
+## Upgrading an SSH certificate authority
+
+CAs uploaded to your organization {% ifversion ghec %}prior to March 27th, 2024,{% elsif ghes %}before {% data variables.product.prodname_ghe_server %} version 3.13{% endif %} allow the use of non-expiring certificates. To learn more about why expirations are now required for new CAs, see "[AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities#issuing-certificates)." You can upgrade an existing CA to prevent it from issuing non-expiring certificates. For best security, we strongly recommend upgrading all your CAs once you validate you're not reliant on non-expiring certificates.
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+{% data reusables.organizations.security %}
+1. Under "SSH Certificate Authorities", to the right of the CA you want to upgrade, click **Upgrade**.
+1. Read the warning, then click **Upgrade**.
+
+After upgrading the CA, non-expiring certificates signed by that CA will be rejected.
+{% endif %}

data/features/ssh-ca-expires.yml

@@ -0,0 +1,5 @@
+# Reference: #49724
+
+versions:
+  ghec: '*'
+  ghes: '>=3.13'

data/reusables/enterprise/certificate-authority-usage.md

@@ -1,3 +1,3 @@
-Each certificate authority can only be uploaded to one account on {% data variables.product.prodname_dotcom_the_website %}. If an SSH certificate authority has been added to an organization or enterprise account, you cannot add the same certificate authority to another organization or enterprise account on {% data variables.product.prodname_dotcom_the_website %}.
+Each certificate authority can only be uploaded to one account on {% data variables.product.product_name %}. If an SSH certificate authority has been added to an organization or enterprise account, you cannot add the same certificate authority to another organization or enterprise account on {% data variables.product.product_name %}.
 
 If you add one certificate authority to an enterprise and another certificate authority to an organization in the enterprise, either certificate authority can be used to access the organization's repositories.