Authentik Github SSO (#246)

<!-- ELLIPSIS_HIDDEN -->


> [!IMPORTANT]
> Introduces `authentik_github_sso` module for Authentik-GitHub SAML SSO
integration, focusing on authentication without user provisioning.
> 
>   - **New Module**:
> - Adds `authentik_github_sso` module for integrating Authentik with
GitHub SAML SSO.
> - Handles authentication only; does not support user provisioning or
de-provisioning.
>     - Requires GitHub Enterprise plan.
>   - **Configuration**:
> - Includes `main.tf`, `vars.tf`, `outputs.tf`, and `config.yaml` for
Terraform setup.
> - Uses providers: `authentik`, `kubernetes`, `kubectl`, `random`,
`tls`.
>   - **Documentation**:
> - Adds `README.md` and `index.mdx` with setup guide and usage
instructions.
> - Updates `changelog/edge.mdx` and `modules.json` to include the new
module.
>   - **Setup Guide**:
> - Provides step-by-step instructions for configuring SAML SSO at the
enterprise level.
> - Details on deploying GitHub provider and application in Authentik.
> 
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=Panfactum%2Fstack&utm_source=github&utm_medium=referral)<sup>
for 9ff13b2. It will automatically
update as commits are pushed.</sup>


<!-- ELLIPSIS_HIDDEN -->

---------

Signed-off-by: James Lee <[email protected]>
Co-authored-by: ellipsis-dev[bot] <65095814+ellipsis-dev[bot]@users.noreply.github.com>

Author: uptownhr

packages/infrastructure/authentik_github_sso/FOOTER.md

@@ -0,0 +1,3 @@
+## Maintainer Notes
+
+No notes

packages/infrastructure/authentik_github_sso/README.md

@@ -0,0 +1,65 @@
+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](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise) is required for SSO.   
+
+<MarkdownAlert severity="warning">
+  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.
+</MarkdownAlert>
+    
+## Guide
+
+<MarkdownAlert severity="warning">
+  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.
+</MarkdownAlert>
+
+### 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.
+  1. Click on your profile picture in the top right corner.
+  2. Select `Your enterprises`.
+  3. Click on `settings` for your enterprise name. 
+2. Go to Authentication security.
+3. Toggle on `Require SAML authentication`.
+4. Note the `assertion consumer service URL`. We will use this in the following step.
+   ![GitHub ACS URL](doc_images/github-acs-url.png)
+   
+
+### 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](https://github.com/Panfactum/stack/blob/__PANFACTUM_VERSION_MAIN__/packages/reference/environments/production/us-east-2/authentik_github_sso/terragrunt.hcl).
+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.
+   ![SAML Form](doc_images/github-saml-form.png)
+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.
+   ![GitHub Application](doc_images/github-application.png)
+3. Click and confirm that you are able to login.

packages/infrastructure/authentik_github_sso/config.yaml

@@ -0,0 +1,3 @@
+type: direct
+status: stable
+group: authentik

packages/infrastructure/authentik_github_sso/doc_images/github-acs-url.png

