Add GHES SAML content about the SP SAML Signing Certificate (#53828)

Co-authored-by: Ryan Trauntvein <[email protected]>
Co-authored-by: mc <[email protected]>

Author: 3 people

content/admin/managing-iam/iam-configuration-reference/saml-configuration-reference.md

@@ -129,6 +129,36 @@ To specify more than one value for an attribute, use multiple `<saml2:AttributeV
      </samlp:Response>
      ```
 
+{% ifversion ghes %}
+
+## SAML signing certificate for AuthnRequests
+
+When you first set up {% data variables.product.prodname_ghe_server %} and start the instance, a self-signed SAML signing certificate is generated, separate from the IdP's SAML certificate. This certificate is used to sign SAML `AuthnRequests` sent to the IdP and is valid for ten years. It is stored at `/data/user/common/saml-sp.p12` and you can view details in base64-encoded format at `http(s)://HOSTNAME/saml/metadata`.
+
+If your IdP validates the SAML signing certificate, or if SAML encrypted assertions are enabled, users may face authentication issues when the certificate expires. To check the expiration date, a {% data variables.product.prodname_ghe_server %} administrator can connect to the server via SSH and run the command below. See [Connecting to the administrative shell over SSH](/admin/administering-your-instance/administering-your-instance-from-the-command-line/accessing-the-administrative-shell-ssh#connecting-to-the-administrative-shell-over-ssh).
+
+`sudo openssl pkcs12 -in /data/user/common/saml-sp.p12 -clcerts -nokeys -password pass: | sudo openssl x509 -noout -enddate`
+
+To re-generate this SAML SP signing certificate if it has expired and it's required by the IdP or encrypted assertions, a {% data variables.product.prodname_ghe_server %} administrator can run the commands below in a {% data variables.product.prodname_ghe_server %} SSH session.
+
+>[!NOTE]
+> The `nomad` commands will be briefly disruptive to users as the `github-unicorn` service restarts.
+
+``` shell
+# Backup the old certificate
+sudo cp /data/user/common/saml-sp.p12 /data/user/common/saml-sp.p12-$(date +%d%m%Y_%H%M%S)
+
+saml_tempdir=$(sudo mktemp -d)
+sudo openssl req -new -newkey rsa:4096 -days 3650 -nodes -x509 -sha256 -subj "/CN=github_enterprise" -keyout $saml_tempdir/saml.key -out $saml_tempdir/saml.crt
+sudo openssl pkcs12 -export -inkey $saml_tempdir/saml.key -in $saml_tempdir/saml.crt -nodes -password pass: -out /data/user/common/saml-sp.p12
+sudo rm -rf $saml_tempdir
+
+sudo nomad stop github-unicorn
+sudo nomad run -hcl1 /etc/nomad-jobs/github/unicorn.hcl
+```
+
+{% endif %}
+
 ## Session duration and timeout
 
 To prevent a person from authenticating with your IdP and staying authorized indefinitely, {% data variables.product.product_name %} periodically invalidates the session for each user account with access to {% ifversion ghec %}your enterprise's resources{% elsif ghes %}{% data variables.location.product_location %}{% endif %}. After invalidation, the person must authenticate with your IdP once again.

content/admin/managing-iam/using-saml-for-enterprise-iam/enabling-encrypted-assertions.md

@@ -49,3 +49,9 @@ To enable encrypted assertions, you must provide {% data variables.location.prod
 {% data reusables.enterprise_site_admin_settings.wait-for-configuration-run %}
 
 If you enabled SAML debugging to test authentication with encrypted assertions, disable SAML debugging when you're done testing. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/troubleshooting-saml-authentication#configuring-saml-debugging).
+
+## SAML signing certificate for AuthnRequests
+
+With encrypted assertions, {% data variables.product.prodname_ghe_server %} relies on the SAML signing certificate private key to decrypt assertions. This certificate is automatically generated when {% data variables.product.prodname_ghe_server %} is set up, and it is valid for 10 years.
+
+You can find more details about the SAML signing certificate, how long it is valid for, and how to regenerate it if needed in [AUTOTITLE](/admin/managing-iam/iam-configuration-reference/saml-configuration-reference#saml-signing-certificate-for-authnrequests).