Skip to main content

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

Updated

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

After setting up SSO, choose a compliant identity provider (IdPs):

  • Okta
  • OneLogin
  • Google
  • Microsoft Azure
  • Federation
  • Idaptive
  • Ping

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

Identity providers (IdPs)

This section includes all the IdPs available with the SSO with Karat. Choose your preferred IdPs and follow its instructions to set it up.

1.Okta

Create a New App

  1. Log in to Okta.
  2. Create a new SAML 2.0 application.
  3. Enter the settings for the new SAML 2.0 application as follows. Take the configuration details from the Setting up SSO section. 
    • Single sign on URL is the ACS URL.
    • Audience URI is the Entity ID.
    • Central requires SAML assertions to be signed with the encryption settings shown below. These should be the default options for Okta.
    • Attribute mappings are also as outlined in the Setting up SSO section. Okta does not have a full name field so the first and last names are used.

Okta does not support setting import from the metadata document.

Basic settingsAdvanced settingsAttribute settings

Set up Sign On

On the Sign On tab, select View Setup Instructions for configuring the data needed to the organization on Central.

2.OneLogin

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

  1. From the Parameters page, enter the following parameters:
    • email / Email
    • first_name / First Name
    • last_name / Last Name
  2. 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.

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

3.Google

Set up your own custom SAML app

  1. Sign to the Admin console Home page.
  2. Go to Apps.
  3. Click Web and mobile apps.

  1. Click Add App.
  2. Click Add custom SAML app.

  1. On the App Details page:
    1. Enter the name of the custom app.
    2. Optional: Upload an app icon. The app icon appears on the Web and mobile apps list, on the app settings page, and in the app launcher. If you don't upload an icon, an icon is created using the first two letters of the app name.

  1. Click Continue.
  2. On the Google Identity Provider details page, get the setup information needed by the service provider using one of these options:
    • Download the IDP metadata.
    • Copy the SSO URL and Entity ID.
    • Download the Certificate (or SHA-256 fingerprint, if needed).
    • Optional. In a separate browser tab or window, sign in to your service provider and enter the information you copied into the appropriate SSO configuration page, then return to the Admin console.

  1. Click Continue.
  2. In the Service Provider Details window, enter an ACS URL, Entity ID, and Start URL (if needed) for your custom app. These values are all provided by the service provider. 

