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.

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.