import MarkdownAlert from "@/components/markdown/MarkdownAlert.astro";

Authentik GitHub SSO

This module configures Authentik for integration with GitHub SAML single sign-on.

Note: The GitHub Enterprise plan is required for SSO.

Due to limitations with GitHub, this module only handles authentication and does not support user provisioning or de-provisioning at this time. As a result, users will not be automatically created or removed from GitHub when they are added or removed from Authentik.

When a user is removed from Authentik, they will lose access to the organization. However, be aware of the following caveats:

• Any active session tokens that the user has with the GitHub web UI and PATs the user may have generated will not be automatically revoked. Until these tokens expire, the user may still interact with the web UI / API unless they are manually removed from the GitHub organization.

Guide

This guide sets up SAML SSO at the enterprise level, not the organization level. This is important because: - An enterprise-level integration provides SSO coverage for all organizations within your GitHub Enterprise - This eliminates the need to configure separate SSO integrations for each organization - All authentication will be managed through a single integration point

While this guide focuses on enterprise-level setup, the same steps can be followed for organization-level SSO by selecting the organization settings instead of enterprise settings in GitHub.

Start the GitHub SAML SSO Setup

1. Log in to GitHub and navigate to your enterprise's dashboard. For example, Panfactum's enterprise url is https://github.com/enterprises/Panfactum.
2. Click on your profile picture in the top right corner.
3. Select Your enterprises.
4. Click on settings for your enterprise name.
5. Go to Authentication security.
6. Toggle on Require SAML authentication.
7. Note the assertion consumer service URL. We will use this in the following step.

Deploy GitHub Provider & Application in Authentik

1. Add a new authentik_github_sso folder adjacent to your authentik_core_resources folder.
2. Add a new terragrunt.hcl file that looks like this.
3. Set the acs_url input using the assertion consumer service URL from above.
4. Run pf-tf-init.
5. Run terragrunt apply.
6. Note the output as you'll use it in the following steps.

Complete GitHub SAML single sign-on

1. Resume the Authentication security page
2. Go to Security -> Authentication security.
3. Set Sign on URL with the sso_post_url output value from above.
4. Set Issuer with the issuer_url output value from above.
5. Set Public certificate from the certificate output value from above.
6. Click on Test SAML configuration.
7. Save the recovery codes that you are prompted with.
8. Click on Save.

Test and Validate the Integration

1. Go to your Authentik instance.
2. Find the GitHub application. Ensure you are in the user dashboard, not the admin dashboard.
3. Click and confirm that you are able to login.