Configuring Support for Microsoft Entra ID

The HID Authentication Service now offers seamless integration with Microsoft® Entra ID, providing a robust External Authentication Method (EAM) for federated authentication.

This integration empowers organizations to meet mandatory multifactor authentication (MFA) requirements and simplifies the journey to phishing-resistant passwordless authentication.

With this solution, users can securely access protected applications from Microsoft Windows workstations using HID authenticators, including their existing contactless physical access cards.

External authentication via the HID Authentication Service IdP is deployed as the second factor of a multifactor authentication flow.

The integration consists of the following configuration steps:

1. Configure the IdP Workflow

2. Create a New OpenID Client for the Authentication Journey Workflow

3. Create Users and Groups in the Entra ID Tenant (Optional)

4. Configure the Federation between Entra ID and HID Authentication Service

5. Configure the Entra ID Redirection

6. Create the Card Application

7. Create and Assign a Card Authenticator (Optional)

8. Validate the Integration

For an overview of the user experience, see User Enrollment and Authentication.

Prerequisites

Before configuring the solution, you must have:

• A Microsoft Azure directory with a valid license for Entra ID

  Make a note of your Entra ID Tenant ID as you will need it to configure the HID Authentication Service.

  You can retrieve the ID in the Overview page of the Microsoft Entra admin center:

  

• Predefined names for the following Entra ID elements:

  • Application for Contactless Card authentication via the HID Authentication Service IdP (for example, HID IDP integration)

  • External authentication method displayed in the Microsoft interface when prompting the user to verify their identity (for example, HID Contactless Card)

    In the prompt, the label will be Approve with <your external method name> (for example, Approve with HID Contactless Card)

• A functional HID Authentication Service tenant

  You should have the following properties:

  • Your HID Authentication Service tenant ID (starting with t, for example, tb7b09f3d844646108589)

    During the configuration process, you will create the following clients on this tenant:

    • A dedicated OpenID Client ID for authentication via the workflow (defined in the client_id parameter, for example, Client_ID_FLOWCARD_ENTRAID)

    • A dedicated OpenID client with the RL_CLIENTIDM2M role (machine to machine) for provisioning users from the Microsoft Azure directory to HID Authentication Service

  • The Discovery Endpoint (also known as the 'Well-known' endpoint URL) for your tenant

    https://[base-server-url]/idp/{tenant}/authn/.well-known/openid-configuration

  • The login endpoint of your tenant

    https://[base-server-url]/idp/{tenant}/authn/login

  For further information about the HID Authentication Service URLs, see HID Authentication Service Platforms around the World.

• A tenant Administrator with all required roles and your own application (OpenID client) to be used with the API

Configure the IdP Workflow

The IdP workflows define the parameters for the enrollment and authentication process.

The following is an example of the enrollment and authentication workflow with Contactless Card authentication as a first factor.

POST  https://[base-server-url]/configuration/{tenant}/v2/Custo/IDPWorkflows
{
	"schemas": [
		"urn:hid:scim:api:idp:2.0:Customization"
	],
	"id": "ID_FLOWCARD_ENTRAID",
	"payload": {
		"accessCriteria": [
			{
				"authenticators": {
					"secondFactorsFiltering": true,
					"acrFiltering": true,
					"firstFactorsFiltering": true
				},
				"accessCriteriaId": "access_criteria.common_to_all"
			}
		],
		"firstFactors": [
			{
				"factorId": "factor.card_authentication",
				"acr": "possessionorinherence",
				"code": "AT_CARD",
				"type": "CARD",
				"amr": "pop",
				"accessCriteriaId": "access_criteria.common_to_all",
				"enrollActions": [
					"enroll_action.card"
				],
				"stepUp": "notRequired",
				"retry": 3
			}
		],
		"enrollActions": [
			{
				"enrollId": "enroll_action.card",
				"accessCriteriaId": "access_criteria.common_to_all",
				"type": "CARD",
				"code": "enrollaction1",
				"defaultCard": "APP_CARD",
				"retry": 30,
				"deviceBinding": "notRequired",
				"enrollValidation": false
			}
		]
	}
}

