Single Sign-on

Single sign-on (SSO) is a user-authentication technique that makes it more convenient to maintain security without constantly entering credentials. Kentik’s implementation of SSO is covered in the following topics:

• About SSO
• SSO Config Prerequisites
• Kentik SSO Configuration
• SSO Login Process
• Migrating to SSO

Note: This article covers SSO configuration for both of the following (for more detail, see SSO Configuration Overview):
- Admin and Member users (see About Users) of the Kentik Detect portal.
- Users assigned (by a Kentik customer) to a tenant of the My Kentik Portal.

The basics of SSO are covered in the following topics:

• SSO Overview
• SSO Identity Providers
• How SSO Works

Kentik has enabled single sign-on for the V3 Kentik Detect portal. That means Kentik users are now able access the portal via the same authentication services that they use for other SSO-enabled applications, allowing them to access many services with just one sign-on.

Kentik’s new SSO implementation is (exclusively) compliant with standard SAML2 transport, which is sometimes referred to as “Federated Identity Management.” In the SAML2 terminology:

• Kentik is the “service provider” (SP).
• Your SSO is the “identity provider” (IdP).

Kentik’s SSO implementation has been successfully tested with the following identity providers:

SSO is conceptually quite simple. Each Kentik customer (organization) sets up an identity provider that keeps track of who in the company has permission to access Kentik Detect. (These Kentik users may be categorized into groups to facilitate differentiated management by role.) As shown in the following diagram, when a user attempts to log into the portal via the SSO login URL, Kentik finds the IdP in the company’s Kentik Detect SSO settings and contacts the IdP to request verification of the user. If the IdP is able to authenticate the user, a SAML2 response is returned to Kentik and Kentik logs the user in. If the IdP can’t authenticate, the user is unable to access the portal via SSO.

Two prerequisites must be met before you can successfully configure your Kentik account for SSO:

• Identity provider account: You must have one of the following:
  - Existing identity provider account: An account with an existing SAML2 identity provider (e.g. Okta, OneLogin, Ping Federate, Google GSuite, Duo, etc.) and a directory of users.
  - In-house identity management: A self-operated SAML2-compatible IdP or identity gateway, such as Shibboleth.
  Note: For users requiring LDAP or Active Directory as an authentication backend, we recommend Shibboleth, which has open source LDAP and AD extensions.
• Kentik Super Admin user: The user level of at least one user in your organization must be Super Admin.

Super Admin users are equivalent to Admin users, with the following additional privileges:

• They can configure SSO from the portal’s Single Sign-on page (Admin » Single Sign-on).
• When SSO is required, Super Admins are the only ones who can still use non-SSO login (e.g. username + password, or username + password + 2FA), allowing a Super Admin to disable SSO in case of an identity provider failure.
• They can turn other users into Super Admin users.

To prevent a single point of failure, we recommend that you set up two Super Admins so that when one is unavailable you can still reach the other. We don’t recommend more than two, however, because it’s wise to restrict the number of users that are allowed to log in using the traditional username/password approach.

Any Admin-level user in a given organization can check who the Super Admin users are by looking at the Level column in the User List (Admin » Users). If no user is a Super Admin, please contact Kentik support (support@kentik.com) to request that a Super Admin be designated for your organization.

Note: If your organization signed up with Kentik prior to October 2017, the first user registered to your account will be automatically set as a Super Admin (to change, go to Admin » Users).

Configuration of SSO in Kentik Detect is covered in the following topics:

• SSO Types
• SSO Configuration Overview
• Add Kentik To Your IdP
• Configure IdP Settings in Kentik
• Configure User Level Behavior
• Configure Auto-provisioning
• Additional Configuration Options

Note: You must be a Super Admin user to configure SSO in Kentik Detect.

Kentik enables two distinct types of SSO for two distinct groups of users:

• Direct-user SSO: SSO for Admin and Member users (see About Users) of the Kentik Detect portal, for whom SSO is managed from the Kentik portal’s Single Sign-on page (choose Admin from the portal navbar, then choose Single Sign-on in the sidebar at left).
• Tenant SSO: SSO for users who are assigned by your organization to a tenant of the My Kentik Portal (see About Tenancy). SSO for all tenants in your organization is managed from the My Kentik Portal Single Sign-on page, which is accessed via the My Kentik Portal Single Sign-on Settings link at the bottom of the Tenant Defaults pane of the My Kentik Portal Page (Admin » My Kentik Portal).

