authentik_github_sso

Stable

Direct

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

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

Deploy GitHub Provider & Application in Authentik

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

Complete GitHub SAML single sign-on

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

Test and Validate the Integration

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

Providers

The following providers are needed by this module:

authentik (2024.8.4)
kubectl (2.1.3)
kubernetes (2.34.0)
random (3.6.3)
tls (4.0.6)

Required Inputs

The following input variables are required:

acs_url

Description: The ACS url provided by GitHub when configuring an external identity provider

Type: string

authentik_domain

Description: The domain name of the Authentik instance

Type: string

organization_name

Description: The name of your organization

Type: string

Optional Inputs

The following input variables are optional (have default values):

authentik_namespace

Description: The kubernetes namespace where Authentik is deployed

Type: string

Default: "authentik"

extra_allowed_groups

Description: Additional groups that can access GitHub

Type: set(string)

Default: []

media_configmap

Description: The ConfigMap holding the static media that Authentik will use

Type: string

Default: "media"

ui_description

Description: The description to display in the Authentik web dashboard

Type: string

Default: "GitHub"

Outputs

The following outputs are exported:

certificate

Description: The certificate used to sign SAML responses

issuer_url

Description: The Authentik issuer URL for the GitHub provider

saml_metadata

Description: The SAML metadata for the GitHub provider. https://en.wikipedia.org/wiki/SAML_metadata

sso_post_url

Description: The URL where SAML authentication requests are sent from the Service Provider (GitHub)

Maintainer Notes

No notes