🚧
IDP-initiated SSO has been deprecated and is no longer supported by Lytics

Overview

Single Sign-On (SSO) allows employees to safely and securely access a host of Internet tools with a single username and password. There are four primary reasons why your business should consider leveraging Single Sign-On:

SSO helps the end user. Implementing SSO means employees are required to commit just one password to memory. With one password to remember, a user can easily create and remember a unique and secure password without writing it down. SSO reduces password fatigue and frustration and makes the employee more efficient.
SSO benefits the company. Fewer passwords to remember equals fewer calls to the helpdesk, resulting in more time spent on other tasks for both the end user and IT. Fewer calls to the helpdesk (which is oftentimes outsourced) means a reduction in cost to the company as well.
SSO improves security. When employees are required to remember numerous passwords, it is easy to fall into lazy habits, such as using simple, easy-to-remember passwords, which are more susceptible to hacking. Or writing passwords down on Post-it notes where they can easily be stolen or fall into the wrong hands.
SSO helps with compliance. SSO helps companies increase control over the user's access to certain information as well as easily enforce password change policies. This makes it simpler for organizations to comply with HIPAA, SOX, and other regulatory groups.

SP-Initiated SSO

Lytics supports enterprise Single Sign-On (SSO) by using Google Cloud Identity Platform as a service provider using SAML protocol. Lytics integrates with Identity Providers (IdPs) in such a way that the Service Provider (SP) initiates SSO.

Once implemented, users will log in to Lytics via a special SSO form that only requires an email address. Lytics will recognize the email address and open a pop-up to the user's IdP to complete the login. Once the IdP verifies credentials, the pop-up will close, redirecting the user to a logged-in instance of their Lytics dashboard. Behind the scenes, a customer's IdP will communicate with the Lytics APIs, which use Google Cloud Identity Platform to validate the login. This document describes the process for integrating with a new IdP that uses SAML.

Service Provider Configuration

To configure SAML for the Lytics service provider, some information is required about your IdP. If you have a metadata file that contains SAML provider information, this may be appropriate, but please ensure that the following information is provided to Lytics Support:

Entity ID
Sign In URL
X509 Signing Certificate

Further configuration details, such as mappings, may need to be provided, but the Lytics implementation only requires the email address field to be mapped. Once this information has been received, Lytics can configure the SAML connection in the Google Cloud Identity Platform.

IdP Configuration

After Lytics configures the SAML connection on the service provider, Lytics Support will provide the following key fields of information to the customer to complete the configuration in their IdP.

Assertion Consumer Service (ACS) URL (aka postback or callback URL)
Entity ID of the Service Provider
Sign-in URL

With this information, your IdP connection can be configured to complete the SSO integration.

📘
At this time, Lytics does not support providing this information in an XML metadata file. Additional information about the Service Provider may be provided on request.

Testing SSO

Once all the information has been configured in both the IdP and the Lytics service provider, you can test and verify that the SSO implementation works as expected. If you are using SSO as your only sign-in method, please disable any password restriction or expiration settings that may have been enabled in the UI.

During the testing process, Lytics can be configured to allow both SSO login and regular username and password (or Google OAuth) login through the app. This allows users to test SSO without disrupting the day-to-day usage of the app.

If requested, once the SSO implementation has been tested and verified, Lytics can disable the use of other login types for an account.

Troubleshooting SSO

If it's known that SSO will be added to an account, the user email addresses added to the account should match the email address present within the IdP. If the email address doesn’t match, the login will fail as Lytics will not be able to verify that there is a user with that email address.

For instance, if the email listed in the IdP is abc@123 and within Lytics, it is def@456, then there will be potentially multiple error points for a user trying to log in via the SSO form on Lytics.

If the user enters abc@123 into the IdP pop-up, it will immediately fail as we use the Lytics account user to determine which IdP to redirect to. You would see an error message like the following:

SSO Error State

However, should the user enter def@456 (their Lytics account email), they will be redirected to their IdP, but the verification of the login will fail once information is sent back to Lytics.

To remedy this situation, you would need to create a new user within Lytics with the email address abc@123 for the SSO login to be successful. You can check, add, and remove users for an account using the Managing Users guide as a reference.

