Provision administrator accounts from Entra ID using SCIM

In this topic, you will learn how to create and manage Portnox™ Cloud administrator accounts in Microsoft Entra ID using SCIM.

SCIM (System for Cross-domain Identity Management) is an open standard protocol for managing user identities across applications. With SCIM, you create and manage Portnox Cloud administrator accounts in Entra ID. When you assign Entra ID users to the SCIM application, Portnox Cloud creates administrator accounts for these users. When you change the attributes of these users in Entra ID, Portnox Cloud updates their administrator accounts.

Note:

SCIM provisioning does not require a Portnox Cloud integration with Entra ID (see the following topic: Integrate with Microsoft Entra ID). The SCIM application is a separate Entra ID enterprise application.

Important:

Don’t edit or delete SCIM-provisioned administrator accounts in the Portnox Cloud portal. Manage them only in Entra ID. Portnox Cloud behavior for accounts managed both in the portal and through SCIM is undefined.

Create an application API integration in Portnox Cloud

In this section, you will create a SCIM application API integration in Portnox Cloud.

In the Cloud portal top menu, click on the Settings option.
In the Cloud portal left-hand side menu, click on the Integration Services > APPLICATION API INTEGRATIONS option.
Click on the Add API integration button.
Enter a Name for the integration and in the Capability field, select the Admin provisioning (SCIM) option. Then, click on the Next: View variables button.

Portnox Cloud displays the values that you need for the Entra ID application: Tenant URL, OAuth token endpoint, Client identifier, and Client secret.
Keep this browser tab open.

From now on, we will call this tab the Portnox tab.

Important:
Portnox Cloud shows the client secret only once. If needed, click on the ⧉ icon before you click on the Finish button and save the copied value in a temporary text file. You cannot retrieve it later.

Create a new Entra ID enterprise application

In this section, you will access the Microsoft Azure administrative interface and use it to create a new Entra ID enterprise application for SCIM provisioning.

In another tab of your browser, open your Microsoft Azure Portal by accessing the following URL: https://portal.azure.com/
From now on, we will call this tab the Azure tab.
In the Azure Portal main menu, click on the Microsoft Entra ID option.
In the left-hand side menu, click on the Manage > Enterprise applications option.
In the top menu of the Enterprise applications screen, click on the New application button.
In the top menu of the Browse Microsoft Entra Gallery screen, click on the Create your own application button.
In the Create your own application pane, enter a name for the new application in the What is the name of your app field, select the Integrate any other application you don’t find in the gallery (Non-gallery) option, and then click on the Create button.

In this example, we used the name Portnox SCIM integration for the new application but you can use any name you like.
In the left-hand side menu of the application pane, click on the Manage > Provisioning option.
Keep this browser tab open.

From now on, we will call this tab the Azure tab.

Connect the Entra ID application to Portnox Cloud

In this section, you will copy the values displayed by Portnox Cloud and paste them in the connectivity settings of the Entra ID application.

In the Azure tab, in the Create configuration section, click on the Connect your application button.
In the New provisioning configuration pane, in the Select authentication method field, select the OAuth2 client credentials grant option.
Copy the connection values from the Portnox tab to the Azure tab.
1. In the Portnox tab, click on the ⧉ icon next to the Tenant URL field. In the Azure tab, paste the value into the Tenant URL field.
2. In the Portnox tab, click on the ⧉ icon next to the OAuth token endpoint field. In the Azure tab, paste the value into the OAuth token endpoint field.
3. In the Portnox tab, click on the ⧉ icon next to the Client identifier field. In the Azure tab, paste the value into the Client identifier field.
4. In the Portnox tab, click on the ⧉ icon next to the Client secret field. In the Azure tab, paste the value into the Client secret field.
Click on the Test connection button. After the test succeeds, click on the Create button.
In the Portnox tab, click on the Finish button.

Disable the group provisioning

In this section, you will disable the group provisioning in the Entra ID application. Portnox Cloud provisions administrator accounts, not groups.

In the Azure tab, in the left-hand side menu of the application pane, click on the Manage > Scoping filters option.
In the top menu, click on the Edit button.
In the Scope settings step, click on the Groups tab, and then set the Enabled option to Disabled.
Click on the Next button in the bottom-right corner four times, and then click on the Save button in the same location.

The Groups tab in the Scope settings section shows the Disabled value next to the Enabled field.

Map the administrator attributes

In this section, you will map the Entra ID attributes that set the repository and the administrator type of each Portnox Cloud administrator account.

