Managing Your Enterprise Identity Provider (IdP) Certificates

[Sam-Rowe]

Managing Your Enterprise Identity Provider (IdP) Certificates

Maintaining the security and integrity of your enterprise's identity infrastructure is paramount. One crucial aspect of this is managing your Identity Provider (IdP) certificates. These certificates play a vital role in enabling Single Sign-On (SSO) and ensuring secure authentication for your GitHub Enterprise Managed Users (GHEC EMU) users.

Why is Certificate Management Important?

IdP certificates, like any other digital certificate, have an expiration date. If a certificate expires, users may be unable to log in to your GHEC EMU. This can lead to significant disruptions and impact productivity. Therefore, proactively managing and renewing these certificates is essential.

Best Practices for IdP Certificate Management

Here are some key considerations for managing your IdP certificates:

• Regular Reviews: Conduct periodic reviews of your IdP certificates, ideally on a yearly basis, to check their expiration dates. This proactive approach helps prevent unexpected outages.
• Plan for Renewal: When a certificate is approaching its expiration date, plan for its renewal well in advance. This includes generating a new certificate, configuring it in your IdP, and updating your GitHub configuration with your ‘Setup User’ for your GHEC EMU Enterprise.
• Testing Change: It is essential to test the new certificate before deploying it to production. This allows you to identify and resolve any potential issues without impacting your users. The GHEC EMU portal has the option to test that the new certificate works; this must pass before you can save the page.
• Downtime Considerations: Be aware that there might be a brief period of downtime during the certificate swap, especially in larger enterprise environments. Communicate any planned downtime to your users in advance.
• Recovery Codes: Always maintain a set of recovery codes or backup authentication methods. This ensures that you can still access your systems even if there are issues with your IdP or certificates.
• Security Best Practices: Adhere to security best practices when handling certificates. Store private keys securely and restrict access to certificate management tools.
• Documentation: Keep detailed documentation of your IdP certificate management processes. This will help ensure consistency and facilitate troubleshooting in the future. The IDP certificate can only be managed by the GHEC EMU ‘Setup User’ so ensure the documentation also describes your security practices for gaining access to this special user and how to recycle the recovery codes.

In summary: Regular IdP certificate management is crucial for maintaining secure and uninterrupted access to your enterprise systems. By following these best practices, enterprise administrators can minimize the risk of authentication issues and ensure a smooth user experience.

Example of a certificate in Entra IDP:

This can be found in Entra by going to ‘Enterprise Applications’ then finding the GitHub Enterprise Application for the relevant EMU. In that application under the Manage section open the ‘Single Sign-On’ which then lets you see the steps that were taken to setup the EMU IDP connection and on Step 3 for SAML Certificates there is an Edit button that allows you to see the current certificate and with the correct permissions to create a new certificate.

Other IDP’s have their own steps and this was correct at the time of writing in February 2025.

Steps to change the certificate in GitHub Enterprise:

1. Sign in as the setup user for your enterprise:
   Use the username SHORT-CODE_admin, replacing SHORT-CODE with your enterprise's short code. If you need to reset the password for this user, you can contact GitHub Support.

2. Access the SAML configuration settings:
   In the top-right corner of GitHub, click your profile photo.
   Click Your enterprise.
   In the enterprise account sidebar on the left, click Identity provider.
   Under Identity Provider, click Single sign-on configuration.

3. Edit the SAML configuration:
   Under SAML single sign-on, locate your current configuration and click Edit.
   Update the Public Certificate field with the new Base64-encoded public certificate from your Identity Provider (IdP). This is the certificate that corresponds to the private key used to sign SAML responses.

4. Verify the hashing algorithms:
   Ensure the Signature Method and Digest Method match the algorithms used by your IdP. Update these if necessary.

5. Test the new SAML configuration:
   Before saving, click Test SAML configuration to ensure the new certificate works correctly. This test uses Service Provider-initiated (SP-initiated) authentication and must succeed before you can save the changes.

6. Save the updated configuration:
   Once the test is successful, click Save SAML settings.

7. Download recovery codes (optional but recommended):
   After saving, download, print, or copy your recovery codes to ensure you can still access your enterprise if your IdP becomes unavailable. For more details, see Downloading your enterprise account's single sign-on recovery codes.
   Once the new certificate is active in your IdP, GitHub will use it for SAML authentication. If you encounter any issues during the process, let me know!

Sources
Configuring authentication and provisioning with PingFederate
Configuring SAML single sign-on for Enterprise Managed Users
Configuring SAML single sign-on for your enterprise
GitHub Corporate Terms of Service