Microsoft Entra authentication

SAFEQ Cloud supports Microsoft Entra ID (formerly Azure AD) authentication for authenticating Microsoft Entra ID users to SAFEQ Cloud.

You can configure Microsoft Entra ID authentication to use either OpenID Connect (OIDC) authentication, service access authentication (implemented via Service Account), or both types simultaneously. Configuring an authorization provider with OIDC and service access can be helpful when you require enhanced security, user convenience, and support for all possible authentication options when authenticating into SAFEQ Cloud (e.g., Web UI, MFD terminal, etc.).

Be aware that OIDC on its own is incompatible with SAML Single sign-on. If you wish to use SAML, enable Service Account Authentication as well.

General settings

To add Microsoft Entra ID Authentication provider, perform the following steps:

1. Log in to SAFEQ Cloud Web UI and go to Users page and Authentication providers tab.

2. Click Add.

3. In Type, select Microsoft Entra ID.

4. Fill in the general settings:

   1. Name – An internal name used for identifying the particular authentication provider configuration. Should be prefilled with the selected Type.

   2. Domains – The domain names of the authenticating users. Add here the domain aliases that the users can use to log in. At least one domain in the list should match the domain part of the fully qualified username. If strict domain validation is disabled, SAFEQ Cloud will attempt to authenticate the user with all domains in the list when the username does not contain any domain, in the order defined in the list. If strict domain validation is enabled or the username contains a domain, SAFEQ Cloud will attempt to authenticate only with the domain in the credentials.
      

      For example, to allow user john.doe@acme.com to log in via this Authentication provider, enter the acme.com domain here.

      Microsoft Entra ID's limitation is that the domain in the user's email address must match the Microsoft Entra ID tenant domain. Otherwise, SAFEQ Cloud cannot synchronize the email address with the user.

      For example, if your Microsoft Entra ID's tenant domain is mycompany.com and there is a user with username john.doe@mycompany.com and e-mail john.doe@privatemail.com, the john.doe@privatemail.com e-mail won't be visible to SAFEQ Cloud.

   3. Priority – A number that determines the order in which authentication providers will be called until one succeeds. Higher-priority providers will be tried first.

   4. Active – If enabled, the authentication provider will be used for authentication. If disabled, this authentication provider will not be used for authentication. You can use this to disable the Authentication provider temporarily.

   5. Authentication method - types of authentication, which can be used for user validation and data synchronization

5. In the next steps, choose the authentication method.
   Here is an overview of the available methods. Detailed information you can find in the chapters below.

   1. OIDC – Most secure sign-in. Users log in on your identity provider's page, so credentials are never entered here.

   2. OIDC + System for Cross-domain Identity Management (SCIM) – Most secure and fully automated. Adds syncing of users and groups from your identity provider, so accounts stay up to date without manual upkeep. Enables card or PIN login at the MFD.

   3. OIDC + Service Account  – Secure sign-in with extra features. Combines OIDC login with Service Account for card or PIN login at the MFD terminal.

   4. Only Service Account  – Least secure option. Enables card or PIN login at the MFD, but on its own it doesn't offer secure sign-in — use it only when OIDC isn't available. This is a legacy type of authentication, and we do not recommend using it in newly set up Authentication providers.

OIDC Built-in configuration

When using the built-in OIDC authentication, users can log in via a predefined SAFEQ Cloud Microsoft Azure application (commonly named SafeQ - Authentication; its Application ID can be found in the authentication provider configuration in the OIDC section).

1. Log in to SAFEQ Cloud Web UI and go to Users page and Authentication providers tab.

2. Click Add and fill in the general settings (Type, Name, Domains, Priority, Active).

3. Select OIDC in the Authentication method drop-down list.

