Groups are case-sensitive and mapped by UUID with Azure

Integrate your user-groups with Lenses using the Azure group IDs. Create a group in Lenses using the UUID as the name.

For example, if the Engineers group has the UUID ae3f363d-f0f1-43e6-8122-afed65147ef8, create a group with the same name.

Set up Microsoft Azure SSO

Learn more about Azure SSO

Add from Azure app-gallery

1. Go to Enterprise applications > + New Application

2. Search for Lenses.io in the gallery directory

3. Choose a name for Lenses e.g. Lenses.io and click Add

4. Select Set up single sign on > SAML

5. Configure the SAML details

1. Download the Federation Metadata XML file with the Azure IdP details. You will reference this file’s path in the Lenses security.conf configuration file.

lenses.security.saml.base.url="https://lenses-dev.example.com"
lenses.security.saml.idp.provider="azure"
lenses.security.saml.idp.metadata.file="/path/to/AzureIDPMetadata.xml"
lenses.security.saml.keystore.location="/path/to/keystore.jks"
lenses.security.saml.keystore.password="my_keystore_password"
lenses.security.saml.key.password="my_saml_key_password"

Groups are case-sensitive and mapped by name with Okta

Integrate your user-groups with Lenses using the Okta group names. Create a group in Lenses using the same case-sensitive group name as in Okta.

For example, if the Engineers group is available in Okta, create a group with the same name.

Set up Okta IdP

Lenses is available directly in Okta’s Application catalog.

Add application in the Catalog

1. Go to Applications > Applications

2. Click Add Application

3. Search for Lenses

4. Select by pressing Add

Set General Settings

1. App label: Lenses

2. Set the base url of your lenses installation e.g. https://lenses-dev.example.com

3. Click Done

Download IdP XML file

Download the Metadata XML file with the Okta IdP details.

1. Go to Sign On > Settings > SIGN ON METHODS

2. Click on Identity Provider metadata and download the XML data to a file.

3. You will reference this file’s path in the security.conf configuration file.

lenses.security.saml.idp.metadata.file="/path/to/OktaIDPMetadata.xml"

Google doesn't expose the groups, or organization unit, of a user to a SAML app. This means we must set up a custom attribute for the Lenses groups that each user belongs to.

Create a custom attribute for Lenses groups

1. Open the Google Admin console from an administrator account.

2. Click the Users button

3. Select the More dropdown and choose Manage custom attributes

4. Click the Add custom attribute button

5. Fill the form to add a Text, Multi-value field for Lenses Groups, then click Add

Assign Lenses groups attributes to Google users

1. Open the Google Admin console from an administrator account.

2. Click the Users button

3. Select the user to update

4. Click User information

5. Click the Lenses Groups attribute

6. Enter one or more groups and click Save

Add Google custom SAML app

Learn more about Google custom SAML apps

1. Open the Google Admin console from an administrator account.

2. Click the Apps button

3. Click the SAML apps button

4. Select the Add App dropdown and choose Add custom SAML app

App Details

1. Enter a descriptive name for the Lenses installation

2. Upload a Lenses icon

Download IdPXML file

Configure in security.conf.

lenses.security.saml.base.url="https://lenses-dev.example.com"
lenses.security.saml.idp.provider="google"
lenses.security.saml.idp.metadata.file="/path/to/GoogleIDPMetadata.xml"
lenses.security.saml.keystore.location="/path/to/keystore.jks"
lenses.security.saml.keystore.password="my_keystore_password"
lenses.security.saml.key.password="my_saml_key_password"

Groups are case-sensitive and mapped to roles, by name, with OneLogin

Integrate your user roles with Lenses using the Keycloak role names. Create a group in Lenses using the same case-sensitive role name as in OneLogin.

For example, if the Engineers role is available in OneLogin, create a group with the same name.

Set up OneLogin IdP

Lenses is available in the OneLogin Application catalog.

Visit OneLogin’s Administration console. Select Applications > Applications > Add App

1. Search and select Lenses

2. Optionally add a description and click save

Add Lenses via the Application Catalog

1. In the Configuration section set the base path from the url of the Lenses installation e.g. lenses-dev.example.com ( without the https://)

2. Click Save

Download the IdP XML file

1. Use the More Actions button

2. Click and download the SAML Metadata

3. You will reference this file’s path in the security.conf configuration file.

lenses.security.saml.idp.metadata.file="/path/to/OneLoginIDPMetadata.xml"

1. Enable TLS (SSL) for Lenses HTTPS.

2. Create a keystore for SAML.

3. Choose your identity provider (IdP):

Set the following in the security.conf

lenses.security.saml.keystore.location = "/path/to/lenses.p12"
lenses.security.saml.keystore.password = "my_password"
lenses.security.saml.key.password = "my_password"

Integrate your user groups with Lenses using the Keycloak group names. Create a group in Lenses using the same case-sensitive group name as in Keycloak.

For example, if the Engineers group is available in Keycloak, with Lenses assigned to it, create a group with the same name.

Create a new SAML application client in Keycloak

1. Go to Clients

2. Click Create

3. Fill in the details: see the table below.

4. Click Save

Change the settings on client you just created to:

Map user groups

Configure Keycloak to communicate groups to Lenses. Head to the Mappers section.

1. Click Create

2. Fill in the details: see table below.

3. Click Save

Download IdP XML file

Configure in the security.conf file.

lenses.security.saml.idp.metadata.file="/path/to/KeycloakIDPMetadata.xml"

Authentication instances too old or in the future

The error that you see

Authentication issue instant is too old or in the future

What causes it

1. The user’s session in the SSO provider is too old.

2. The system clocks of the SSO provider and the Lenses instance are out of sync.

For security purposes, Lenses prevents authenticating SSO users that have remained logged in SSO for a very long time.

Example: You use Okta SSO and, you logged in to Okta a year ago. Okta might allow you to remain logged in along that year without having to re-authenticate. Lenses has a limit of 100 days. In that case, Lenses will receive an authenticated user that originally logged in before the 100 days mark.

How to solve it

1. Ensure that the SSO and Lenses system clocks are in sync.

2. If the SSO provider supports very long sessions either:

   1. Log out of the SSO and log back in. This explicitly renews the SSO session.

   2. Increase the Lenses limit to more than 100 days.

Example:

lenses.security.saml.idp.session.lifetime.max = 365days