ADFS Integration

The following article describes how to create and configure a SAML 2.0 identity provider (IdP) and tie it to an existing Active Directory Federation Services (ADFS) implementation. With ADFS, you can give users 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

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 the instance level role of Admin).

Instance Administrators can use their Kinvey credentials to log in to the Console even after the Kinvey identity has been disabled.

Here are the steps needed to disable the Kinvey identity:

  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