Enrollment Flow

"localizationKeyRedefinition": {
	"CARD.auth.enroll_action.link": "CARD.auth.enroll_action.customlink",
	"CARD.auth.message.instructions": "CARD.auth.message.custominstructions"
}

For further information about configuring enrollment factors, see Add an Enrollment Workflow.

Authentication Flow

For further information about configuring authentication factors, see Create the Authentication Workflow.

Create a New OpenID Client for the Authentication Journey Workflow

Create or update an OpenID client to support external id_token_issuer and the Entra ID workflow.

For this step, you will need your Entra ID Tenant ID to reference it in the id_token_hint_issuers attribute.

POST https://[base-server-url]/idp/{tenant}/authn/register
{
	"client_id": "<Unique identifier for your OpenId client>",                     // The OpenID client ID that will be used in your Entra ID configuration.
	"authn_portal_configuration": {
		"workflow_id": "<FLOW ID>"                                                 // The ID of the previously created IdP workflow flow.
	},
	"client_name": "HID IDP Integration",
	"hid_client_group": "UG_CLIENTID",
	"redirect_uris": [
		"https://login.microsoftonline.com/common/federation/externalauthprovider"
	],
	"id_token_hint_issuers": [
		"https://login.microsoftonline.com/<Microsoft Tenant ID>/v2.0"             // Replace with your Microsoft tenant ID.
	],
	"hid_client_channel": "CH_EXTRAPP",
	"hid_user_channel": "CH_EXTRAPP"
}

POST https://[base-server-url]/idp/{tenant}/authn/register
{
	"client_id": "Client_ID_FLOWCARD_ENTRAID",
	"authn_portal_configuration": {
		"workflow_id": "ID_FLOWCARD_ENTRAID"
	},
	"client_name": "HID IDP Integration",
	"hid_client_group": "UG_CLIENTID",
	"redirect_uris": [
		"https://login.microsoftonline.com/common/federation/externalauthprovider"
	],
	"id_token_hint_issuers": [
		"https://login.microsoftonline.com/bb1da57d-<....>/v2.0"
	],
	"hid_client_channel": "CH_EXTRAPP",
	"hid_user_channel": "CH_EXTRAPP"
}

Create Users and Groups in the Entra ID Tenant (Optional)

You can create new groups and users as the target population for the integration in your Entra ID tenant.

If you prefer to use an existing group of users, skip this section and proceed to Configure the Federation between Entra ID and HID Authentication Service.

Create Users

1. Log on to the Microsoft Entra admin center for your tenant.

2. In the left panel, expand Users and select All users.

3. In the New user drop-down menu , click Create new user.

   

4. Enter a User principal name and a Display name

5. Select to Auto-generate password (it will be changed at first log on).

6. Click Review + create, and then Create.

Create Groups

1. In the left panel, expand Groups and select Overview.

2. Click New Group.

   

3. Select Security as the Group Type.

4. Enter a Group name.

5. Click No members selected.

   

6. Select all objects you want add to the group and click Select.

7. Click Create to finalize the group creation.

Configure the Federation between Entra ID and HID Authentication Service

The IdP supports both LDAP users in a directory (SCIM_FED user type) and non-directory users (defined as 'external' users in Entra ID).

The sections below explain how to configure federation between Entra ID and HID Authentication Service to dynamically synchronize users from your Entra ID group with your tenant.

For further information about federation, see:

• Configure Microsoft Azure for Provisioning

• Integrate your SCIM Endpoint with the Microsoft Entra Provisioning Service in the Microsoft documentation

Create the OpenID Client for Provisioning

