Single Sign-On

The following article describes how to create and configure an identity provider (IdP) and tie it to an existing external system like Active Directory Federation Services (ADFS). With Single Sign-On, you can provide users with access to the Kinvey Console and CLI without them having to manage another set of credentials.

Requirements

To integrate ADFS with your dedicated Kinvey instance, you need the following:

  • A dedicated Kinvey instance. Only owners of dedicated instances can setup ADFS integration.
  • An instance level role of Admin. Only instance administrators can create and configure identity providers, and enable the ADFS integration.
  • An 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.

Add Identity Provider

The first step of enabling the ADFS integration is to add and configure a SAML 2.0 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

The Kinvey accounts are part of organizations and app environments and have specific access rights associated with them. This makes the linking of existing Kinvey and ADFS accounts a mandatory process for each user.

Attempting to log through the ADFS login 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 ADFS login without taking any additional steps.

Below are the steps that each user needs to take in order to link their existing Kinvey and ADFS 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 ADFS login page, provide your ADFS credentials.
  6. You can now log out of the Kinvey account and use the ADFS login and credentials to authenticate in the Kinvey Console.

Link Account

Access Management

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 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 Identity

To disable the default Kinvey login and prevent users from logging in with their Kinvey credentials, you should enable the Disable Kinvey Identity setting in the Instance Settings view. This will also collapse the Kinvey login option in the login menu of the Kinvey Console.

Before disabling the Kinvey identity, you must ensure that all existing users have linked their accounts as described above. Otherwise, those users won't be able to access their accounts until the Kinvey identity is enabled.

The Kinvey identity can be disabled or enabled only by an Instance Administrator (a user with an instance level role of Admin). The Instance Administrators can continue to access the Kinvey Console with their Kinvey credentials even after the Kinvey identity has been disabled.

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