Authentication & SSO

Kentik’s implementation of Authentication and SSO is covered in the following topics:

• About Authentication & SSO
• Password Expiration Policy
• 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 portal.
- Users assigned (by a Kentik customer) to a tenant of the My Kentik Portal.

Password expiration and single sign-on (SSO) are user authentication techniques that help maintain the security of your Kentik account. These techniques are implemented in the portal on the Authentication & SSO page, which has two main parts:

• Password Expiration Policy: Set an expiration duration for passwords; see Password Expiration Policy.
• Single Sign-on: Set up access to the portal via an authentication service; see About SSO.

The basics of Kentik’s Password Expiration Policy are covered in the following topics:

• Password Policy Overview
• Password Policy UI

Kentik’s password policy enforces specific rules to align with SOC-2 compliance. Minimal password complexity is checked during the creation of a password. This applies to both new accounts during account activation and existing accounts during password resets. For more information regarding the different levels of password complexity, see Account Activation UI.

In addition to password complexity, passwords can be configured to expire after a certain number of days to reduce the likelihood of unauthorized access. A password must be reset once it reaches expiration. The system maintains a history of the previous five passwords to prevent reuse.

The Password Expiration Policy pane contains the following UI elements:

• Password Expiration Duration: A dropdown to configure the duration before a password must be reset.
• Disable Password Expiration:
  - If set to Off (default), users who log in exclusively with a password will be required to reset their password in accordance with the configured expiration duration.
  - If set to On, users will not be required to reset their password.

The basics of SSO are covered in the following topics:

• SSO Overview
• SSO Identity Providers
• How SSO Works

Single sign-on (SSO) is enabled for the Kentik portal. That means Kentik users can 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 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:

Single sign-on (SSO) is conceptually quite simple. Each Kentik customer (organization) sets up an identity provider (IdP) that keeps track of who in the company has permission to access Kentik. (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 SSO settings and contacts the IdP to request verification of the user. If the IdP can 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 single sign-on (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 G Suite, 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 Authentication & SSO page (Settings » Authentication & SSO).
• 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 (Settings » Manage 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 Settings » Manage Users).

Configuration of single sign-on (SSO) in Kentik 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.

Kentik enables two distinct types of single sign-on (SSO) for two distinct groups of Kentik portal users:

• Direct-user SSO: SSO for Admin and Member users (see About Users), for whom SSO is managed from the Kentik portal’s Settings » Authentication & SSO page.
• 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 by clicking the Settings button on the My Kentik Portal Page (Main Menu » My Kentik Portal) and then selecting Tenant SSO from the left menu.

Some of the configuration steps described in the topics below are performed in your identity provider’s management app while others, depending on single sign-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:

• Profile Attribute for User Level: Present for direct-user SSO (see Configure User-level Behavior), not present for tenant SSO.
• Profile Attribute for Tenant ID field: Present for tenant SSO (see Configure IdP Settings in Kentik), not present for direct-user SSO.
• Sign outgoing authentication requests: Present only for direct-user SSO.
• Omit requested authn context from outgoing authentication requests: Present only for direct-user SSO.

On both pages, the settings include both switches and fields. Before configuration, check that the SSO Enabled switch (at the top of the page) 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.

Single sign-on (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 as a service provider (SP) is found in the first two fields, which are read-only:

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

Use the Copy to Clipboard button at the right of each field to copy the field's contents so you can paste it into the appropriate form in your IdP.

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 Name column of the Tenants 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 Authentication & SSO page via the Download Kentik SP metadata button at the bottom.

Once you’ve added Kentik to your IdP, go back to the Authentication & SSO 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:

• Identity Provider (IDP) SSO Entry Point 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.
• Profile Attribute for User Email (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.
• Profile Attribute for Tenant ID (required; 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 Name column of the Tenants List on the My Kentik Portal page.
• IDP requires encrypted 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 Public Signing Key (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 single sign-on (SSO), not tenant SSO (see SSO Types), then in addition to the controls described above you may also want to set the optional Profile Attribute for User Level, 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, 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 registered as an Admin in Kentik 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 profile attribute, 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 profile attribute, 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 Allow auto-provisioning of new users 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 Settings » Manage Users):

• 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 considering the following:

• If the Profile Attribute for User Level 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 Profile Attribute for User Email 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 (Settings » Manage Users) or via Kentik’s User APIs.

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 when user has authenticated via SSO (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).
• Sign outgoing authentication requests (default = Off):
  - If On, all outgoing authentication requests (AuthnRequests) to your IdP are signed with Kentik’s certificate.
  - If Off, all outgoing authentication requests remain unsigned. (SAML2 SSO usually requires this to be option to be Off.)
• Omit requested authn context from outgoing authentication requests (default = Off):
  - If On, outgoing authentication requests do not contain “authnContext”.
  - If Off, outgoing requests contain “authnContext”.

Once single sign-on (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 Service Provider (SP) Entity ID or Service Provider (SP) Assertion Consumer Service (ACS) URL field (see Add Kentik to Your IdP):

https://portal.kentik.com/login/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 portal.
• If they don’t already have a current session, they will be redirected to their IdP’s login screen and then back to Kentik Portal upon successful authentication.

The following procedure is the recommended way to transition from plain authentication to single sign-on (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 Service Provider (SP) Entity ID or Service Provider (SP) Assertion Consumer Service (ACS) URL field]:
   https://portal.kentik.com/login/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.