POST https://[base-server-url]/idp/{tenant}/authn/register
{
	"redirect_uris": [
		"http://localhost:8080"
	],
	"client_id": "SCIM_FED_CLIENT",
	"client_name": "SCIM Federation Client",
	"token_endpoint_auth_method": "client_secret_basic",
	"hid_client_channel": "CH_EXTRAPP",
	"hid_client_pwd_policy": "AT_AADSYS",
	"hid_client_pki_policy": "AT_SYSPKI",
	"hid_user_channel": "CH_EXTRAPP",
	"hid_user_authn_policy": "AT_STDPWD",
	"hid_sessiontransfer_type": "NUM002",
	"hid_client_group": "UG_CLIENTID",
	"hid_federation_audiences": "",
	"hid_federation_roles": ".*",
	"hid_federation_atttype": "OAUTHFEDID",
	"hid_federation_channel": "",
	"backchannel_token_delivery_mode": "poll"
}

Update the Client's Permissions

To update the client's permissions, you need to assign the RL_CLIENTIDM2M role.

POST https://[base-server-url]/scim/{tenant}/v2/Users/.search
{
	"schemas": [
		"urn:ietf:params:scim:api:messages:2.0:SearchRequest"
	],
	"filter": "externalId eq SCIM_FED_CLIENT",
	"sortBy": "id",
	"sortOrder": "descending",
	"startIndex": 0,
	"count": 100
}

PUT https://[base-server-url]/scim/{tenant}/v2/Users/{id}
{
	"schemas": [
		"urn:ietf:params:scim:schemas:core:2.0:User"
	],
	"externalId": "{clientId}",
	"roles": [
		"RL_CLIENTIDM2M"
	]
}

Create a SCIM Federated User Repository

You need a unique ID for your federated user repository.

POST https://[base-server-url]/configuration/{tenant}/v2/User/Repository/ScimFed
{
	"schemas": [
		"urn:hid:scim:api:idp:2.0:User:Repository"
	],
	"id": "DS_aad1",
	"name": "SCIM federated user repository for Entra ID",
	"type": "SCIM_FED_AD",
	"adminGroupAssignment": {
		"value": "UG_ROOT"
	},
	"provisioningAgentCredential": {
		"value": "{id}"
	},
	"federatedAttributes": [
		{
			"value": "LASTNAME"
		},
		{
			"value": "FIRSTNAME"
		},
		{
			"value": "ATR_MOBILE"
		},
		{
			"value": "ATR_EMAIL"
		}
	]
}

Create an Entra ID Provisioning Application

1. Log on to the Microsoft Entra admin center as an Application Administrator.

2. Navigate to Identity, Applications and then Enterprise applications.

   A list of all configured apps is shown, including apps that were added from the gallery.

   

3. Click Create your own application.

4. Enter a name for your application, select the Integrate any other application you don't find in the gallery option and click Create to create an app object.

   The new app is added to the list of enterprise applications and opens to its app management page.

   

5. Under Manage in the left panel, select Provisioning.

6. From the Provisioning Mode drop-down menu, select Automatic.

7. Expand the Admin Credentials section.

8. In the Tenant URL field, enter the URL of the application's SCIM endpoint in the form https://[base-server-url]/scim/{tenant}/v2, where:

   • https://[base-server-url] is the fully qualified name of the HID Authentication Service

   • {tenant} is the ID of the HID Authentication Service tenant created previously

9. If the SCIM endpoint requires an OAuth bearer token from an issuer other than Microsoft Entra ID, copy the required OAuth bearer token into the optional Secret Token field.

   To get an access token from the OpenID client you created for provisioning (for example, SCIM_FED_CLIENT), execute an authentication request and get the access token from the response:

   Copy

   Sample request to get access token

   POST https://[base-server-url]/idp/{tenant}/authn/token HTTP/1.1
   grant_type=client_credentials&client_id={clientId}&client_secret={clientSecret}

   Note: The {clientSecret} was obtained when you created the OpenID Client for Provisioning.
   Copy

   Sample response

   HTTP/1.1 200 OK
   {
   	"access_token": "RTqmfQAAAZIqBhJ2kIwBT0tYPTdKdqrTeD7lJTpu",
   	"token_type": "Bearer",
   	"expires_in": 63072000
   }