Note: The ACS URL has to start with https://

  1. Optional. On the Attribute mapping page, click Add another mapping to map additional attributes. You can define a maximum of 1500 attributes over all apps. Because each app has one default attribute, the total amount includes the default attribute plus any custom attributes you add.
    • Under App attributes, enter the corresponding attribute for your custom SAML app.

  1. Optional. If you want to send a user’s group membership information in the SAML response, enter the group names that are relevant for this app in the Group membership field.
    • Under App attribute, enter the service provider’s corresponding groups attribute name. Regardless of how many group names you enter, the SAML response will only include groups that a user is a member of (directly or indirectly. For more information, see About group membership mapping.

  1. Click Finish.

Configure SAML

  1. Go the Admin console Home page.
  2. Go to Apps.
  3. Click Web and mobile apps.
  4. Select your SAML app.
  5. Click User access.

  1. To turn on or off a service for everyone in your organization, click On for everyone or Off for everyone, and then click Save.

  1. Optional. To turn a service on or off for an organizational unit:
    1. At the left, select the organizational unit.
    2. To change the Service status, select On or Off.
    3. Choose one:
      • If the Service status is set to Inherited and you want to keep the updated setting, even if the parent setting changes, click Override.
      • If the Service status is set to Overridden, either click Inherit to revert to the same setting as its parent, or click Save to keep the new setting, even if the parent setting changes.
      • For more information, see organizational structure.
  2. To turn on a service for a set of users across or within organizational units, select an access group. For more details, see turn on a service for a group.
  3. Make sure that the email addresses your users use to sign in to the SAML app match the email addresses they use to sign in to your Google domain.

Verify that SSO is Working with your App

IDP Initiated

  1. Go the Admin console Home page.
  2. Go to Apps.
  3. Click Web and mobile apps.
  4. Select your custom SAML app. 
  5. At the top left, click Test SAML login. Your app should open in a separate tab. If it doesn’t, use the information in the resulting SAML error messages to update your IdP and SP settings as needed, then retest SAML login.

4.Microsoft Azure

Create a New App

  1. Log in to the Azure portal.
  2. In the left-hand menu, click Azure Active Directory.
  3. Click Enterprise applications.

  1. Click + New application.

  1. Click Non-gallery application.

  1. Give the new application a name.
  2. Click Add at the bottom of the screen. This will add a custom application to your Azure Active Directory.

  1. Once the application loads, click Users and groups in the left-hand menu. 
  2. Click + Add user to assign users or user groups to this application.

  1. Click Single sign-on in the left-hand menu.
  2. Click SAML.

Configure SAML

  1. In the setup screen, click the pencil icon in the Basic SAML Configuration box.

  1. Enter the following URLs in the fields provided, replacing subdomain with your subdomain:
    • Identifier (Entity ID): Karat
    • Reply URL (Assertion Consumer Service URL):  https://client-name.karat.io/users/auth/saml/callback
    • Sign on URL 
    • Relay State - Skip. This is an optional parameter used to tell the application where to redirect the user after authentication is completed.
    • Logout URL 

  1. Make sure to fill in your subdomain where it says subdomain. Note that there's no trailing slash at the end of the URL. 
  2. Click Save at the top of the form when finished.

User Attributes & Claims

  1. Return to the setup screen.
  2. Click the pencil icon on the User Attributes & Claims box.

  1. Click Unique User Identifier (Name ID). 

  1. Enter a name and select user.mail in the Source attribute drop-down menu.
  2. Click Save at the top of the form.

SAML Signing Certificate

  1. Return to the setup screen.
  2. Click the pencil icon in the SAML Signing Certificate box.

  1. Enter a notification email for the certificate expiry reminders.
  2. Click Save at the top of the form.

  1. Back in the setup screen, click to download the Certificate (Base64) to save the certificate file on your computer and copy the Thumbprint.

Setup Karat SSO

  1. Return to the setup screen.
  2. Click the View step-by-step instructions link in the Setup <Karat> box.

  1. Review the documentation that will guide you through filling out the:
    • Login URL ( SAML Single Sign-On Service URL)
    • Azure AD Identifier (SAML Entity ID), and
    • Logout URL (Sign-out URL) fields.

Test Single Sign-on with <Karat>

  1. Return to the setup screen.
  2. Click Test in the Test Single Sign-on with <Karat> box to check if single sign-on is working.

5.Federation

Register IdP

The Reply URL is used by the app to redirect users to the portal after the authentication succeeds. If your portal uses a custom domain name, you might have a different URL than the one provided here. More details about creating the app registration on the Azure portal are available in Quickstart: Register an application with the Microsoft identity platform.

In this section, you create the application and configure the settings with your identity provider. 

  1. Sign in to the Azure portal.
  2. Search for and select Azure Active Directory.
  3. Under Manage, select App registrations.
  4. Select New registration.

  1. Enter a name.
  2. If necessary, select a different Supported account type. For more information, see Supported account types.
  3. Under Redirect URI, select Web (if it isn't already selected).
  4. Enter the Reply URL for your portal in the Redirect URI text box. Example: https://client-name.karat.io/users/auth/saml/callback. 

Note: If you're using the default portal URL, copy and paste the Reply URL as shown in the Create and configure WS-Federation provider settings section on the Configure identity provider screen (step 6 above). If you're using a custom domain name for the portal, enter the custom URL. Make sure to use this value when you configure the Assertion consumer service URL in your portal settings while configuring the WS-Federation provider. For example, if you enter the Reply URL in Azure portal as https://client-name.karat.io/users/auth/saml/callback, you must use it as-is for the WS-Federation configuration in portals.

Register Application

  1. Select Register.
  2. Select Expose an API.
  3. For Application ID URI, click Set.

  1. To use the auto-generated URI, click Save. You'll need to manually update the value in site settings after you configure settings using the studio.
  2. If you're using a custom domain name, enter the portal URL as the App ID URI.

  1. Click Save.
  2. Keep the Azure portal open, and switch to the WS-Federation configuration for Power Apps portals for the next steps.

Portal Configurations

In this section you enter the site settings for the portal configuration.

  1. Metadata address. To configure the metadata address, do the following:
    1. Select Overview in the Azure portal.
    2. Select Endpoints.

  1. Copy the URL for Federation metadata document.

  1. Paste the copied document URL as the Metadata address for portals.
  1. Authentication type.To configure the authentication type, do the following:
    1. Copy and paste the Metadata address configured earlier in a new browser window.
    2. Copy the value of entityID tag from the URL document.

  1. Paste the copied value of entityID as the Authentication type. Example: https://sts.windows.net/7e6ea6c7-a751-4b0d-bbb0-8cf17fe85dbb/
  1. Service provider realm: Enter the custom portal URL as the service provider realm. Example: https://portal.karat.com
  2. Click Confirm.

  1. Select Close.

Update App ID URI in site settings

If you're using the auto-generated URI for the App ID URI, you'll need to update the value in site settings.

  1. Open the Portal Management app.
  2. Navigate to Site Settings.
  3. Update the site setting Authentication/WsFederation/WSFederation_1/Wtrealm with the auto-generated APP ID URI.

  1. Click Save

6.Idaptive

Follow these simple steps to set up Idaptive SAML SSO.

Create a New App

  1. Log in to Idaptive.
  2. Click Web Apps from the left menu.
  3. Click Add Web Apps.

Configure SAML

  1. Click the Custom tab.
  2. Click Add, under SAML.

  1. Click Settings from the left menu
  2. Enter a name for the app, for example, Karat SSO.
  3. Click Save.

  1. Click Trust from the left menu.
  2. Under Identity Provider Configuration:
    • Select Manual Configuration.
    • Copy the IdP Entity ID / Issuer value. For example: https://xxx.my.idaptive.net/523452345dae97454dec
    • Download the Signing Certificate.
    • Copy  the Single Sign On URL value. For example: https://xxx.my.idaptive.net/applogin/appKey/2345234/customerId/XXX
    • Copy  the Single Logout URL value. For example:  https://xxx.my.idaptive.net/applogout/appkey/2234223ec/customerid/XXX

  1. Under Service Provider Configuration: 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
  • Encrypt SAML Response Assertion: No
  • Relay State: (leave it blank)
  • Authentication Context Class: unspecific
  1. Click Save.

NameID Format and Signing Certificate

Permissions and Deployment

  1. Click Permissions from the left menu.
  2. Click Add.

  1. Enter Everybody (or any user, group or role) in the search box.
  2. Select users, groups or roles then click.
  3. Click Add.

  1. Click Save. 
  2. You should see the Deployed status.

7.Ping

Follow these steps to set up Ping SAML SSO.

Creating a New App

  1.  Click the Web tab.
  2. A list of all the existing policies will be displayed.

  1. Click + Add Policy.
  2. The New Policy window will display with the Applications list.

  1. In the PingFederate Applications section, click + Add Application. The PingFederate Application window will appear.

  1. In the PingFederate Application window, enter the following information:
    • Name: Enter the name of the application (max. 20 characters).
    • ID: Enter the application ID for the application. For more information, see unique application ID.
    • Add application to target: Select this check box to add the application to the new policy that you just created.
  2. Click Save.
  3. The new application is saved and appears in the Applications list.

Defining PingFederate application ID attributes

Define an application policy by adding the Name and ID attributes. Each application that you define in the PingID Policy tab must include the following information:

  • Name: The name of the application as it appears in the PingID policy application list. This attribute does not have to match the application name defined in PingFederate.
  • ID: The unique ID for the relevant application in PingFederate. This attribute must match the relevant PingFederate Application ID attribute as defined in the following table.

For more information from the administrator's guide, see PingFederate admin guide.

Type of Target Application Application Identifier
SAML or WS-Federation (service provider connection) Partner Entity or Realm ID (Connection ID)
OAuth or OpenID Connect (OAuth Client) OAuth Client ID
Custom SP Adapter ID

Updating the policy groups list

When a group is created in Active Directory, it does not automatically appear in the policy groups list. At least one user that is assigned to the group must successfully authenticate using PingID for the groups list to be updated.

  1. Create a new user group in your local Active Directory.
  2. Assign users to the directory group.
  3. At least one user must be assigned to the group.
  4. Ensure at least one of the users in the new group authenticates with PingID successfully or through SSO to PingOne.
  5. In the PingOne admin portal:
    1. Go to Setup
    2. Click PingID.
    3. Click Policy.
    4. Refresh the Policy window.
  6. The next time you create or edit a policy, the new group appears in the Groups list.

SSO in Central

Once you’ve configured your identity provider, an Organization Admin can enable SSO in Karat.

  1. In the left-hand sidebar, click Settings.
  2. Click the SAML/SSO tab.
  3. Enter your IdP sign on URL into the SAML URL field.
  4. Enter your IdP certificate into the SAML Certificate field.
  5. If you want to require all users to log in with SAML, toggle SAML Required on. If you want users to be able to log in with SAML or email and password, leave it toggled off.
  6. Click Update SAML/SSO to save your settings.

By completing these steps, you have successfully configured Single Sign-On (SSO) for your organization on the Karat platform. 

For further assistance, contact Karat support or refer to your identity provider's documentation.

Was this article helpful?

0 out of 0 found this helpful
Return to top

Related articles