sso-guide

SSO integration guidance for fort-nix services. Use when adding authentication to a service, choosing an SSO mode, configuring oauth2-proxy, or troubleshooting auth issues.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides expert guidance for implementing Single Sign-On (SSO) integrations within fort-nix services. It streamlines the process of securing exposed services by helping users select the optimal authentication mode—such as OIDC, header-based auth, or gatekeeper—and providing detailed configuration steps for oauth2-proxy and Nginx wiring.

Use Cases

  • 1. SSO Mode Selection: Use the interactive flowchart to determine whether a service should use native OIDC, X-Auth headers, or a simple Gatekeeper login wall based on its technical capabilities.
  • 2. Oauth2-Proxy Configuration: Get step-by-step instructions for configuring oauth2-proxy and Nginx to ensure seamless identity delivery and credential management.
  • 3. Troubleshooting Authentication: Quickly diagnose and resolve common integration issues, such as header mismatches or OIDC credential delivery errors, using the built-in troubleshooting guide.
  • 4. Access Control Implementation: Configure security groups and LDAP-based restrictions to manage user permissions for services exposed via fortCluster.
namesso-guide
descriptionSSO integration guidance for fort-nix services. Use when adding authentication to a service, choosing an SSO mode, configuring oauth2-proxy, or troubleshooting auth issues.

SSO Integration Guide

This skill helps you configure authentication for services exposed via fortCluster.exposedServices.

Quick Reference: SSO Modes

Mode Use When fort.nix Provides You Provide
none No auth needed, or app handles its own Plain reverse proxy Nothing
oidc App supports OIDC natively Credential delivery to /var/lib/fort-auth/<svc>/ OIDC config in app
headers App reads X-Auth-* headers oauth2-proxy + nginx wiring Header consumption in app
basicauth App only supports HTTP Basic Auth oauth2-proxy translating to Basic Basic auth config in app
gatekeeper Login wall, no identity needed oauth2-proxy blocking unauthenticated Nothing

Mode Selection Flowchart

Does the app need authentication?
├─ No → mode = "none"
└─ Yes → Does the app support OIDC natively?
         ├─ Yes → mode = "oidc" (see oidc.md)
         └─ No → Can the app read X-Auth-* headers?
                  ├─ Yes → mode = "headers" (see headers.md)
                  └─ No → Does it support HTTP Basic Auth?
                           ├─ Yes → mode = "basicauth" (see basicauth.md)
                           └─ No → Just need login gate? → mode = "gatekeeper" (see gatekeeper.md)

Detailed Mode Documentation

Common Options

All SSO modes support:

sso = {
  mode = "headers";  # or oidc, basicauth, gatekeeper
  groups = [ "admins" ];  # Planned: restrict to LDAP groups (not yet working)
};

Note: The groups option is defined in the schema but not yet functional. See fort-040 for tracking. When implemented, it will pass through to oauth2-proxy's --allowed-group flag for all SSO modes.