Docs
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.
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.
| Field | Description | Required |
|---|---|---|
| Name | The name of the Identity Provider as it will appear in the Instance Settings view | Yes |
| Description | This field can contain any additional information or comments about the Identity Provider | No |
| Label | The 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 Icon | The 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 instead | No |
| Single Sign-On URL | The single sign-on service URL provided by the SAML Identity Provider | Yes |
| Idp Certificate | The X.509 Certificate text provided by the SAML Identity Provider | Yes |
| SAML Binding | The mechanism by which the SAML requestors and responders are communicating. The available options are HTTP-POST and HTTP-Redirect | - |
| Name ID Format | Aligns 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 Request | Specifies if the authentication requests are signed or not | No |
| Signature Algorithm | The type of algorithm that is used to sign the requests. The available options are sha1, sha256 and sha512. | - |
| Request Compression | Specifies if the requests are compressed or not | No |
| Session Timeout | Specifies an expiration time for the user session in seconds. The default value is 3600 seconds (60 minutes) | No |
| Sliding Expiration | Specifies 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 |
| Enabled | Specifies 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.
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.
E-mail address is already taken.
Below are the steps that each user needs to take in order to link their existing Kinvey and ADFS accounts:
- Navigate to your Kinvey Console instance and log in with your Kinvey credentials.
- Hover over the avatar in the top right corner and select Profile from the menu.
- In the Edit Profile view, select the Link Accounts tab from the left-side menu
- Select the Identity Provider to which you want to link the account and click Link Account.
- When redirected to your ADFS login page, provide your ADFS credentials.
- You can now log out of the Kinvey account and use the ADFS login and credentials to authenticate in the Kinvey Console.
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:
| Field | Description | Required |
|---|---|---|
| Identity Provider Group | The group name. Must exactly match the name in the IdP group claims of the SAML Response | Yes |
| Organization | The organization in which resides the Kinvey team and to which the IdP group will be mapped | Yes |
| Kinvey Team | The Kinvey team to which the specific IdP group will be mapped | Yes |
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.
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.
The steps to disable the Kinvey identity are:
- Navigate to your Kinvey Console instance and log in.
- Open the Instance Settings view by clicking on the respective icon in the top right corner.
- Select the Settings tab from the left-side menu.
- Enable the Disable Kinvey Identity toggle to disable the Kinvey identity and login.
