How to: Set up Single Sign-On (OneLogin)

This guide explains how to set up Single Sign-On (SSO) on the Karat platform using the SAML 2.0-compliant identity provider (IdP) OneLogin. Follow the steps below to configure your IdP, enable SSO in Karat, and manage user provisioning and permissions.

Prerequisites

Before configuring SSO for your organization, ensure the following prerequisites are met:

• You have an admin user account on the Karat platform.
• You have access to a SAML 2.0-compliant identity provider IdP available with Karat.

User provisioning and permissions

The Karat platform supports Just-In-Time (JIT) provisioning of users from the IdP. When a new user authenticates with SAML for the first time, an account is automatically created for them. By default, they are assigned the 'Team Member' user type with the standard role access permissions for their group. See How To: Manage Karat Users (RBAC) to learn about user types and role access permissions.

If the user already has an account in Karat, their existing permissions remain unchanged when logging in via SSO.

If a client wants to set a new team member's user type or role access permissions, they can either wait until the new team member has logged in with SSO and their user has been JIT provisioned, or they can create a user account with the desired permissions manually in Karat before adding the user in their IdP.

Warning: Karat does not support Single Logout (SLO) or user deprovisioning via the IdP. Users signed out of the IdP will remain logged into Karat until their session has been idle for 8 hours. If a user is removed from the IdP, they will be unable to log in to Karat if the organization's SAML policy is set to "Required". To fully disable a user, see How To: Manage Karat Users (RBAC) guide.

Karat includes a setting for its 'Organization' called "SAML New User Type." This determines the default user type assigned to new accounts created via SSO. By default, the setting is configured to "Team Member," but it can be adjusted to "Admin," "Limited Team Member," or "External Team Member" based on your preferences.

We recommend utilizing this setting to ensure newly created users do not automatically gain access to sensitive areas of the Karat platform, providing an additional layer of control and security. To modify this setting, contact the Karat support team.

Karat doesn't support System for Cross-domain Identity Management (SCIM).

Note:  If your organization has enabled Single Sign-On (SSO) on the Karat platform using SAML 2.0-compliant identity providers (IdPs), avoid setting up Two-Factor Authentication (2FA). Users authenticated through SSO will not require 2FA.

Setting up SSO

To set up SSO, configure your identity provider (IdP) using the details below. Terminology may vary across IdPs—refer to IdP-specific instructions in this guide for additional help.

Enter the following configuration details into your IdP:

• ACS URL (replace client-name with your subdomain): https://client-name.karat.io/users/auth/saml/callback
• Entity ID: Karat
• Metadata document (replace client-name with your subdomain): https://client-name.karat.io/users/auth/saml/metadata
• The email attribute is required. 
• Additionally, you must provide either full_name or both first_name and last_name. If full_name is provided, it will take precedence. Some IdPs only support first_name and last_name.
• Attribute mappings:

<md:RequestedAttribute FriendlyName="Email address" Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>

<md:RequestedAttribute FriendlyName="Full name" Name="name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>

<md:RequestedAttribute FriendlyName="Given name" Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>

<md:RequestedAttribute FriendlyName="Family name" Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>

After the identity provider is set up, email the following details to a Karat internal user to enter into Central, Karat's platform:

• IdP URL
• IdP certificate in PEM format

Create a New App

1. Log in to OneLogin.
2. From the administration page, select Apps.
3. Click Add App. 
4. Enter SAML in the search bar. 
5. Select the SAML Custom Connector (Advanced) app using SAML 2.0.

1. Enter Karat in the Display Name field.
2. Optional: add an icon for the new SAML.
3. Click Save. 

SAML Configuration

1. From the Configuration page, add the following fields, replacing client-name with the subdomain:
   • Audience (Entity ID): Karat
   • Recipient: https://client-name.karat.io/users/auth/saml/callback
   • ACS (Consumer) URl Validator: ^https:\/\/client-name\.karat\.io\/users\/auth\/saml\/callback$
   • ACS (Consumer) URL: https://client-name.karat.io/users/auth/saml/callback

2. From the Parameters page, enter the following parameters:

• email / Email
• first_name / First Name
• last_name / Last Name

3. Each field should be included in the SAML assertion.

1. From the SSO tab, change the SAML signature algorithm to SHA-256.
2. Enter the SAML 2.0 Endpoint (HTTP) URL into the client's group edit page on Central as the SAML URL. 
3. Select View details, under the X.509 certificate to view the SAML certificate.

Enter the above information into the Central to configure the organization.