Single Sign-On

The Kinvey Single Sign-On feature allows linking external (SAML\ADFS) identity providers to Kinvey. The external identity providers can then be used to access the Kinvey Web Console, CLI and Management API.

Using an external identity provider results in better security and improved convenience for the users. Users will not need to remember an additional set of credentials for Kinvey and the user management (including disabling access for a user) will happens only in the identity provider (already handled by the IT team).

The Single Sign-On feature is only available for single-tenant instances.

Requirements

To configure single sign-on with a SAML identity provider you need the following:

  • Administrator role on instance level in Kinvey. Only instance administrators can configure single sign-on.
  • A configured and accessible Active Directory instance.

After you ensure that you meet those requirements, you should navigate to the Kinvey Console and work on adding an identity provider.

Configuration

Single sign-on in Kinvey is configured through Identity Providers. An Identity Provider entity is used to configure integration with a single external SAML identity provider. It is possible te configure integration with several SAML identity providers at the same time. Each configured identity integration appears as a button in the Kinvey Login screen.

The first step of enabling single sign-on is to add and configure a SAML identity provider in the Kinvey Console.

To begin, log in to the Kinvey Console and navigate to the Instance Settings view by clicking on the respective icon in the top right corner. Then, select the Identity Providers tab from the left-side menu. Finally, click on the Add an Identity Provider button.

Add Identity Provider

There are several fields that need to be populated in order to add an identity provider. The table below contains short description of each field.

FieldDescriptionRequired
NameThe name of the Identity Provider as it will appear in the Instance Settings viewYes
DescriptionThis field can contain any additional information or comments about the Identity ProviderNo
LabelThe name associated with the identity provider and shown on the login screen in the Kinvey Console. If no label is provided then a default value is created based on the content of the Name field: "Login with Name Account"No
Identity Provider IconThe icon that is associated with the identity provider and shown on the login screen in the Kinvey Console. If no icon is provided then a default icon depicting a key is used insteadNo
Single Sign-On URLThe single sign-on service URL provided by the SAML Identity ProviderYes
Idp CertificateThe X.509 Certificate text provided by the SAML Identity ProviderYes
SAML BindingThe mechanism by which the SAML requestors and responders are communicating. The available options are HTTP-POST and HTTP-Redirect-
Name ID FormatAligns the expectations between the identity provider and Kinvey on the format of the user identity that is communicated. The setting indicates what format Kinvey should expect from the Identity provider. If none is specified, a default format is used urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified-
Sign Auth RequestSpecifies if the authentication requests are signed or notNo
Signature AlgorithmThe type of algorithm that is used to sign the requests. The available options are sha1, sha256 and sha512.-
Request CompressionSpecifies if the requests are compressed or notNo
Session TimeoutSpecifies an expiration time for the user session in seconds. The default value is 3600 seconds (60 minutes)No
Sliding ExpirationSpecifies if sliding expiration is enabled or not. Sliding expiration resets the expiration time for a valid authentication cookie if a request is made and more than half of the timeout interval has elapsed. If the cookie expires, the user must re-authenticate.No
EnabledSpecifies if the Identity Provider is enabled or not. Setting this option to Yes will enable the ADFS integration and show the new login option in the login menu of the Kinvey Console.-

On the bottom of the form is the Provider Testing section which offers a way to test the integration without the need to enable it for the entire instance. This is where you can also download the metadata of the identity provider.

After you enable the identity provider, it will appear in the login form on the Kinvey Console. You can have more than one identity provider enabled at the same time and they all will be listed in the login form.

Login Form

Linking Existing Accounts

It is possible to start using Kinvey with Kinvey-managed user accounts and switch to using single sign-on at a later time. If you do that some of the existing users will probably have accounts in the identity provider, but their Kinvey accounts will not be linked to that identity provider.

Those existing users can be part of organizations, have their own applications, special permissions and so on. It is often preferred to be able to link the existing Kinvey accounts to accounts to the newly configured identity provider and keep all data related to them, as opposed to creating new Kinvey accounts.

Kinvey makes it possible to link existing accounts that are using Kinvey identity to accounts from an external identity provider. Once the accounts are linked, it is possible to log in using either the single sign-on with the external identity provider or the Kinvey user credentials.

Attempting to log through a SAML identity provider with an email that is associated with an unlinked Kinvey account will result in an error - E-mail address is already taken.

Users that have never accessed the Kinvey Console and do not have a Kinvey account can log directly through the SAML login without taking any additional steps.

For security reasons, linking user account to an external provider cannot be done in a batch. Each user needs to link their own account. Below are the steps that need to be taken in order to link accounts:

  1. Navigate to your Kinvey Console instance and log in with your Kinvey credentials.
  2. Hover over the avatar in the top right corner and select Profile from the menu.
  3. In the Edit Profile view, select the Link Accounts tab from the left-side menu
  4. Select the Identity Provider to which you want to link the account and click Link Account.
  5. When redirected to your identity provider login page, provide your identity provider credentials.
  6. You will be redirected back to the Kinvey Web Console and a success or error message will be displayed.
  7. After successful linking, you will be able to log in to Kinvey using the external identity provider

Link Account

Permissions Mapping

The mapping configurations provide a way for the instance administrators to manage users membership and permissions by mapping identity provider (IdP) groups to Kinvey teams. Each mapping takes three values:

FieldDescriptionRequired
Identity Provider GroupThe group name. Must exactly match the name in the IdP group claims of the SAML ResponseYes
OrganizationThe organization in which resides the Kinvey team and to which the IdP group will be mappedYes
Kinvey TeamThe Kinvey team to which the specific IdP group will be mappedYes

You can add more than one mapping for a single IdP group. This way users from one IdP group can be part of multiple Kinvey teams.

If a user is added to a team which is associated with an organization in which the user does not have access, the user is automatically added to the organization and given COLLABORATOR role.

When the instance administrator saves the mapping, it will apply to all users that have logged with the related IdP based on the information from their last login. On the next login, any group changes will be respected and the Kinvey teams will be updated accordingly.

Permissions Mapping

Removing Users

Users added to a team through the permissions mapping cannot be removed manually from the Kinvey Console. To remove such users from a team, they should be removed from the corresponding group on the identity provider side. Any changes made to the identity provider groups will be applied when the user logs in (after logout or session expiration) and the SAML Assertion with updated groups is received.

Disable Kinvey Credentials

In order to improve security it is possible to completely disable the use of the Kinvey built-in login mechanism. This would prevent users from logging in with their Kinvey credentials and ensure that all users need to go through the external identity provider in order to work with Kinvey.

This is done through the Disable Kinvey Identity setting in the Instance Settings page. Turning it on will make it impossible to log in with Kinvey credentials. It will also collapse the Kinvey login option in the login menu of the Kinvey Web Console.

Even if the Disable Kinvey Identity setting is turned on, instance administrators can still log in with their Kinvey credentials. This is designed that way to prevent scenarios in which the identity provider integration breaks and there is no way to log in and manage the instance.

The steps to disable the Kinvey identity are:

  1. Navigate to your Kinvey Console instance and log in.
  2. Open the Instance Settings view by clicking on the respective icon in the top right corner.
  3. Select the Settings tab from the left-side menu.
  4. Enable the Disable Kinvey Identity toggle to disable the Kinvey identity and login.

Disable Kinvey Identity