10. Click Test Connection to verify that Microsoft Entra ID can connect to the SCIM endpoint:

    • If the attempts to connect to the application succeed, click Save to save the Admin Credentials

    • If the attempt fails, error information is displayed

11. Use the Entra admin center to assign users and groups to app-roles for your application.

Map the Attributes

1. In the Provisioning menu, expand the Mappings section.

   

2. Map the Users:

   1. Click on Provision Microsoft Entra ID Users.

   2. If a mapping for externalId already exists, delete it.

      

   3. Add a new mapping (or edit an existing userPrincipalName mapping) where userPrincipalName is the Source attribute and externalId is the Target attribute.

   4. Click Ok to validate the mapping.

      

   5. Add a new Constant mapping, with SCIM_FED as the value and userType is the Target attribute.

      This indicates to HID Authentication Service that you are creating a federated user.

   6. Click Ok to validate the mapping.

3. Click Save.

The resulting user attribute mapping should be:

Configure the Entra ID Redirection

Configure Entra ID to redirect users to the HID Authentication Service IdP for authentication.

Create an HID IDP Application

1. In the left panel, select App registrations.

   

2. In the menu bar, select New registration.

   

3. Enter an application Name.

4. Select Account in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) as the supported account type.

5. Set the Redirect URI:

   1. In the left drop-down list, select Web.

   2. Set the URI with the login endpoint of your tenant in the format https://[base-server-url]/idp/{tenant}/authn/login,

6. Click Register to create the application.

   The new application's Overview page is displayed.

   

Configure the Application Authentication

1. In the secondary left panel, select Authentication.

   

2. Select ID tokens (used for implicit and hybrid flows).

3. Make sure Account in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) is selected as the supported account type.

4. Click Save.

Add Users and Groups to the Application

Configure the groups and users who will be allowed to authenticate with this HID IDP application.

1. In the left panel, select Enterprise applications.

   

2. In the secondary left panel, select All applications and select the required application.

   

3. In the application Overview page, click Assign users and groups.

   

4. In the menu bar, select Add user/group.

   

5. In the secondary left panel, select None Selected.

6. Select the groups and users for whom you want to enable authentication using the HID Authentication Service IdP.

7. Click Select and then Assign.

   The groups and users should be displayed in Users and groups.

   

Configure an External Authentication Method (EAM)

Add an external authentication method to the application with the HID Authentication Service IdP server and OpenID client information.

1. In the left panel, select App registrations.

   

2. Click All applications.

3. Make a note of the Application (client) ID of the required application.

   

4. In the left panel, expand Protection and select Authentication methods.

5. In the Policies page, click Add external method.

   

6. Enter the required information:

   • Name - the name of the External authentication method displayed in the Microsoft interface when prompting the user to verify their identity (for example, HID Contactless Card)

     In the prompt, the label will be Approve with <your external method name> (for example, Approve with HID Contactless Card)

   • Client ID - the ID ("client_id") of the OpenID client created for Entra ID in the HID Authentication Service (for example, Client_ID_FLOWCARD_ENTRAID)

   • Discovery Endpoint - the URI of the 'Well-known' endpoint for your tenant

     https://[base-server-url]/idp/{tenant}/authn/.well-known/openid-configuration

   • App ID - the Application ID noted above

7. Click Request permission.

   

   1. Select an organization's administrator user.

      

   2. Click Accept to consent to the permissions request.

   

8. In the External Authentication Methods page:

   

   1. Enable your EAM.

   2. From the Add Target drop-down menu, select Select Targets.

      

   3. Select the groups and users who are allowed to use the HID Authentication Service IdP for authentication.

   4. Click Select.

9. Click Save.

Configure Conditional Access

1. In the left panel, expand Protection and select Conditional Access.

   

2. In the Overview page, select Create new policy.

   

3. Enter a Name for the policy.

4. Click the link below Users:

   1. In the Include section, select Select users and groups.

   2. Select Users and groups.

   3. Select the required groups and users and click Select.

5. Click the link below Target resources:

   

   1. In the Include section, select All cloud apps.

