The Things Stack supports OpenID Connect for single sign-on. This section contains instructions for connecting an OpenID provider to your The Things Stack deployment to allow users to sign in with their existing credentials.

Requirements

1. Access to an OpenID Connect provider such as Google or Amazon Cognito
2. Administrator access to your The Things Stack deployment
3. tti-lw-cli

Configure Your OpenID Connect Provider

First, you must configure your OpenID Connect Provider to accept login requests from The Things Stack and to forward authentication to the callback address of your The Things Stack deployment.

The Things Stack requires the following from the OpenID Connect Provider:

• OpenID Discovery Address
• Client ID
• Client Secret

And you must enter the following in the OpenID Connect Provider configuration:

• Callback URL

See instructions for configuring Google and Amazon Cognito OpenID Connect Providers.

Callback URL

The callback URL (or Redirect URI in Google terminology) of your The Things Stack deployment is the Server Address followed by the OAuth endpoint, which includes an Authentication Provider ID of your choosing:

/oauth/login/<authentication-provider-id>/callback

You will actually create the Authentication Provider in The Things Stack using this Authentication Provider ID, so remember it.

For example, with a tenant tenant1 in the eu1 cluster and an Authentication Provider ID of auth-provider, the OAuth Callback URL is:

https://tenant1.eu1.cloud.thethings.industries/oauth/login/auth-provider/callback

Configure The Things Stack for SSO

Once your OpenID Connect provider is configured, you can configure The Things Stack.

Use the following command (note that Authentication Provider commands are only available in tti-lw-cli):

$ tti-lw-cli authentication-providers create <authentication-provider-id> \
--allow-registrations \
--configuration.provider.oidc.client-id <client-id> \
--configuration.provider.oidc.client-secret <client-secret> \
--configuration.provider.oidc.provider-url <provider-url> \
--name <display-name>

The name is what will appear on The Things Stack login screen. For example, to register a Google OpenID Authentication Provider, using the id goog and name Goog:

$ tti-lw-cli authentication-providers create goog \
--allow-registrations \
--configuration.provider.oidc.client-id xxxxx-vq3v4e2ha7c1668mr92iiqu0bd1spct2.apps.googleusercontent.com \
--configuration.provider.oidc.client-secret GOCSPX-Vxxxxxxx \
--configuration.provider.oidc.provider-url https://accounts.google.com \
--name Goog

A list of provider discovery URLs is available from AWS here.

If succesful, tti-lw-cli will return a list of Authentication Providers. When you go to login, you will see the login option using the name you registered the Authentication Provider with.

Troubleshooting

I get the email not verified error when logging in using SSO.

The Things Stack checks if the email address included in the JWT token has been verified by the OIDC provider (e.g. The Things ID or SSO DB), so the JWT token that the OIDC provider provides should contain the email_verified field. If this field is not present, the user might face the following error upon logging in with SSO:

{
"code": 7,
"message": "error:pkg/account/oidc:unverified_email (email not verified)",
"details": [
    {
        "@type": "type.googleapis.com/ttn.lorawan.v3.ErrorDetails",
        "namespace": "pkg/account/oidc",
        "name": "unverified_email",
        "message_format": "email not verified",
        "correlation_id": "43c2ea63620d4487b64723d03195953e",
        "code": 7
    }]
}

To fix this error, users should ask their OIDC provider to include the email_verified field in the JWT token to be used with The Things Stack SSO.