Merge pull request 'add oidc support' (#3) from oidc into main

Reviewed-on: coop-cloud/headscale#3

.env.sample

@@ -7,8 +7,21 @@ DOMAIN=headscale.example.com
 
 LETS_ENCRYPT_ENV=production
 
+COMPOSE_FILE="compose.yml"
+
 # Defines the base domain to create the hostnames for MagicDNS.
 BASE_DOMAIN=f0x.lan
 
+
+# set this to true to enable using the built-in DERP rather than tailscale's
+ENABLE_DERP=false
+
+# enable oidc
+# OIDC_ENABLED=1
+# OIDC_ISSUER=https://authentik.example
+# SECRET_OIDC_CLIENT_KEY_VERSION=v1
+# COMPOSE_FILE="$COMPOSE_FILE:compose.oidc.yml"
+
 # See https://git.coopcloud.tech/coop-cloud/backup-bot-two
 ENABLE_BACKUPS=true
+

.gitignore

@@ -1 +1,2 @@
 .envrc
+*~

abra.sh

@@ -1,3 +1,3 @@
 # Set any config versions here
 # Docs: https://docs.coopcloud.tech/maintainers/handbook/#manage-configs
-export CONFIG_YAML_VERSION=v3
+export CONFIG_YAML_VERSION=v4

compose.oidc.yml

@@ -0,0 +1,10 @@
+---
+services:
+  app:
+    secrets:
+      - oidc_client_key
+
+secrets:
+  oidc_client_key:
+    external: true
+    name: ${STACK_NAME}_oidc_client_key_${SECRET_OIDC_CLIENT_KEY_VERSION}

config.yaml.tmpl

@@ -75,7 +75,7 @@ derp:
   server:
     # If enabled, runs the embedded DERP server and merges it into the rest of the DERP config
     # The Headscale server_url defined above MUST be using https, DERP requires TLS to be in place
-    enabled: false
+    enabled: {{ env "ENABLE_DERP" }}
 
     # Region ID to use for the embedded DERP server.
     # The local DERP prevails if the region ID collides with other region ID coming from
@@ -326,76 +326,78 @@ unix_socket: /var/run/headscale/headscale.sock
 unix_socket_permission: "0770"
 
 # OpenID Connect
-# oidc:
-#   # Block startup until the identity provider is available and healthy.
-#   only_start_if_oidc_is_available: true
-#
-#   # OpenID Connect Issuer URL from the identity provider
-#   issuer: "https://your-oidc.issuer.com/path"
-#
-#   # Client ID from the identity provider
-#   client_id: "your-oidc-client-id"
-#
-#   # Client secret generated by the identity provider
-#   # Note: client_secret and client_secret_path are mutually exclusive.
-#   client_secret: "your-oidc-client-secret"
-#   # Alternatively, set `client_secret_path` to read the secret from the file.
-#   # It resolves environment variables, making integration to systemd's
-#   # `LoadCredential` straightforward:
-#   client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret"
-#
-#   # The amount of time a node is authenticated with OpenID until it expires
-#   # and needs to reauthenticate.
-#   # Setting the value to "0" will mean no expiry.
-#   expiry: 180d
-#
-#   # Use the expiry from the token received from OpenID when the user logged
-#   # in. This will typically lead to frequent need to reauthenticate and should
-#   # only be enabled if you know what you are doing.
-#   # Note: enabling this will cause `oidc.expiry` to be ignored.
-#   use_expiry_from_token: false
-#
-#   # The OIDC scopes to use, defaults to "openid", "profile" and "email".
-#   # Custom scopes can be configured as needed, be sure to always include the
-#   # required "openid" scope.
-#   scope: ["openid", "profile", "email"]
-#
-#   # Only verified email addresses are synchronized to the user profile by
-#   # default. Unverified emails may be allowed in case an identity provider
-#   # does not send the "email_verified: true" claim or email verification is
-#   # not required.
-#   email_verified_required: true
-#
-#   # Provide custom key/value pairs which get sent to the identity provider's
-#   # authorization endpoint.
-#   extra_params:
-#     domain_hint: example.com
-#
-#   # Only accept users whose email domain is part of the allowed_domains list.
-#   allowed_domains:
-#     - example.com
-#
-#   # Only accept users whose email address is part of the allowed_users list.
-#   allowed_users:
-#     - alice@example.com
-#
-#   # Only accept users which are members of at least one group in the
-#   # allowed_groups list.
-#   allowed_groups:
-#     - /headscale
-#
-#   # Optional: PKCE (Proof Key for Code Exchange) configuration
-#   # PKCE adds an additional layer of security to the OAuth 2.0 authorization code flow
-#   # by preventing authorization code interception attacks
-#   # See https://datatracker.ietf.org/doc/html/rfc7636
-#   pkce:
-#     # Enable or disable PKCE support (default: false)
-#     enabled: false
-#
-#     # PKCE method to use:
-#     # - plain: Use plain code verifier
-#     # - S256: Use SHA256 hashed code verifier (default, recommended)
-#     method: S256
+{{ if eq (env "OIDC_ENABLED") "1" }}
+oidc:
+  # Block startup until the identity provider is available and healthy.
+  only_start_if_oidc_is_available: true
+
+  # OpenID Connect Issuer URL from the identity provider
+  issuer: {{ env "OIDC_ISSUER" }}
+
+  # Client ID from the identity provider
+  client_id: "headscale"
+
+  # Client secret generated by the identity provider
+  # Note: client_secret and client_secret_path are mutually exclusive.
+  # client_secret: {{ env "OIDC_CLIENT_SECRET" }}
+  # Alternatively, set `client_secret_path` to read the secret from the file.
+  # It resolves environment variables, making integration to systemd's
+  # `LoadCredential` straightforward:
+  client_secret_path: "/run/secrets/oidc_client_key"
+
+  # The amount of time a node is authenticated with OpenID until it expires
+  # and needs to reauthenticate.
+  # Setting the value to "0" will mean no expiry.
+  expiry: 7d
+
+  # Use the expiry from the token received from OpenID when the user logged
+  # in. This will typically lead to frequent need to reauthenticate and should
+  # only be enabled if you know what you are doing.
+  # Note: enabling this will cause `oidc.expiry` to be ignored.
+  use_expiry_from_token: false
+
+  # The OIDC scopes to use, defaults to "openid", "profile" and "email".
+  # Custom scopes can be configured as needed, be sure to always include the
+  # required "openid" scope.
+  scope: ["openid", "profile", "email"]
+
+  # Only verified email addresses are synchronized to the user profile by
+  # default. Unverified emails may be allowed in case an identity provider
+  # does not send the "email_verified: true" claim or email verification is
+  # not required.
+  email_verified_required: true
+
+  # Provide custom key/value pairs which get sent to the identity provider's
+  # authorization endpoint.
+  # extra_params:
+  #  domain_hint: example.com
+
+  # Only accept users whose email domain is part of the allowed_domains list.
+  # allowed_domains:
+  #   - example.com
+
+  # Only accept users whose email address is part of the allowed_users list.
+  # allowed_users:
+  #   - alice@example.com
+
+  # Only accept users which are members of at least one group in the
+  # allowed_groups list.
+  # allowed_groups:
+  #   - /headscale
+
+  # Optional: PKCE (Proof Key for Code Exchange) configuration
+  # PKCE adds an additional layer of security to the OAuth 2.0 authorization code flow
+  # by preventing authorization code interception attacks
+  # See https://datatracker.ietf.org/doc/html/rfc7636
+  pkce:
+    # Enable or disable PKCE support (default: false)
+    enabled: true
+
+    # PKCE method to use:
+    # - plain: Use plain code verifier
+    # - S256: Use SHA256 hashed code verifier (default, recommended)
+    method: S256
+{{ end }}
 
 # Logtail configuration
 # Logtail is Tailscales logging and auditing infrastructure, it allows the