Synchronizing user card, PIN or department from Microsoft Entra ID

Microsoft Entra ID stores various user information in attributes, such as userPrincipalName (john.doe@sample.com), displayName (John Doe), department (Laboratory), customattributecard (123456789). SAFEQ Cloud can be configured to read them to enhance user experience.

This article demonstrates how to utilize user's department from Microsoft Entra ID for reporting purposes.

The similar approach can be taken to allow usage of cards stored in Microsoft Entra ID for authentication on MFD.

Card and Short ID synchronized through Microsoft Entra ID is not going to be visible on web UI, however users can still use it for authentication without any issue.

Microsoft Entra ID provides so called Directory Extension, a custom attribute created by administrator or migrated from on-prem AD. Directory Extension has a unique naming convention extension_<appID>_<extensionProperty-name>. To ensure SAFEQ Cloud utilizes the value from the Directory Extension, make sure to follow its naming convention when verifying attribute presence via Graph Explorer and when configuring SAFEQ Cloud. Typically <appID> is ID of Microsoft Entra ID application used to create the extension, <extensionProperty-name> is the custom name of the extension. For details refer to:
https://learn.microsoft.com/en-us/entra/identity/hybrid/cloud-sync/custom-attribute-mapping
https://learn.microsoft.com/en-us/azure/active-directory-b2c/user-flow-custom-attributes?pivots=b2c-user-flow

Microsoft Entra ID provides custom attribute onPremisesExtensionAttributes with sub-parameters extensionAttribute1 - extensionAttribute15 (see Microsoft documentation). To ensure SAFEQ Cloud utilizes values from these attributes, set the custom attribute in SAFEQ Cloud to extensionAttribute1 (or extensionAttribute2, extensionAttribute3 ...).

You can query the presence of these attributes via Graph Explorer with the following GET request:
https://graph.microsoft.com/v1.0/me?$select=userPrincipalName,onPremisesExtensionAttributes

To check that GraphAPI finds a user with extensionAttribute1 set to card123, use this GET request:
https://graph.microsoft.com/v1.0/users?$select=userPrincipalName,onPremisesExtensionAttributes&$count=true&$filter=accountEnabled eq true and ((onPremisesExtensionAttributes/extensionAttribute1 eq 'card123'))
Additionally the header ConsistencyLevel = eventual must be set.

Steps to take:

Make sure that "department" is set in Microsoft Entra ID
- fill in user's department
  - details at https://learn.microsoft.com/en-us/entra/fundamentals/how-to-manage-user-profile-info
- verify the attribute exists and has the right value
  - details at https://learn.microsoft.com/en-gb/graph/api/resources/user?view=graph-rest-1
    
    Example
    
    Go to https://developer.microsoft.com/en-us/graph/graph-explorer
    Authenticate as end user that has "department" filled in
    Run query: https://graph.microsoft.com/v1.0/me?$select=displayName,givenName,department,userPrincipalName
Set up authentication provider with enabled "Service Account Authentication"
- full guide here:
  - Microsoft Entra authentication
- in brief:
  - create new app in Microsoft Entra ID
  - create new user in Microsoft Entra ID
    - note: no special roles required, user department will be obtained through permission scope of the new Microsoft Entra ID application
  - verify that new user can log in to https://portal.azure.com
    - note: typically a first time password change is required, inability to log in would prevent SAFEQ Cloud from using the account
  - create "Microsoft Entra ID" provider in SAFEQ Cloud
    - enable OIDC authentication Built-in (optional but advised)
    - enable "Service Account Authentication and use details of your new app and new user
- click "Show" next to "Custom attributes" inside the provider
- put "department" (without quotes) in department section
Wait for users to authenticate through this provider
- authentication triggers refresh of user information, user may authenticate e.g. via web or PC client
Verify that department is visible in user details
- SAFEQ Cloud > Users > select your Microsoft Entra ID provider > Search for user
From this moment jobs performed by this user will have department filled in and visible in reports.