6. Click the link below Grant.

   

   1. Select Grant access.

   2. Select Require multifactor authentication.

   3. Select Require one of the selected controls.

   4. Click Select.

7. Enable the policy by selecting On.

8. Click Create.

Create the Card Application

Create a Card Auth application with POST /configuration/{tenant}/v2/Application/CardAuth.

During creation, the authentication type is bound to the CH_EXTRAPP channel and the UT_EMP user type.

{
	"id": "APP_CARD",
	"type": "MiFare Standard 1K, Contactless Writable",
	"name": "MiFare cards application",
	"notes": "Application for MiFare 1K Contactless Writable cards",
	"deviceType": {
		"id": "DT_CARD",
		"maximumDevicePerUser": 16
	},
	"credentialType": {
		"id": "CT_CARD"
	},
	"authenticatorPolicy": {
		"id": "AT_CARD",
		"defaultValidDaysAdd": -1,
		"defaultValidDaysEdit": -1,
		"disableThreshold": -1,
		"defaultExpiryThreshold": -1,
		"sessionTimeout": 1000000,
		"sessionValidPeriod": 10000000,
		"disabledTimeReset": -1,
		"levelOfAssurance": "urn:hidaaas:policy:at_card"
 	}
}

Attributes for compatible applications are:

Create and Assign a Card Authenticator (Optional)

If you set deviceBinding to required in the enrollment workflow, you must create and assign (bind) a Card authenticator to the user. The user can then 'bind' their Contactless Card to this authenticator using the IdP enrollment workflow.

Create a Card Authenticator

Use the Device endpoint to create the Card authenticator in the HID Authentication Service.

POST https://[base-server-url]/scim/{tenant}/v2/Device HTTP/1.1
Connection: close
Content-Type: application/scim+json
Authorization: Bearer RTp7HwAAAYNaPRn0EF8SAifAr62AFVQjcWITci7w
Content-Length: 229
Host: <hostname>
User-Agent: Apache-HttpClient/4.5.5 (Java/16.0.1)
{
	"schemas": ["urn:hid:scim:api:idp:2.0:Device"],
	"externalId": "mysmartcard",
	"type": "DT_CARD",
	"status": {
		"status": "PENDING",
		"expiryDate": "2050-06-12T14:46:58+0200",
		"startDate": "2024-06-12T14:46:58+0200"
	}
}

HTTP/1.1 200 OK
{
	"schemas": ["urn:hid:scim:api:idp:2.0:Device"],
	"id": "11992",
	"externalId": "mysmartcard",
	"meta":    {
		"resourceType": "Device",
		"created": "2022-09-20T09:31:59Z",
		"location": https://[base-server-url]/scim/{tenant}/v2/Device/11992,
		"version": "1"
	},
	"type": "DT_CARD",
	"status":    {
		"status": "PENDING",
		"active": false,
		"expiryDate": "2050-06-12T12:46:58Z",
		"startDate": "2024-06-12T12:46:58Z"
	}
}

Assign the Card Authenticator to the User

You can now assign the Card authenticator to the user using the Device endpoint.

The first step is to get the internal ID of the user using their external ID (for example, jsmith@company.com).

For further information, see Internal IDs VS External IDs and Managing Users, Groups and Roles (creating users).

POST https://[base-server-url]/{tenant}/v2/Users/.search HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json" 
{
	"schemas":[
		"urn:ietf:params:scim:api:messages:2.0:SearchRequest"
	],
	"filter":"externalId eq \"jsmith@company.com\"",
	"sortBy":"id",
	"sortOrder":"descending",
	"startIndex":0,
	"count":100
}

{
	"schemas":[
		"urn:ietf:params:scim:api:messages:2.0:ListResponse"
	],
	"totalResults":1,
	"resources":[
		{
			"schemas":[
				"urn:ietf:params:scim:schemas:core:2.0:User",
				"urn:hid:scim:api:idp:2.0:UserDevice",
				"urn:hid:scim:api:idp:2.0:UserAttribute",
				"urn:hid:scim:api:idp:2.0:UserAuthenticator"
			],
			"id": "11453",
			"externalId": "jsmith@company.com" 
		(...)     
		}
	]
}

