SSO Authentication

This feature is available in v0.5+

Intro

Warpgate can use arbitrary OpenID Connect (OIDC) providers to authenticate users based on their verified emails.

OIDC providers include, but are not limited to:

• Google Accounts
• Sign in with Apple
• GitLab
• Microsoft Azure
• Okta

Configuration

External host setting

To use SSO, Warpgate needs to know what its external hostname is. It'll try its best to figure it out based on the client's request, but it's better if you set it explicitly via the top-level external_host config option:

+ external_host: warpgate.acme.inc

external_host can include a port as well

SSO Providers

Obtaining app credentials from a provider

You'll need to register your Warpgate instance as an "app" (terminology varies per provider) at the provider and obtain a Client ID and a Client secret. You'll need to provide a Redirect URL which - which will be verified by the SSO provider.

The redirect URL for Warpgate is https://<warpgate-external-host>/@warpgate/api/sso/return.

Okta provides excellent guides on registering an app with various providers:

• Google
• Apple
• GitLab
• Microsoft Azure

Adding credentials to the config file

With a Client ID and a Client Secret in hand, you can add these to the Warpgate config file:

Google

external_host: warpgate.acme.inc:8888

+ sso_providers:
+ - name: google
+   label: Google login
+   provider:
+     type: google
+     client_id: 1234...
+     client_secret: ABC...

Apple

external_host: warpgate.acme.inc:8888

+ sso_providers:
+ - name: apple
+   label: Apple ID
+   provider:
+     type: apple
+     client_id: 1234...
+     client_secret: ABC...

Microsoft Azure

external_host: warpgate.acme.inc:8888

+ sso_providers:
+ - name: azure
+   provider:
+     type: azure
+     client_id: 123...
+     client_secret: ABC...
+     tenant: XYZ...

Custom

external_host: warpgate.acme.inc:8888

+ sso_providers:
+ - name: custom
+   label: ACME SSO
+   provider:
+     type: custom
+     client_id: 123...
+     client_secret: ABC...
+     issuer_url: https://sso.acme.inc,
+     scopes: ["email"],

Requiring SSO for a user

Users are linked to their SSO accounts based on their email. If the SSO provider advertises email verification status, Warpgate will require the email to be verified.

To link a user to SSO add a new credentials entry:

  users:
  - username: cwilde
    credentials:
    ... 
+   - type: sso
+     provider: azure
+     email: [email protected]
+   require:
+     http: [sso]
+     ssh: [web]

Here, we've also set SSO to be the only required login credential for HTTP auth, and have set SSH to use out-of-band web authentication. You can omit the provider key if there's only one provider, or if you don't care which provider confirms the user's e-mail.

web (OOB web authentication) means that Warpgate will send a login link to the SSH client and will wait for the user to authenticate themselves in a browser. The auth requirements will be the same as set for the http protocol.

With the config file updated, run warpgate check to verify it.

❯ ssh cwilde:[email protected] -p 2222   
----------------------------------------------------------------
Warpgate authentication: please open https://warpgate.acme.inc:8888/@warpgate#/login/31282192-ad29-4fa7-bdc2-5b481d531e58 in your browser
----------------------------------------------------------------

(cwilde:[email protected]) Press Enter when done: