Authenticating with an external identity provider

A guide to setting up an external identity provider for use with the dashboard

Prior to starting

Before you start to configure OpenID Connect you should make sure you have the appropriate configuration for integrating with an external provider:

If you use a reverse proxy or load balancer ensure your external URL details are specified in the proxy settings in the configuration including the secure flag
Ensure your cookie configuration is set to same site 'none' and secure
Ensure your Dashboard users all have valid email addresses assigned, this will be used as the identifier
Ensure users have external login enabled

Please note you can only assign one identity provider of each type to the Dashboard.

Technology

We support OpenID Connect and SAML, as well as Integrated Windows Authentication in internal Microsoft environments. We recommend OpenID Connect as a modern and open standard.

Providers

We follow the standards defined for each technology so that we have broad compatibility out of the box but given the huge number of possible providers we limit our testing to a number of popular ones. Occasionally the implementation by a provider will differ slightly from what we expect so we aim to provide maximum configurability within the Dashboard so we can easily handle this.

Setup

Generally the process of setup involves creating an “application” within the identity provider, setting the appropriate options for your chosen mode of authentication and then providing the connection details and secrets to the Dashboard. The OpenID Connect and SAML sections below provide more specific detail. You will need to allow a reply URL for the Dashboard which will be https://dashboard.company.com/pi/auth/oAuthComplete (the bold part will differ).

OpenID Connect

You will need to setup a web application with the Authorization Code Flow that provides an OpenID Connect compatible token. The scopes required could be email and/or openid. You will need to capture the authentication URL and token URL as well as a set of keys, a username and password effectively (the username could be an app id or similar). Once you have the required details you can set them up in the Dashboard. If you are not sure if your setup is correct we have a debugging tool which can be used to run through the authentication process outside of the Dashboard and advise on issues with the configuration.

Provider	Variables

Provider	Variables
Microsoft Azure AD	OAUTH_ENABLED: TRUE OAUTH_PROVIDER: microsoft OAUTH_BASE_URL: https://login.microsoftonline.com/TENANT (or /common) OAUTH_API_KEY: Application ID OAUTH_API_SECRET: API Secret OAUTH_AUTH_URL: (blank) OAUTH_TOKEN_ENDPOINT: (blank)
Auth0	OAUTH_ENABLED: TRUE OAUTH_PROVIDER: auth0 OAUTH_BASE_URL: https://company.eu.auth0.com OAUTH_API_KEY: Client ID OAUTH_API_SECRET: Client Secret OAUTH_AUTH_URL: (blank) OAUTH_TOKEN_ENDPOINT: (blank)
Keycloak	OAUTH_ENABLED: TRUE OAUTH_PROVIDER: keycloak OAUTH_BASE_URL: https://server:port/auth/realms/realm/ OAUTH_API_KEY: Client ID OAUTH_API_SECRET: Client Secret OAUTH_AUTH_URL: (blank) OAUTH_TOKEN_ENDPOINT: (blank)
AWS Cognito	OAUTH_ENABLED: TRUE OAUTH_PROVIDER: custom OAUTH_BASE_URL: https://DOMAIN.auth.region.amazoncognito.com OAUTH_API_KEY: Cognito App client id OAUTH_API_SECRET: Cognito App client secret OAUTH_AUTH_URL: https://DOMAIN.auth.region.amazoncognito.com/login OAUTH_TOKEN_ENDPOINT: https://DOMAIN.auth.region.amazoncognito.com/oauth2/token
Google	OAUTH_ENABLED: TRUE OAUTH_PROVIDER: custom OAUTH_BASE_URL: https://accounts.google.com/o/oauth2/v2/auth OAUTH_API_KEY: Client ID OAUTH_API_SECRET: Client Secret OAUTH_AUTH_URL: https://accounts.google.com/o/oauth2/v2/auth OAUTH_TOKEN_ENDPOINT: https://oauth2.googleapis.com/token
Azure B2C	OAUTH_ENABLED: TRUE OAUTH_PROVIDER: custom OAUTH_BASE_URL: https://TENANT.b2clogin.com/TENANT.onmicrosoft.com/POLICY OAUTH_API_KEY: Client ID OAUTH_API_SECRET: Client Secret OAUTH_AUTH_URL: https://TENANT.b2clogin.com/TENANT.onmicrosoft.com/POLICY/oauth2/v2.0/authorize OAUTH_TOKEN_ENDPOINT: https://TENANT.b2clogin.com/TENANT.onmicrosoft.com/POLICY/oauth2/v2.0/token OAUTH_SCOPE: CLIENT_ID openid email

AWS Cognito - please replace the text 'region’ with the name of the region where you’re based e.g. us-east or eu-west-1.

Auto login

Auto login to the dashboard via OpenID Connect can be achieved by using the /auth/oidc URL. If the variable OAUTH_LOGIN_SCREEN_BYPASS exists and is set to true the login screen will be bypassed by default. If direct access to the login screen is needed it can be reached via the /login URL.

Logout Integration

If you would like a Dashboard log out to be integrated with your identity provider you can set the OAUTH_LOGOUT_URL field and the user will be redirected there, logged and, and redirected back to the Dashboard logo out screen.

SAML

You will need to setup a web application with support for SAML and allow a reply URL for the Dashboard which will be https://dashboard.company.com/pi/auth/samlComplete (the bold part will differ). The SAML response will need to contain the emailaddress claim.

You can then provide the details to the Dashboard:

SAML_ENABLED: true

SAML_SP_ENTITY_ID: (Service Provider Entity ID URI)

SAML_IDP_ENTITY_ID: (Identity Provider Entity ID URI)

SAML_IDP_SSO_URL: (SSO endpoint of the Identity Provider)

SAML_IDP_X509_CERT: (x509 public certificate of the Identity Provider)

Auto login

Auto login to the dashboard via SAML can be achieved by using the /auth/startSaml URL. If the variable SAML_LOGIN_SCREEN_BYPASS exists and is set to true the login screen will be bypassed by default. If direct access to the login screen is needed it can be reached via the /login URL.