PUT https://[base-server-url]/scim/{tenant}/v2/Device/11992 HTTP/1.1
Connection: close
Content-Type: application/scim+json
Authorization: Bearer RTp7HwAAAYNaPRn0EF8SAifAr62AFVQjcWITci7w
Content-Length: 271
Host: <hostname>
User-Agent: Apache-HttpClient/4.5.5 (Java/16.0.1)
{
	"schemas": ["urn:hid:scim:api:idp:2.0:Device"],
	"id": "11992",
	"type": "DT_CARD",
	"status": {
		"status": "PENDING",
		"active": false
	},
	"owner": {
		"value": "11453"
	}
}

HTTP/1.1 200 OK
{
	"schemas": ["urn:hid:scim:api:idp:2.0:Device"],
	"id": "11992",
	"externalId": "mysmartcard",
	"meta":    {
		"resourceType": "Device",
		"created": "2022-09-20T09:31:59Z",
		"location": https://[base-server-url]/scim/{tenant}/v2/Device/11992,
		"version": "1"
	},
	"type": "DT_CARD",
	"status":    {
		"status": "PENDING",
		"active": false,
		"expiryDate": "2050-06-12T12:46:58Z",
		"startDate": "2024-06-12T12:46:58Z"
	},
	"owner":    {
		"type": "User",
		"externalId": "jsmith@company.com",
		"value": "11453",
		"$ref": https://[base-server-url]/scim/{tenant}/v2/Users/11453
	}
}

Validate the Integration

Your users should be synchronized and available in your HID Authentication Service tenant.

For the validation purpose, you must have at least one user with an authenticator for the authentication method configured in the workflow for Entra ID.

You can test the integration by accessing a Microsoft application such as 365 (https://www.office.com/?auth=2) using your created user.

User Enrollment and Authentication

The following sections provide an overview of the Contactless Card enrollment and authentication process for end users.

Both processes require the HID Authentication Device Client, a lightweight client application adding support for authentication using smart card credentials. This client can be installed:

• Before enrollment - the client can be downloaded from the ActivID Customer Portal for distribution to your users

• During enrollment - the IdP detects that the client is not installed and displays a link to the installer, prompting the user to download and install it before continuing

Enrollment Process

Once you have deployed your workflow, the next time the user authenticates to the IdP, the option to enroll their card is displayed in the logon interface.

1. The user clicks the enrollment link and is directed to the enrollment process.

   

2. If the IdP detects that the HID Authentication Device Client is not installed on the computer, the user is prompted to download and install it.

   Note: The computer must be restarted after installing the client.

3. The IdP guides them through the process, based on the settings and criteria you have defined in the enrollment workflow.

   

   

4. If the enrollment is successful, the HID Authentication Service creates a new authenticator, device and credential (based on the card authentication policy, device and credential type parameters) for the user.

For details of the API enrollment flow, see the Enrollment endpoint.

Authentication Process

To authenticate with their enrolled card in the Entra ID MFA flow, the user experience depends on the settings and criteria you have defined in the authentication workflow.

1. The user first authenticates to the application (for example, Microsoft 365) with their password as the first factor.

2. As the second factor, the user selects to verify their identity using their enrolled Contactless Card.

   

3. The application redirects the user to the IdP authentication workflow.

4. If card authentication is configured, the HID Authentication Service checks if the user has an enrolled card credential.

5. If the user has a credential, the authentication is allowed and the HID Authentication Service displays the authentication prompt.

   

   Note: If the user does not have an enrolled card credential, authentication is not allowed. Depending on the defined workflow, the user can either enroll a card or authenticate with another method if available.

6. As the Username (User ID) is included in the request, the user does not need to enter it and is simply prompted to present their card for authentication.

7. The user taps or inserts their card into the reader.

   Note: The required action depends on the type of card and reader.

8. On successful authentication, the user is redirected back to the requested application.

For details of the API authentication flow, see the Code endpoint.