Portnox Cloud uses the following SCIM attributes:


Target attribute	Purpose	Value	Result
`userType`	Sets the identity repository of the administrator account. Portnox Cloud uses this repository to authenticate the administrator at login.	`Clear`	Portnox Cloud repository
		`EntraId`	Entra ID repository
		`Google`	Google Workspace repository
		`Okta`	Okta repository
`roles[primary eq "True"].value`	Sets the administrator type.	`FullAdmin`	Administrator
		`ReadOnlyAdmin`	Read-only Administrator
		`GuestAdmin`	Guest Administrator
		`ReadOnlyGuestAdmin`	Guest Administrator + Read-only

We recommend that you use EntraId for the userType attribute.

Important:

If you use a value other than EntraId, the administrator cannot log in with Entra ID SSO. For example, with Clear, Portnox Cloud creates a Cloud administrator account. The administrator logs in with the value mapped to the userName attribute (by default, the Entra ID user principal name). They set a password using a link that Portnox Cloud sends via email.

In the Azure tab, in the left-hand side menu of the application pane, click on the Manage > Attribute mapping option.
In the Users tab, in the top menu, click on the Add attribute mapping button.
Add the mapping for the repository.
1. In the Mapping type field, select the Constant option.
2. In the Constant attribute (Microsoft Entra ID) field, enter EntraId.
3. In the Target attribute (customappsso) field, select the userType option.
4. Click on the Add button at the bottom of the Add Attribute Mapping pane.

Then, map the administrator type using one of the two approaches described in the following sections.

Map administrator types using an expression

In this section, you will map the administrator type of each Portnox Cloud administrator account using an expression based on Entra ID user attributes.

In this approach, an expression sets the administrator type of each user based on their Entra ID attributes, for example their department or job title.

Advantages:

You can assign many users to the application at once. Entra ID sets the administrator type of each user based on their attributes.
When users move to a different department or job, Entra ID updates their administrator type. You only change the application assignments to add or remove Portnox Cloud administrators.
You don’t need to choose an administrator type when you assign users. Their department or job title decides it.

Disadvantages:

Less granular control. All users with the same attribute value get the same administrator type.
You must remember which attribute values give which administrator type.

Important:

This is one of two ways to set the administrator type. The next section shows another approach. Complete only one of these sections depending on your preference.

In the Users tab, in the top menu, click on the Add attribute mapping button.
Add the mapping for the administrator type.

Note:
You can also use the Constant mapping type to give all assigned users the same administrator type. The following procedure uses the Expression mapping type, which lets you choose the administrator type for each user based on their Entra ID attributes.
1. In the Mapping type field, select the Expression option.
2. In the Expression field, enter a Switch expression.
  Use the following format:
```
Switch([attribute], "default", "key1", "value1", "key2", "value2")
```
  - attribute: The Entra ID user attribute to check, for example department or jobTitle.
  - default: The administrator type for users whose attribute value matches no key.
  - key and value pairs: If the attribute value is exactly key, the user gets the administrator type value. Add as many pairs as you need.
  Each default and value must be one of the roles[primary eq "True"].value values from the table in the previous section.
  Examples:
  - Users in the IT department get full administrator access. All other assigned users get read-only access:
```
Switch([department], "ReadOnlyAdmin", "IT", "FullAdmin")
```
  - Users in the IT department get full administrator access. Users in the Support department get guest administrator access. Users in the Onboarding department get guest administrator and read-only access. All other assigned users get read-only access:
```
Switch([department], "ReadOnlyAdmin", "IT", "FullAdmin", "Support", "GuestAdmin", "Onboarding", "ReadOnlyGuestAdmin")
```
  - Users with the Network Administrator job title get full administrator access. Users with the Support Technician job title get guest administrator access. Users with the Onboarding Technician job title get guest administrator and read-only access. All other assigned users get read-only access:
```
Switch([jobTitle], "ReadOnlyAdmin", "Network Administrator", "FullAdmin", "Support Technician", "GuestAdmin", "Onboarding Technician", "ReadOnlyGuestAdmin")
```
3. In the Target attribute (customappsso) field, select the roles[primary eq "True"].value option.
4. Click on the Add button at the bottom of the Add Attribute Mapping pane.
Click on the Save button at the bottom of the Attribute mapping pane, then click on the Yes button in the confirmation dialog.

Note:

You can set the value of each attribute using any logic based on Entra ID user attributes. To build and test more complex expressions, click on the Use the expression builder link below the Expression field in the Add Attribute Mapping pane.

