GitHub Authentication

STEP 1

Choose DEX_HOSTNAME And Configure DNS

Loft uses the CNCF project dex for single sign-on.

The easiest case is this one:

$LOFT_HOSTNAME = loft.mycompany.tld (where Loft is running)
$DEX_HOSTNAME = dex.mycompany.tld (where dex should be running)
Loft and dex should run in the same Kubernetes cluster

Then, you can set a CNAME record with value loft.mycompany.tld in the DNS configuration for dex.mycompany.tld.

STEP 2

Create A GitHub App

In GitHub, navigate to Settings > Developer Settings > OAuth Apps and create a new OAuth App with the following settings:

Application name: Loft Login via GitHub
Homepage URL: https://loft.yourcompany.tld = https:// + $LOFT_HOSTNAME
Auth callback URL: https://dex.yourcompany.tld/callback = https:// + $DEX_HOSTNAME + /callback

Remember the $GITHUB_CLIENT_ID and $GITHUB_CLIENT_SECRET that GitHub generates for your OAuth application because you will need it in the next step.

STEP 3

Create Dex Config For GitHub

Create the file dex-config.yaml with the following dex configuration:

ingress:
  enabled: true
  hosts:
  - dex.yourcompany.tld                                   # Use $DEX_HOSTNAME
config:
  issuer: https://dex.yourcompany.tld                     # "https://" + $DEX_HOSTNAME
  connectors:
  - type: github
    id: github
    name: GitHub
    config:
      clientID: XXXXXXXXXXXXXX                            # Use $GITHUB_CLIENT_ID (see above)
      clientSecret: XXXXXXXXXXXXXX                        # Use $GITHUB_CLIENT_SECRET (see above)
      redirectURI: https://dex.yourcompany.tld/callback   # Use https:// + $DEX_HOSTNAME + /callback
      orgs:
      - name: my-company-name-on-github                   # Your GitHub organization (only members can sign in via dex)
      useLoginAsID: true
      teamNameField: slug
  staticClients:
  - name: Loft
    id: loft                                              # Define a $DEX_CLIENT_ID
    secret: XXXXXXXXXXXXXX                                # Define a $DEX_CLIENT_SECRET (can be any secret key)
    redirectURIs:
    - 'https://loft.mycompany.tld/auth/oidc/callback'     # Loft URL + /auth/oidc/callback
  oauth2:
    skipApprovalScreen: true
  web:
    http: 0.0.0.0:5556
  storage:
    type: kubernetes
    config:
      inCluster: true

For details about configuring dex for GitHub, take a look at the dex documentation for GitHub.

STEP 4

Deploy Dex via Helm

After creating the file dex-config.yaml, you can now install dex via helm:

helm install dex dex --repo https://kubernetes-charts.storage.googleapis.com \
  --create-namespace --namespace dex \
  -f dex-config.yaml \
  --wait

STEP 5

Configure Loft To Use Dex For Authentication

To tell Loft to use dex for SSO, navigate to Admin > Config in Loft and adjust your config as shown below:

auth:
  oidc:
    issuerUrl: https://dex.mycompany.tld  # Use $DEX_HOSTNAME (see above)
    clientId: ""                          # Use $DEX_CLIENT_ID (see above)
    clientSecret: ""                      # Use $DEX_CLIENT_SECRET (see above)
    type: "github"                        # Optional: SSO Login Button Icon ("", github, gitlab, microsoft, google)
    usernameClaim: "email"                # Optional: Which part of the dex token to use as Loft username (default: email)
    usernamePrefix: ""                    # Optional: Add prefix to usernameClaim for Loft username
    groupsClaim: "groups"                 # Optional: Add Kubernetes groups for this user
    groupsPrefix: "loft-"                 # Optional: Prefix for Kubernetes groups
    caFile: ""                            # Optional: Path to a CA cert of dex within the Loft container (default: '')

STEP 6

Authenticate via Dex + GitHub

After saving the new Loft configuration, Loft will restart itself and you should be able to log in via GitHub and dex. Beware that only members of your organization on GitHub can sign in and that everyone must grant access to view their organization during the login process.

Must Grant Access To Organization

Users must grant access to the organization you configured dex for in step 2 above, otherwise they will not be able to log in.

STEP 7

Disable Username + Password Authentication (optional)

To disable password-based authentication, navigate to Admin > Config add these two lines to your config:

auth:
  oidc: ...             # This is your SSO configuration (make sure this is working!)
  password:
    disabled: true      # Disable password-based authentication