diff --git a/content/admin/managing-iam/iam-configuration-reference/saml-configuration-reference.md b/content/admin/managing-iam/iam-configuration-reference/saml-configuration-reference.md index da95aafe1d71..24a9d261b237 100644 --- a/content/admin/managing-iam/iam-configuration-reference/saml-configuration-reference.md +++ b/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 ` ``` +{% 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. diff --git a/content/admin/managing-iam/using-saml-for-enterprise-iam/enabling-encrypted-assertions.md b/content/admin/managing-iam/using-saml-for-enterprise-iam/enabling-encrypted-assertions.md index e160b0c3599e..e7233377e2ce 100644 --- a/content/admin/managing-iam/using-saml-for-enterprise-iam/enabling-encrypted-assertions.md +++ b/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).