Map administrator types using app roles

In this section, you will map the administrator type of each Portnox Cloud administrator account using app roles, and create an app role for each administrator type. You will select the app role for each user when you assign them to the application.

In this approach, you create an app role for each administrator type. When you assign users to the application, you select the app role for them.

Advantages:

Granular control. You choose the administrator type for each user, regardless of their department or job title. For example, if two network administrators work in the IT department, you can give full access to one and read-only access to the other.

Disadvantages:

More work when assigning users. You must assign users in separate batches, one for each administrator type.
More work when managing users. To change the administrator type of a user, you must change their assignment in the application. Changes in the directory don’t affect it.

Important:

This is one of two ways to set the administrator type. The previous section shows another approach. Complete only one of these sections depending on your preference.

In the Users tab, in the top menu, click on the Add attribute mapping button.
Add the mapping for the administrator type.
1. In the Mapping type field, select the Expression option.
2. In the Expression field, enter the following expression:
```
SingleAppRoleAssignment([appRoleAssignments])
```
  This expression returns the app role assigned to the user.
3. In the Target attribute (customappsso) field, select the roles[primary eq "True"].value option.
4. Click on the Add button at the bottom of the Add Attribute Mapping pane.
Click on the Save button at the bottom of the Attribute mapping pane, then click on the Yes button in the confirmation dialog.
In the left-hand side menu of the application pane, click on the Manage > Users and groups option. Then, click on the application registration link in the description at the top of the pane.
In the left-hand side menu of the app registration pane, click on the Manage > App roles option.
Create an app role for an administrator type.

Note:
Repeat this step to create an app role for each of the four administrator types.
1. In the top menu, click on the Create app role button.
2. In the Create app role pane, in the Display name field, enter one of the roles[primary eq "True"].value values from the table in the Map the administrator attributes section.
  
  Important:
  The Display name must be exactly the same as the Value, with no spaces. Entra ID sends the display name to Portnox Cloud instead of the value.
3. In the Allowed member types section, select the Users/Groups option.
4. In the Value field, enter the same value as in the Display name field.
5. In the Description field, enter a description for this role (mandatory).
6. Click on the Apply button.
Result: You can see the new app roles in the App roles list.

Note:
The list also contains the default User and msiam_access app roles. These roles are not valid administrator types. Do not assign them to users of this application.

Assign users and start provisioning

In this section, you will select the Entra ID users that become Portnox Cloud administrators and start the provisioning process.

Optional: If needed, go back to the provisioning settings of the enterprise application. In the Azure tab, in the left-hand side menu, click on the Entra ID > Enterprise apps option, click on the name of the application that you created for SCIM provisioning, and then click on the Manage > Provisioning option.
In the Azure tab, in the left-hand side menu, click on the Manage > Users and groups option.
In the top menu, click on the Add user/group button.

The browser displays the Add Assignment pane.
In the Users and groups section, click on the None Selected link.
In the Users and groups pane, click on the checkboxes next to the users or groups that should have Portnox Cloud administrator accounts. Then, click on the Select button.
Optional: If you mapped administrator types using app roles, in the Select a role section, click on the None Selected link. In the Select a role pane, click on the app role for the administrator type, and then click on the Select button.

Note:
The selected app role applies to all users and groups in this assignment. To give different administrator types to different users, repeat the assignment for each administrator type.
Click on the Assign button at the bottom of the Add Assignment pane.

The selected users and groups show in the Users and groups list.
In the left-hand side menu, click on the Overview option. Then, in the top menu, click on the Start provisioning button and click on the Yes button in the confirmation dialog.

Result: Portnox Cloud creates administrator accounts for the assigned users during the next provisioning cycle. The accounts show in the Settings > Administrators list.

Note:

Entra ID runs automatic provisioning cycles about every 40 minutes. New assignments and attribute changes reach Portnox Cloud during the next cycle. The first cycle after you start provisioning can take longer.

To provision a single user immediately, in the Azure tab, in the left-hand side menu of the application pane, click on the Provision on demand option. Then, select the user and click on the Provision button.

Note:

You can also provision administrator accounts from other SCIM-compatible applications, for example Rippling HR software, PingOne, or CyberArk Identity. However, if integrating with a platform different than Entra ID, the names of the SCIM connection fields will differ. For example, the Tenant URL value is called SCIM base URL in Rippling and PingOne, and SCIM service URL in CyberArk Identity. If you integrate with an application other than Entra ID, adjust the procedure by consulting that application’s documentation for the relevant field names and settings.