Some of the configuration steps described in the topics below are performed in your identity provider’s management app while others, depending on SSO type (direct-user SSO or tenant SSO), involve one of the portal pages mentioned in SSO Types.

The settings available on the two SSO configuration pages in the portal are nearly identical, with the following exceptions:

• User Level Attrib. Key: Present for direct-user SSO (see Configure User Level Behavior), not present for tenant SSO.
• IDP Profile Tenant ID field: Present for tenant SSO (see Configure IdP Settings in Kentik), not present for direct-user SSO.

On both pages, the settings are divided into two main sections: a set of switches at top and a set of fields below. Before configuration, check that the SSO Enabled switch at top is set to Off (default), so that you can complete the settings before actually turning on SSO.

Once you’ve completed all of your settings as described in the topics below, you can begin using SSO by setting the SSO Enabled switch to On. If needed you can turn SSO off at any time without losing any of the settings you’ve made.

SSO involves two-way communication between Kentik and the identity provider, which requires that each is aware of the other. The information you’ll need to configure your IdP to recognize Kentik Detect as a service provider (SP) is found in the first two fields, which are read-only:

• SP Entity Id: A unique identifier for Kentik.
• SP ACS Url: The endpoint of the Assertion Consumer Service at Kentik, which is the URL to which the IdP should posts its response.

Note: If you are configuring tenant SSO you will likely also need (depending on the configuration process for your IdP) the IDs listed in the Tenant ID column of the Tenant List on the My Kentik Portal page.

Note that some IdP solutions, including Shibboleth, can take the needed information (SP Entity Id and SP ACS Url) from an XML configuration file. We’ve provided a ready-made config file for that purpose, which you can download directly from the Single Sign-on page via the Download Kentik SP Metadata button at the bottom.

Once you’ve added Kentik to your IdP, go back to the Single Sign-on page to set IdP-related settings. As described in How SSO Works, when Kentik requests authentication for a given user the IdP will return a response. The following controls tell the IdP which fields in that response to use for certain pieces of information, so that when Kentik gets the response we know where the information will be:

• IDP SSO Url (required): The name of the field in which the IdP should return the IdP entry-point URL, which is the IdP URL to which Kentik redirects the browser when a user initially attempts to log in.
• Email Attrib. Key (required): The name of the field in which the IdP should return the IdP’s email attribute key, which tells Kentik where to find the user’s email in the IdP’s response to an authentication request.
• IDP Profile Tenant ID field (required; not pictured, present only for tenant SSO configuration): The name of the field in which the IdP should return the tenant ID, which tells Kentik which tenant the user is associated with.
  Note: Tenant ID is indicated in the Tenant ID column of the Tenant List on the My Kentik Portal page.

• Encrypt Assertions (default = Off): Specify whether or not you want SAML assertions (authentication, attribute, and/or authorization decision statements) in a response from the IdP to be encrypted.
• IdP Signing Cert (optional): The name of the field in which the IdP should return the IdP’s public signing key. If a signing cert is provided in this field, Kentik will reject any response for which there is either no signature or a signature that can’t be verified. If no signing cert is provided then Kentik will not require a signature or attempt to verify signed responses.
  Note: Kentik recommends that the value entered in this field be formatted with the tool at the following URL: https://www.samltool.com/format_x509cert.php

If you are configuring direct-user SSO (not tenant SSO; see SSO Types), then in addition to the controls described above you may also want to set the optional User Level Attrib. Key, which is a field to enter your IdP’s user-level attribute key. If the IdP’s response to an authentication request includes an IdP-specified user level, this setting tells Kentik where to find it. That allows user levels to be managed from the IdP:

• If this field is left blank, or the field is specified but the IdP-provided value is invalid, then the field will be ignored, meaning that the user level will be determined by Kentik’s internal user-level value for the user. The only valid (Kentik-recognized) values for the key are 0 (Member) and 1 (Admin).
• If the IdP does provide a valid level for a given user then at login Kentik’s internally stored user-level value for that user will be overwritten with the IdP-provided value. For example, if a user that’s registered in Kentik as an Admin is identified by IdP as a Member, then that user will become a Member and no longer have access to Admin privileges.

The fact that all values other than 0 (Member) and 1 (Admin) are ignored prevents an existing user level in Kentik from being overwritten with an invalid level from the IdP. It also means (because there is no valid value representing the Super Admin level) that a user’s level can’t be changed to Super Admin via IdP (this is intentional to discourage the automatic creation of excessive Super Admin users).

Keep the following in mind when considering how to manage Kentik user levels with your IdP:

• If the IdP provides a valid user-level key then any user level that is changed directly in Kentik (via portal or API) will be reset to the IdP-provided level at the next SSO login.
• If a Super Admin user is included in an IdP group whose user level is collectively set via an IdP user-level key then that user will lose Super Admin privileges.
• In cases where the user-level values used by your IdP are not Kentik-valid (e.g. true and false rather than 1 and 0) your IdP may enable you to configure a transform that makes the value Kentik-valid before including it in the SAML assertion sent to Kentik.

The Auto-provisioning switch (default = Off) determines what happens when sign-on is attempted by someone who is successfully authenticated by the IdP but is not already registered with Kentik as a user (not listed in Admin » User):

• If set to On, login will be allowed and the user will be automatically registered with Kentik.
• If Off, login will be denied.

If you decide to use auto-provisioning, you’re most likely to achieve the expected results by taking into account the following:

• If the User Level Attribute Key field is blank or a valid user-level key is not found in the IdP response then the user level assigned to auto-provisioned users will be Member.
• There is currently no mechanism to auto-provision the Full Name field in Kentik’s internal record for each user. Instead, the Full Name of auto-provisioned users will be set to the IdP-provided email address (see Email Attrib. Key in Configure IdP Settings in Kentik), after which it can be changed directly in Kentik (portal or API).
• You can’t “auto-deprovision” a user. In other words, removing a user from the IdP does not remove that user from Kentik’s internal list of the organization’s users. That has to be done from the portal (Admin » User) or via Kentik’s User API.

In addition to the settings above the following settings can be used to tailor the configuration to your organization’s specific needs:

• SSO Required (default = Off):
  - If set to On, all users (except for Super Admins) will be required to log in via SSO.
  - If Off, users may log in with either SSO or standard login.
• Disable 2FA (default = Off):
  - If On, two-factor authentication will be disabled whenever SSO is enabled.
  - If Off, 2FA users who sign on via SSO will still need to input a one-time password from their 2FA source (e.g. Google Authenticator or any OTP client).

Once SSO is enabled, logins will take place at a newly created URL that is specific to your organization. In the following example, company_shortname is a placeholder for the actual value, which is the last segment of the URL shown in the SP Entity Id or SP ACS Url field (see Add Kentik To Your IdP):

https://portal.kentik.com/sso/company_shortname

When users land on your Kentik SSO login gateway page:

• If they already have a valid active session (as defined by the IdP) they will be automatically logged into the Kentik Detect portal.
• If they don’t already have a current session they will be redirected to the IdP’s login screen and then back to Kentik Detect Portal upon successful authentication.

The following procedure is the recommended way to transition from plain authentication to SSO:

1. Configure SSO with SSO Required set to Off (default). Perform all of the needed tests and validate the optional features with a single user, typically the staff member (a Super Admin) in charge of SSO.
2. Send an announcement to your organization’s Kentik user base. Include the following:
   - A clear date on which Kentik access will become SSO-only.
   - Contact info for the Super Admin, so that users can ask for help before the cutoff date.
   - The new login URL for Kentik access via SSO (replace the company_shortname placeholder with the last segment of the URL shown in the SP Entity Id or SP ACS Url field):
   https://portal.kentik.com/sso/company_shortname
3. On the cutoff date, flip the SSO Required switch to On, after which Kentik users will only be able to log in using the SSO URL.
   Note: Once SSO is required, users attempting non-SSO access (https://portal.kentik.com/login) will be denied access.