4. OIDC Authentication section – in the Type drop-down list, choose Built-in and fill in the fields accordingly

   1. Hide on Login Page - Enable this option to hide the Microsoft Entra ID button on the SAFEQ Cloud login page. Otherwise, the name displayed on the button is taken from the Name field.
      Example:
       

      If the Hide on Login Page option is enabled, no "Login via <Provider Name>" button will be displayed on the login screen. To authenticate via such an authentication provider, users need to fill in the username containing a domain matching the authentication provider, which will redirect them to the OIDC authentication flow (the same way as clicking the "Login via <Provider Name>" button.

5. SCIM section: is shown when the OIDC + System for Cross-domain Identity Management (SCIM) authentication method is selected, and the OIDC is used in combination with SCIM.
   Service account Authentication section: is shown when the OIDC + Service account authentication method is selected, and the OIDC is used in combination with a service account.

6. This is an example of the final configuration:

   

7. Click Save.

8. Microsoft Entra ID users can now log in to SAFEQ Cloud.
   

OIDC + System for Cross-domain Identity Management (SCIM)

SCIM (System for Cross‑domain Identity Management) is a standard protocol that enables automated exchange of identity information between systems. With SCIM integration, user and group creation, updates, and deactivation in an Identity Provider (for instance, in Microsoft Entra ID) are automatically synchronized/provisioned to SAFEQ Cloud.
See the About SCIM page for more information about SAFEQ Cloud SCIM implementation.
See Understand how Application Provisioning in Microsoft Entra ID page for more information about Microsoft Entra ID SCIM implementation.

To connect Microsoft Entra ID with SAFEQ Cloud using SCIM, you must create and configure a custom Enterprise application in Entra ID. This application serves as a communication bridge between Entra ID and the SAFEQ Cloud SCIM endpoint, enabling automatic creation, updating, and deactivation of users and groups in SAFEQ Cloud.

The configuration requires:

• activating and configuring SCIM provisioning in SAFEQ Cloud

• creating and configuring a new Enterprise application that will act as the SCIM connector

  • configuring the SCIM URL and security token obtained from SAFEQ Cloud

  • adjusting attribute mappings to match SAFEQ Cloud requirements

  • selecting which users or groups will be provisioned (scoping)

  • activating provisioning and starting synchronization

After completing these steps, Microsoft Entra ID will start sending changes of users and groups automatically to SAFEQ Cloud, without manual intervention.

The Microsoft Entra admin center is the strategic and recommended management interface for SCIM provisioning. While Azure Portal may still expose some related functionality, Microsoft documentation, new capabilities, and the most complete identity-management experience are focused on the Entra admin center.

Configuring an Authentication provider in SAFEQ Cloud

To connect SAFEQ Cloud with Microsoft Entra ID using SCIM, first configure SCIM in a SAFEQ Cloud Authentication Provider (see the steps below).

For SCIM provisioning, these two values are important:

• Tenant URL for SCIM configuration – the SAFEQ Cloud API address where Microsoft Entra ID will send SCIM requests

• Secret Token – a “password” used by Entra ID to authenticate to SAFEQ Cloud

You will use these values later when configuring the Enterprise application in Microsoft Entra ID.

Steps to configure a SAFEQ Cloud Authentication Provider:

1. Log in to SAFEQ Cloud Web UI, and go to the Users page and the Authentication providers tab.

2. Click Add and fill in the general settings (Type, Name, Domains, Priority, Active).
   Or select an existing Authentication Provider and click the Edit icon . In this case, please also read “How to safely switch your existing Authentication Provider to OIDC+SCIM“.

3. Select “OIDC + System for Cross-domain Identity Management (SCIM)” in the Authentication method drop-down list.

4. The SCIM section appears, and it is prefilled.
   Remember the generated Secret token.

   

5. Click Save.

6. The “SCIM Provisioning is ready“ window pops up.
   Remember the displayed Tenant URL.

   

After saving, SAFEQ Cloud is ready to receive SCIM provisioning from Microsoft Entra ID. The next step is to create and configure the Enterprise application in Entra ID.

Configuring SCIM in Microsoft Entra ID

This part continues in the Microsoft Entra admin center. You now have the Tenant URL and Secret token from SAFEQ Cloud and can create the SCIM connector.

Creating the Enterprise application

1. Log in to the Microsoft Entra admin center.

2. Open Enterprise apps.

3. Click New application.

4. Select Create your own application.

5. Enter a name, for instance “SAFEQ Cloud SCIM”.

6. Choose: Integrate any other application you don’t find in the gallery (Non‑gallery).

7. Confirm creation.

For details, see the Microsoft documentation: Integrate your SCIM endpoint with the Microsoft Entra provisioning service

Configuring the SCIM connection (Tenant URL + Secret Token)

1. In the created Enterprise application, click the Provisioning item from the left-side Manage menu.

2. Click the New configuration button

   

3. Fill in the Admin Credentials

   1. Select the “Bearer authentication“ method

   2. Enter the Tenant URL from SAFEQ Cloud.

   3. Enter the Secret Token from SAFEQ Cloud.

4. Click Test Connection to verify connectivity.

5. After a successful test, click Create.

For details, see the Microsoft documentation Integrate your SCIM endpoint with the Microsoft Entra provisioning service

The new provisioning configuration is now successfully created.

This provisioning configuration has not started yet. Also, its settings are not complete yet.
Follow the next steps to complete the configuration and start the automated users and group provisioning.

Adjusting attribute mappings

SCIM schema defines many user and group attributes that can be synchronized via the SCIM protocol. SAFEQ Cloud supports a subset of these attributes. Further, SAFEQ Cloud extends the SCIM schema with print-specific user attributes. See the About SCIM page for a complete list of the attributes.

On the other side, the Microsoft Entra ID - through the Enterprise application created in the previous steps - maps its user and group attributes to the SCIM user and group attributes. This Entra ID attributes' mapping needs to be adjusted.

Steps to define print-specific user SCIM attributes:

1. In the application details, open Provisioning.

2. In the provisioning details, select Provisioning.

3. In the Mappings section, click Provision Entra ID Users.

4. At the bottom, below the “Attribute Mappings“ table, select the checkbox “Show advanced options“.

5. Additional links appear → click on “Edit attribute list for customappsso“.

6. At the bottom of the table “customappsso User Attributes“, add the following print-specific user SCIM attributes
   - fill the Name column; the Type is always String, all other columns remain empty:

   • urn:ietf:params:scim:schemas:extension:print:2.0:User:department

   • urn:ietf:params:scim:schemas:extension:print:2.0:User:nameAlias

   • urn:ietf:params:scim:schemas:extension:print:2.0:User:homeFolder

   • urn:ietf:params:scim:schemas:extension:print:2.0:User:pin

   • urn:ietf:params:scim:schemas:extension:print:2.0:User:cardNumbers
     
     The table “customappsso User Attributes“ will look like that depicted in the picture below:

     

7. Save the changes

Steps to remove mapping of unsupported attributes and map the print-specific user SCIM attributes

1. In the application details, open Provisioning.

2. In the provisioning details, select Provisioning.

3. In the Mappings section, click Provision Entra ID Users.

4. Delete all attributes from the “Attribute Mappings“ table, except the required basic attributes.

5. Save the changes.

6. At the bottom, below the “Attribute Mappings“ table, click on the “Add New Mapping“ link.

7. On the opened form

   • In the field Target attribute, select one of the print-specific user SCIM attributes, e.g. “urn:ietf:params:scim:schemas:extension:print:2.0:User:pin“

   • In the field Source attribute, select such an Entra ID attribute which holds the value corresponding to the selected target (in case of “pin“ select the Entra ID attribute containing the PIN value)

   • Click OK

8. Repeat the previous step for each print-specific user SCIM attribute.

9. Save the changes.

Your attribute mapping will look like that depicted in the picture below:

Steps to verify the group attributes mapping

Mapping of the group attributes is much simpler - it is fine to keep the default mapping.
To verify the group attributes mapping is as expected:

1. In the application details, open Provisioning.

2. In the provisioning details, select Provisioning.

3. In the Mappings section, click Provision Entra ID Groups.

4. Verify the Attribute Mappings and all other settings are the same as depicted in this picture:

Choose a scope to be provisioned

Provisioning applies only to users and groups within the application's defined scope.

In the Provisioning → Settings section, you can choose from two scopes:

• Sync all users and groups
  All users listed in the Entra ID will be taken into account

• Sync only assigned users and groups
  Go to the Manage users and groups assignment to an application - Microsoft Entra ID | Microsoft Learn documentation to see details

Furthermore, an additional filter can be applied to the users to be provisioned.
Here is an example where the scope is “All users and groups” but both entities are filtered - users in the first picture and groups in the second picture:

The documentation Scoping users or groups to be provisioned with scoping filters in Microsoft Entra ID - Microsoft Entra ID | Microsoft Learn describes how to limit the scope.

Activating provisioning and Initial sync cycle

Now, everything is ready to activate the automatic synchronization of users and groups to SAFEQ Cloud.

1. In the application details, open Provisioning.

2. In the provisioning details, select Overview

3. Click the Start provisioning button at the top of the Overview screen

   

After starting, Entra ID will begin synchronizing users and groups to SAFEQ Cloud. It will execute the regular synchronization cycles (~ every 40 minutes).

You can see whether any and when the last cycle ran:

The initial sync cycle, where all users and groups are synchronized, may take longer (tens of minutes, hours).

Then, Entra ID continues running back-to-back incremental cycles indefinitely, at intervals approx. every 40 minutes.

There is the Restart provisioning option in the Microsoft Entra admin center, which triggers a new initial cycle. The action clears any stored watermark and causes all users and groups to be evaluated again.

Monitoring & Troubleshooting SCIM provisioning

Email notification from Entra ID

Entra ID offers to send an email notification when a user provisioning failure occurs.

How to set it up:

1. In the application details, open Provisioning.

2. In the provisioning details, select Provisioning.

3. In the Settings section, select the option “Send an email notification when a failure occurs“

4. Fill the Notification Email

5. Save the changes

See Learn how Provisioning logs integrate with Azure Monitor for advanced possibilities.

Provisioning logs in Entra ID

Where to find it:

1. In the application details, open Provisioning.

2. In the provisioning details, select Provisioning.

3. In the left-side Monitor menu, click the Provisioning log item.

What you will see:

• each provisioning step (create/update/delete)

• errors (400, 401, 403, 404, 409, 500…)

• detailed JSON request + response

• timestamp of when the change was processed

• status (Success / Skipped / Failed)

Troubleshooting application provisioning in Entra ID

Refer to the following Microsoft Entra ID documentation for additional troubleshooting aspects:

• Known issues for provisioning in Microsoft Entra ID

• Troubleshoot provisioning to a Microsoft Entra gallery app.

• Quarantine status in Microsoft Entra Application Provisioning

• Users aren't being provisioned in my application

• Create custom attributes in Microsoft Entra ID for mapping (useful when you want to have dedicated fields e.g. card number(s) or PIN in Entra ID)

• How to analyze the Microsoft Entra provisioning logs

• Known issues with System for Cross-Domain Identity Management (SCIM) 2.0 protocol compliance

Audit logs

Where to find it:

SAFEQ Cloud Web UI → Reports → Audit Logs

What you will see:

• Log entries for successful SCIM-related operations (User created, User updated, User deleted).

• They have the value “SCIM API“ in the column “User”.

Service account authentication

This method enables authentication on MFD using data from a remote identity provider (e.g., card, PIN, or credentials). It also allows displaying user department in accounting reports and enables lookup of Microsoft Entra ID users in web UI even before their first interaction with SAFEQ Cloud. Customers who use self-registered cards, API-imported cards, or do not require department reporting typically don’t need to activate it.

To configure Microsoft Entra ID authentication using a service account, first, you need to create an App registration in Microsoft Azure. To do that, perform the following steps:

Registering a new Microsoft Azure app

1. Log in to the Azure Portal and click Manage Microsoft Entra ID.

2. Click App registrations.
   

   

3. Click the +New registration button.

4. Enter the name of your new application, select one of the supported account types, and leave the Redirect URI field empty.
   

   

5. Click Register.

6. Click API permissions.
   

   

7. Click Microsoft Graph (1) and delete the User.Read permission.

8. Click Add a permission.

9. Select Microsoft Graph from Commonly used Microsoft APIs.

10. Click Delegated permissions.
    

    

11. Search for the permissions required, and then click Add Permissions.
    

    

    
    Minimum Permissions Required are:

    • GroupMember.Read.All – Allows the app to list groups and to read their properties and all group memberships on behalf of the signed-in user

    • User.Read.All – Allows the app to read the full set of profile properties, reports, and managers of other users in your organization on behalf of the signed-in user.
      
      

      Additional permissions may be required to read custom attributes or similar. Add them based on your specific configuration of Microsoft Entra ID and attribute mapping configured in SAFEQ Cloud.

12. Grant the admin permissions by clicking Grant admin consent for, then click Yes to approve.

13. Your App Registration should now display the following.
    

    

14. Click Authentication and Set Allow public client flows to Yes.
    
    

    The Service account needs the Allow public client flow functionality for fetching information about a particular user or group from Entra ID and for username/password authentication. Namely, the Username+password type of login on MFDs, the Manual login authentication type in the SAFEQ Cloud Client, and logging in to SAFEQ Cloud Web UI without OIDC. If you wish to use the Service account, the Allow public client flow must be enabled

    Note that SAFEQ Cloud doesn't store the usernames and passwords, but that they are passed through SAFEQ Cloud to Entra ID for validation. Therefore, they might potentially be intercepted by attackers on the way.

15. Microsoft Entra ID app configuration for Service account authentication is now complete.

16. To allow authentication using PINs and cards stored in Microsoft Entra ID or to display user’s department in reports, follow:
    Synchronizing user card, PIN or department from Microsoft Entra ID

Creating an Authentication provider in SAFEQ Cloud

This Authentication provider will use the app registration which you have just created.

1. Log in to SAFEQ Cloud Web UI and go to Users page and Authentication providers tab.

2. Click Add and fill in the general settings (Type, Name, Domains, Priority, Active).

3. Select Service Account in Authentication method drop down list

4. Service Account Authentication – this section applies to service account settings
   

   1. Application ID – The ID of your registered Azure App.

   2. User name – Name of the user to be used for the Microsoft Graph API access.

   3. Password – Password for the above-mentioned user.

   4. Cache expiration in seconds – The time the authentication information is kept in the internal cache to reduce the calls from SAFEQ Cloud to Microsoft Entra ID. We recommend at least 2 minutes.

   5. Custom attributes – Expand custom attributes to change the Microsoft Entra ID attributes in which usernames, card IDs, ShortIDs, and others are stored.

   6. Service – Select which Authentication Service will communicate to this Microsoft Entra ID server. In case no service is already created, you can add it by clicking Add. If the primary server has only one authentication service, or if there's only one authentication service in general, it is pre-selected by default.
      
      

      

      
      

   7. Click Save.

5. The Microsoft Entra ID users can now log in to SAFEQ Cloud. 

OIDC Customizable configuration

If you want to configure custom Microsoft Entra ID OIDC authentication, you must first configure Microsoft Azure App registration and then use it for the authentication provider in SAFEQ Cloud. To create a new Microsoft Azure App registration, perform the following steps:

Registering a new Microsoft Azure app

1. Log in to the Azure Portal and click Manage Microsoft Entra ID.

2. Click App registrations.
   

   

3. Click the +New registration button.

4. Enter your new application's name, choose Single tenant (Accounts in this organizational directory only) or Multitenant (Accounts in any organizational directory) account type. However, we recommend Single tenant. Fill in the Redirect URI field. The Redirect URI pattern is: https://<account-domain>:<port>/callback/oidc-login

   • The port for callback URIs is, by default, 8443. Example: https://print.acme.com:8443/callback/oidc-login

   • In environments with reverse proxy infrastructure, do not specify the port number in the URL, meaning the default HTTPS port 443 will be used. Example: https://print.acme.com/callback/oidc-login

   • The account domain is your domain defined in SAFEQ Cloud. It must be the same as the Callback domain selected in the Authentication Provider form, which you will fill in later.

   

   
   

5. Go to Authentication. In the Web section, click Add URI and fill the URI with a pattern: https://<account-domain>:<port>/callback/acl
   

   • The port for callback URIs is, by default, 8443. Example: https://print.acme.com:8443/callback/acl

   • In environments with reverse proxy infrastructure, do not specify the port number in the URL, meaning the default HTTPS port 443 will be used. Example:  https://print.acme.com/callback/acl

   • The domain is your domain defined in SAFEQ Cloud. It must be the same as the domain selected in the Authentication form, which you will fill out later.

   • Keep the Front-channel logout URL empty.

   

6. Click Save.

   In total, there should be these callback domains defined:

   • https://<domain>:<port>/callback/oidc-login. For environments with reverse proxy: https://<domain>/callback/oidc-login

   • https://<domain>:<port>/callback/acl. For environments with reverse proxy https://<domain>/callback/acl

7. Go to Certificates & secrets and click + New client secret. Optionally, set the Expires value according to your security policy. Click Add.
   
   

8. Copy the secret value and save it securely. You will need it later for the SAFEQ Cloud authentication provider configuration.

   You can only see the secret value during creation time for security reasons. Once you leave the screen, the value will not be shown again.

   Because the Client secret has limited validity, remember to create a new one before it expires and replace the old one either in SAFEQ Cloud Web UI or using SAFEQ Cloud API. See the API documentation > API Functions > section Authentication provider.

   

9. Go to Token configuration, click + Add groups claim, and define the groups that will be part of the users' ID Token. This will be used later in the Access Control configuration in SAFEQ Cloud.
   

   

10. The result will look like this. Microsoft Entra ID app configuration for OIDC authentication is now finished.
    

    

Next, you must create the Authentication provider in SAFEQ Cloud, which will use the app registration you just created.

Creating an Authentication provider in SAFEQ Cloud

1. Log in to SAFEQ Cloud Web UI and go to Users page and Authentication providers tab.

2. Click Add and fill in the general settings (Type, Name, Domains, Priority, Active, and Authentication method).

3. Select OIDC in Authentication method drop down list.

4. OIDC Authentication section – in Type drop-down list, choose Customizable and fill in the fields accordingly:

   1. Client ID – The ID of the registered Azure App you created in previous steps.

   2. Client secret – The secret value you created for the registered Azure App in previous steps.

   3. Entra directory (tenant) ID or domain – If you selected the Multitenant account type during the Entra App registration, keep this field blank. Fill it only if you selected the Single tenant account type. You can find the directory (tenant) ID in the Overview section of the registered Entra App or in the Directories + subscriptions menu in Portal settings.
      

      

      
      

      

   4. Callback domain for custom application – Select from the list of available domains the one that you defined in Azure App registration as Redirect URI in previous steps, e.g. print.acme.com .

   5. Custom token claim names – Click Show to change the mapping between the ID token and Microsoft Entra ID user attributes, such as preferred_username, name, email, and groups.

   6. Hide on Login Page – Enable this option to hide the Microsoft Entra ID button on the SAFEQ Cloud login page. Otherwise the name displayed on the button is taken from the Name field.
      Example:
      

      If the Hide on Login Page option is enabled, no "Login via <Provider Name>" button will be displayed on the login screen. To authenticate via such an authentication provider, users need to fill in the username containing a domain matching the authentication provider, which will redirect them to the OIDC authentication flow (the same way as clicking the "Login via <Provider Name>" button.

5. SCIM section: is shown when the OIDC + System for Cross-domain Identity Management (SCIM) authentication method is selected, and the OIDC is used in combination with SCIM.
   Service account Authentication section: is shown when the OIDC + Service account authentication method is selected, and the OIDC is used in combination with a service account.

6. Click Save.
   

   

   
   

7. The Microsoft Entra ID users can now log in to SAFEQ Cloud.