Lytics Support can assist in the troubleshooting process. When testing for the first time, Lytics can enable logging to help troubleshoot any issues you encounter. With this, the team can help debug if you provide information on the login attempt, such as the login time, user, and account.

If you’re encountering a verification error, but you've checked that your emails from the IdP and Lytics match, this may be an issue with the SAML configuration either on the IdP or SP side. Contact Lytics Support with details of the issue, and our team can coordinate a fix.

Account Structure with SSO

It should also be noted that primary accounts (master accounts) are decided as the first account that a user was added to. Due to this, users from a single group/organization will often have different primary accounts. This is important for SSO as it will also be the account the user is logged into at the start of their session. If SSO is enabled as the only means of login on one account and a user attempts to log in using Google OAuth or their username and password, the login session will fail. The following options are possible solutions:

Add that user to your IdP.
Add other methods of logging in (Google OAuth, username/password).
Remove that user from all accounts and then add them back, with the first account being the account that you want to be their primary account.

Implementing SSO with Okta

This document will walk you through how to implement Single Sign-On to the Lytics application with Okta as an identity provider. Lytics has applied to become an official Okta partner application. Still, while the partnership is being established, you can follow these instructions to set up the custom application in Okta, which covers the IDP configuration portion of the implementation.

From your Okta Administration panel, navigate to Applications and then Add Application and Create New App.
Under Platform, select Web, and for Sign on Method, choose SAML 2.0.
Under General Settings, you can enter the following values:
- App name: Lytics
- App Logo: You can save and upload the following image of the Lytics Logo:
Under SAML Settings, enter the following values:
- Single Sign-on URL: https://app.lytics.com/login/sso
  Make sure Use this for Recipient URL and Destination URL is not selected). Also select Allow this app to request other SSO URLs to enable more URLs to be added.
- Requestable SSO URLs: Add the following two URLs:
  - https://api.lytics.io/api/user/verifyauth (index 0)
  - https://app.lytics.com/login/sso (index 1)
- Recipient URL: https://api.lytics.io/api/user/verifyauth
- Destination URL: https://api.lytics.io/api/user/verifyauth
- Audience URI (SP Entity ID): app.lytics.com
- Name ID format: EmailAddress
Click through the next step, and select Finish.
You can add users to view this application in their portal using the Assignments tab.
Navigate to the Sign On tab. And under settings, click on View Setup Instructions.
You will need to gather the information on this page and send it to Lytics for configuration of the Service Provider:
- Identity Provider Single Sign-On URL
- Identity Provider Issuer
- X.509 Certificate

Once Lytics has completed the service provider implementation, you may begin to test the SSO implementation through your Okta portal.

Implementing SSO with OneLogin

This document will walk you through how to implement Single Sign-On to the Lytics application with OneLogin as an identity provider. You can follow these instructions to set up the custom application in OneLogin, which covers the IDP configuration portion of the implementation.

From the Administration menu, select Applications and then click Add App. Search for SAML Test Connector (Advanced) and select that app type.
Under Configuration > Portal enter the following:
- Display Name: Lytics
- Make sure Visible in Portal is selected.
- For the rectangular icon, you can save and upload the following image:
- For the square icon, you can save and upload the following image:
Click Save to continue to the configuration process. Then click on the Configuration tab to set up the SAML details.
Enter the following into the Application details:
- Audience (EntityID): app.lytics.com
- Recipient: https://api.lytics.io/api/user/verifyauth
- ACS (Consumer) URL Validator: ^https:\/\/api.lytics.io\/api\/user\/verifyauth
- ACS (Consumer) URL: https://api.lytics.io/api/user/verifyauth
- Login URL: https://app.lytics.com/login/sso
- SAML initiator: Service Provider
- SAML nameID format: Email
Click on the Save to save your configuration changes.
You may configure any additional access details, such as users accessing this app in their portal for testing the integration under the User tab.
Click on the SSO tab, and you will need to gather the information on this page and send it to Lytics for configuration of the Service Provider:
- X.509 Certificate (click View Details to see the full cert).
- Issuer URL
- SLO Endpoint (HTTP)

Once Lytics has completed the service provider implementation, you may begin to test the SSO implementation through your OneLogin portal.