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:

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