@@ -0,0 +1,148 @@
+terraform {
+  required_providers {
+    authentik = {
+      source  = "goauthentik/authentik"
+      version = "2024.8.4"
+    }
+    kubernetes = {
+      source  = "hashicorp/kubernetes"
+      version = "2.34.0"
+    }
+    kubectl = {
+      source  = "alekc/kubectl"
+      version = "2.1.3"
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = "3.6.3"
+    }
+    tls = {
+      source  = "hashicorp/tls"
+      version = "4.0.6"
+    }
+  }
+}
+
+locals {
+  combined_allowed_groups = toset([
+    "superusers",
+    "privileged_engineers",
+    "engineers",
+    "restricted_engineers",
+  "billing_admins"], var.extra_allowed_groups...)
+
+  issuer = "https://${var.authentik_domain}"
+}
+
+###########################################################################
+## Upload the logo
+###########################################################################
+
+resource "random_id" "logo" {
+  prefix      = "github-"
+  byte_length = 8
+}
+
+resource "kubernetes_config_map_v1_data" "media" {
+  metadata {
+    name      = var.media_configmap
+    namespace = var.authentik_namespace
+  }
+  data = {
+    "${random_id.logo.hex}.svg" = file("${path.module}/github.svg")
+  }
+  field_manager = random_id.logo.hex
+  force         = true
+}
+
+###########################################################################
+## Cert Config
+###########################################################################
+
+// These certs are only used for their random cryptographic
+// material to sign the SAML assertions. There is no
+// need to use cert-manager to manage them,
+// especially since they need to be manually uploaded to github
+// every time they rotate
+resource "tls_private_key" "signing" {
+  algorithm = "RSA"
+  rsa_bits  = 4096
+}
+
+resource "tls_self_signed_cert" "signing" {
+  private_key_pem = tls_private_key.signing.private_key_pem
+  subject {
+    common_name  = var.authentik_domain
+    organization = var.organization_name
+  }
+  validity_period_hours = 24 * 365 * 10
+  allowed_uses = [
+    "key_encipherment",
+    "digital_signature",
+    "server_auth",
+  ]
+}
+
+resource "authentik_certificate_key_pair" "signing" {
+  name             = "github-signing-certs"
+  certificate_data = tls_self_signed_cert.signing.cert_pem
+  key_data         = tls_private_key.signing.private_key_pem
+}
+
+###########################################################################
+## IdP Config
+###########################################################################
+
+data "authentik_flow" "default_authorization_flow" {
+  slug = "default-provider-authorization-implicit-consent"
+}
+
+data "authentik_property_mapping_provider_saml" "email" {
+  managed = "goauthentik.io/providers/saml/email"
+}
+
+resource "authentik_provider_saml" "github" {
+  name               = "github"
+  authorization_flow = data.authentik_flow.default_authorization_flow.id
+  property_mappings  = [data.authentik_property_mapping_provider_saml.email.id]
+  acs_url            = var.acs_url
+  sp_binding         = "post"
+  issuer             = local.issuer
+  audience           = replace(var.acs_url, "/saml/consume", "")
+  name_id_mapping    = data.authentik_property_mapping_provider_saml.email.id
+  signing_kp         = authentik_certificate_key_pair.signing.id
+}
+
+resource "null_resource" "wait_for_saml_provider" {
+  depends_on = [authentik_provider_saml.github]
+
+  provisioner "local-exec" {
+    command = "sleep 10"  # Give the API time to fully create the resource
+  }
+}
+
+resource "authentik_application" "github" {
+  name              = "GitHub"
+  slug              = "github"
+  protocol_provider = authentik_provider_saml.github.id
+  meta_description  = var.ui_description
+  meta_publisher    = "Panfactum"
+  meta_icon         = "https://${var.authentik_domain}/media/public/${random_id.logo.hex}.svg"
+  open_in_new_tab   = true
+}
+
+data "authentik_group" "group" {
+  for_each = local.combined_allowed_groups
+  name     = each.key
+}
+
+resource "authentik_policy_binding" "access" {
+  for_each = local.combined_allowed_groups
+  target   = authentik_application.github.uuid
+  group    = data.authentik_group.group[each.key].id
+  order    = 10
+}
+
+data "authentik_provider_saml_metadata" "github" {
+  provider_id = authentik_provider_saml.github.id
+}

packages/infrastructure/authentik_github_sso/doc_images/github-application.png

@@ -0,0 +1,19 @@
+output "saml_metadata" {
+  description = "The SAML metadata for the GitHub provider. https://en.wikipedia.org/wiki/SAML_metadata"
+  value       = data.authentik_provider_saml_metadata.github.metadata
+}
+
+output "sso_post_url" {
+  description = "The URL where SAML authentication requests are sent from the Service Provider (GitHub)"
+  value       = authentik_provider_saml.github.url_sso_redirect
+}
+
+output "issuer_url" {
+  description = "The Authentik issuer URL for the GitHub provider"
+  value       = local.issuer
+}
+
+output "certificate" {
+  description = "The certificate used to sign SAML responses"
+  value = authentik_certificate_key_pair.signing.certificate_data
+}

packages/infrastructure/authentik_github_sso/doc_images/github-saml-form.png

@@ -0,0 +1,38 @@
+variable "media_configmap" {
+  description = "The ConfigMap holding the static media that Authentik will use"
+  type        = string
+  default     = "media"
+}
+
+variable "authentik_namespace" {
+  description = "The kubernetes namespace where Authentik is deployed"
+  type        = string
+  default     = "authentik"
+}
+
+variable "authentik_domain" {
+  description = "The domain name of the Authentik instance"
+  type        = string
+}
+
+variable "organization_name" {
+  description = "The name of your organization"
+  type        = string
+}
+
+variable "acs_url" {
+  description = "The ACS url provided by GitHub when configuring an external identity provider"
+  type        = string
+}
+
+variable "ui_description" {
+  description = "The description to display in the Authentik web dashboard"
+  type        = string
+  default     = "GitHub"
+}
+
+variable "extra_allowed_groups" {
+  description = "Additional groups that can access GitHub"
+  type        = set(string)
+  default     = []
+}