Skip to content

SAML

SAML (Security Assertion Markup Language) is used to provide Single Sign-On (SSO) for GitLab instances. The SAML configuration is managed through the gitlab_rails_common_custom_config_file variable, which points to a Jinja2 template file in the solution's ansible/files/gitlab_config/ directory.

Rotating the IDP certificate

IDP certificates have an expiry date and need to be rotated before they expire. When a customer provides a new IDP certificate, two values need to be updated in the solution's SAML configuration:

  • idp_cert_fingerprint: The SHA1 fingerprint of the new certificate
  • idp_cert: The full PEM-encoded certificate (with \n line breaks)

Procedure

  1. Obtain the new certificate from the customer (PEM format).

  2. Calculate the SHA1 fingerprint of the new certificate:

    openssl x509 -noout -fingerprint -sha1 -in new_certificate.pem

    This outputs something like: sha1 Fingerprint=1B:B0:3B:28:C0:7A:52:54:42:57:BB:12:20:BC:51:36:C5:D0:C1:F2

  3. Update the solution's configuration file (typically <solution>/ansible/files/gitlab_config/gitlab_rails_common.rb.j2 or gitlab_rails.rb.j2):

    • Replace the idp_cert_fingerprint value with the new fingerprint.
    • Replace the idp_cert value with the new certificate content. The certificate must be on a single line with literal \n characters separating each line of the PEM file.

  4. Apply the change by running from the <solution>/ansible directory:

    aws-sso ansible-playbook glh.environment_toolkit.gitlab_update --limit gitlab_rails,sidekiq -i inventory

    It renders the gitlab.rb configuration and runs gitlab-ctl reconfigure on the targeted nodes. The package install step will be a no-op if the GitLab version has not changed.

Verifying your process

You can test the process by generating the fingerprint the existing certificate that is stored as idp_cert, for a solution. Using this value, it should generate the same fingerprint that is stored as the idp_cert_fingerprint value.

Tips

  • Always test certificate rotation on the test environment first before applying to production.

  • Verify the certificate expiry date before installing:

    openssl x509 -noout -dates -in new_certificate.pem

  • After applying, verify SAML login works by attempting to sign in through the SSO flow.