Skip to main content

Microsoft Entra ID authentication

To enhance the security and streamline the user experience of your integrations with MindKey, you can enable Microsoft Entra ID authentication. This guide will walk you through the process of registering your Microsoft Entra ID tenant with MindKey and granting consent to access the MindKey Connector.

Register a tenant​

Step 1: Access the Connector Access Control Panel​

  1. Log in to your MindKey administrative account.
  2. Navigate to the Administration panel on the left sidebar.
  3. Click on Integration.
  4. Select Connector Access Control.
  1. Under the Microsoft Entra ID tenants section, click on the Register tenant button.
  2. A dialog will appear containing an activation link.
  3. Copy the activation link using the copy button.
  1. Send the activation link to a Microsoft Entra ID administrator for your organization.
    • The administrator does not need a MindKey account.
    • The link can be shared via email, chat, or any other communication channel.
  1. The Entra ID administrator opens the activation link in their browser.
  2. They will be redirected to the Microsoft admin consent page.
  3. After reviewing the permissions requested by the MindKey Connector, they click Accept to grant consent.

Step 5: Confirmation of Tenant Registration​

Once consent is granted, the administrator will see a success confirmation page. The tenant ID will now appear under the Microsoft Entra ID tenants in the Connector Access Control panel.

Troubleshooting​

  • If the tenant ID does not appear after the administrator has granted consent, refresh the Connector Access Control page.
  • Activation links are single-use. If the link has expired or was already used, generate a new one by clicking Register tenant again.
  • If the issue persists, contact MindKey support for assistance.

By following these steps, you have successfully enabled Microsoft Entra ID authentication for the MindKey Connector, allowing for a secure and integrated user experience with your Microsoft Entra ID infrastructure.

Granting Access for Users and Service Principals​

After successfully registering your tenant, you can grant access to individual users and service principals. This process allows specified user accounts and applications to interact with the MindKey Connector API using Microsoft Entra ID authentication.

Step 1: Access the Connector Access Control Panel​

  1. Log in to your MindKey administrative account.
  2. Navigate to the Administration panel on the left sidebar.
  3. Click on Integration.
  4. Select Connector Access Control.

Step 2: Add a New User or Service Principal​

  1. Scroll down to the Microsoft Entra ID users and service principals section.
  2. Click on the Add user button to create a new entry in the users table.

Step 3: Configure Access​

... for a User Account​

danger

Granting access to a user account will give that user access to ALL records, bypassing all exiting security rules, that are applied within the application.

  1. In the new row under User type, select User account from the dropdown menu.
  2. A second dropdown menu will appear under Username/Client Id. Click on it and select the desired user account that should have access to the MindKey Connector.
  3. Select one or more scopes that the user should have access to.
  4. If multiple tenants are registered, use the Tenant Id dropdown to select the corresponding tenant for this user.

... for a Service Principal​

  1. In the new row under User type, select Application/Service principal from the dropdown menu.
  2. In the Username/Client Id field, enter the Client Id of the application or service principal.
  3. Select one or more scopes that the service principal should have access to.
  4. If multiple tenants are registered, use the Tenant Id dropdown to select the corresponding tenant for this application/service principal.

Step 4: Save the Configuration​

  • After selecting the user type and specifying the Username/Client Id and Tenant Id, ensure to save the configuration by clicking on the checkmark.

Step 5: Verify Access​

  • Inform the users that they have been granted access.
  • Verify that they can authenticate and interact with the MindKey Connector API successfully.

By following these steps, you have granted access to the MindKey Connector API for specific users and service principals, allowing them to authenticate using Microsoft Entra ID.

User Accounts vs. Service Principals​

Microsoft Entra ID authentication supports two types of identities: User Accounts and Service Principals (Applications). These behave differently in the Connector API.

Service Principals​

Service principals represent applications or automated services. They are the recommended approach for server-to-server integrations, background jobs, and automated data extraction.

  • Access is granted based solely on the assigned scopes.
  • No additional requirements beyond valid authentication and scope assignment.

User Accounts​

User accounts represent individual human users. They have an additional security requirement:

  • The user must have an active employee record in MindKey with at least one active position.
  • If the user does not meet this requirement, requests will be rejected even if scopes are correctly assigned.

This restriction ensures that only current employees with active positions can access data through the Connector API using their personal credentials.

danger

Granting access to a user account bypasses all record-level security rules that are applied within the MindKey application. The user will have access to all records within the assigned scopes, not just the records they can see in the MindKey UI.

Last-Used Tracking​

Similar to API keys, the Connector API tracks the last time each Entra ID user or service principal accessed the API. This information is visible in the Connector Access Control panel and is updated approximately every 5 minutes.

Using the Microsoft Entra ID Access Token​

To access the MindKey Connector API with Microsoft Entra ID authentication, you must include the obtained access token in the HTTP Authorization header with the Bearer scheme. This token proves your identity and authorizes you to make calls to the API endpoints.

Here is an example of how to include the access token in your HTTP requests:

GET /ping HTTP/1.1
Host: connector.mindkey.com
Authorization: Bearer YOUR_ACCESS_TOKEN