Provision administrator accounts from Okta using SCIM

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

Before you begin, you must integrate Portnox Cloud with Okta and turn on Okta SSO for Portnox Cloud administrators. Portnox Cloud administrators from the Okta repository need this integration to log in with Okta SSO. For more information, see the following topic: Integrate with Okta Workforce Identity.

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 Okta. When you assign Okta users to the SCIM application, Portnox Cloud creates administrator accounts for these users. When you change the attributes of these users in Okta, Portnox Cloud updates their administrator accounts. When you unassign users, Portnox Cloud deactivates their administrator accounts.

Note:
The SCIM application is a separate Okta app integration. It does not replace any other Okta integration that you use with Portnox Cloud.
Important:
Don’t edit or delete SCIM-provisioned administrator accounts in the Portnox Cloud portal. Manage them only in Okta. 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.

  1. In the Cloud portal top menu, click on the Settings option.

  2. In the Cloud portal left-hand side menu, click on the Integration Services > APPLICATION API INTEGRATIONS option.

  3. Click on the Add API integration button.

  4. 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.

    Result: Portnox Cloud displays the values that you need for the Okta application: Tenant URL, OAuth token endpoint, Client identifier, and Client secret.

  5. 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 Okta app integration

In this section, you will access the Okta Admin Console and use it to create a new app integration for SCIM provisioning.

  1. In another tab of your browser, open your Okta admin console: https://your_tenant_name-admin.okta.com/.

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

  2. In the left-hand side menu, click on the Applications and Resources > Applications option.

  3. In the right-hand side pane, click on the Create App Integration button.

  4. In the Create app integration window, select the SAML 2.0 option, and then click on the Next button.

    Note:
    Okta offers SCIM provisioning only for custom SAML 2.0 and SWA app integrations. Do not select the OIDC - OpenID Connect or API Services option.
  5. In the General Settings step, enter a name in the App name field, and then click on the Next button.

    In this example, we used the name Portnox SCIM integration for the new application but you can use any name you like.

  6. In the Configure SAML step, enter https://portnox.com in the Single sign-on URL and Audience URI (SP Entity ID) fields. Then, click on the Next button.

    Note:
    Portnox Cloud uses this application only for provisioning, not for single sign-on. The SAML values are placeholders.
  7. In the Feedback step, select the option This is an internal app that we have created, and then click on the Finish button.

  8. Enable SCIM provisioning for the application.
    1. In the General tab, in the App Settings section, click on the Edit link.

    2. In the Provisioning field, select the SCIM option and then click on the Save button.

    Result: The Provisioning tab appears next to the other tabs of the application.

Connect the Okta application to Portnox Cloud

In this section, you will copy the values displayed by Portnox Cloud and paste them in the SCIM connection settings of the Okta application. Then, you will enable the provisioning actions that Okta performs in Portnox Cloud.

  1. In the Okta tab, click on the Provisioning tab. Then, in the Settings menu, click on the Integration option, and click on the Edit link in the SCIM Connection section.

  2. In the Portnox tab, click on the  ⧉  icon next to the Tenant URL field to copy the value to the clipboard.

  3. In the Okta tab, paste the copied value into the SCIM connector base URL field.

  4. In the Unique identifier field for users field, enter userName.

  5. In the Supported provisioning actions field, select the Push New Users and Push Profile Updates checkboxes. Leave the other checkboxes cleared.

  6. In the Authentication Mode field, select the OAuth 2 option. Then, in the Grant Type field, select the Client Credentials option.

  7. In the Portnox tab, click on the  ⧉  icon next to the OAuth token endpoint field to copy the value to the clipboard.

  8. In the Okta tab, paste the copied value into the Access token endpoint URI field.

  9. In the Portnox tab, click on the  ⧉  icon next to the Client identifier field to copy the value to the clipboard.

  10. In the Okta tab, paste the copied value into the Client ID field.

  11. In the Portnox tab, click on the  ⧉  icon next to the Client secret field to copy the value to the clipboard.

  12. In the Okta tab, paste the copied value into the Client Secret field. Then, click on the Save button.

  13. In the Provisioning tab, in the Settings menu, click on the To App option. Then, click on the Edit link next to the Provisioning to App heading.

  14. Select the Enable checkboxes next to Create Users, Update User Attributes, and Deactivate Users. Leave the Sync Password checkbox deactivated. Then, click on the Save button.

  15. In the Portnox tab, click on the Finish button.

Map the administrator attributes

In this section, you will map the Okta 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 Okta for the userType attribute.

Important:
If you use a value other than Okta, the administrator cannot log in with Okta 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 Okta username). They set a password using a link that Portnox Cloud sends via email.
  1. Set the value for the repository.
    1. In the Okta tab, in the Provisioning tab, in the SCIM Attribute Mappings section, scroll down to the list of attributes and then click on the  ✎  icon next to the User type attribute.

    2. In the Attribute value field, select the Same value for all users option, and then enter Okta in the field next to it. In the Apply on field, select the Create and update option. Then, click on the Save button.

  2. Scroll back up to the top of the section and click on the Go to Profile Editor button.

  3. In the Profile Editor pane, click on the Add Attribute button.

  4. Add the attribute for the administrator type.

    1. In the Data type field, select the string option.
    2. In the Display name field, enter Portnox role.
    3. In the Variable name field, enter portnoxRole.
    4. In the External name field, enter roles.^[primary==true].value.
    5. In the External namespace field, enter urn:ietf:params:scim:schemas:core:2.0:User.
    6. Select the Define enumerated list of values checkbox, and add the four roles[primary eq "True"].value values from the table above.
    7. In the Attribute type field, select the Personal option.
    8. Click on the Save button.
  5. Go back to the application. In the left-hand side menu, click on the Applications and Resources > Applications option, click on the name of the application that you created for SCIM provisioning, and then click on the Provisioning tab. Then, scroll all the way to the bottom and click on the Show Unmapped Attributes link.

    Result: You can see the Portnox role attribute at the bottom of the SCIM Attribute Mappings list with the Not mapped value.

Then, set 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 Okta user attributes.

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

Advantages:

  • You can assign many users to the application at once. Okta sets the administrator type of each user based on their attributes.

  • When users move to a different department or job, Okta 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.
  1. In the Okta tab, in the SCIM Attribute Mappings section, click on the  ✎  icon next to the Portnox role attribute.

  2. Set the expression for the administrator type.

    1. In the Attribute value field, select the Expression option.
    2. In the field next to it, enter a conditional expression.

      Use the following format:

      condition ? "value1" : "value2"

      • condition: A comparison of an Okta user attribute with a value, for example user.department == "IT" or user.title == "Network Administrator".

      • value1: The administrator type for users who match the condition.

      • value2: The administrator type for all other users. To check more conditions, replace value2 with another conditional expression.

      Each value must be one of the roles[primary eq "True"].value values from the table in the previous section. The comparison must match the attribute value exactly, including capitalization.

      Examples:

      • Users in the IT department get full administrator access. All other assigned users get read-only access:

        user.department == "IT" ? "FullAdmin" : "ReadOnlyAdmin"

      • 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:

        user.department == "IT" ? "FullAdmin" : user.department == "Support" ? "GuestAdmin" : user.department == "Onboarding" ? "ReadOnlyGuestAdmin" : "ReadOnlyAdmin"

      • 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:

        user.title == "Network Administrator" ? "FullAdmin" : user.title == "Support Technician" ? "GuestAdmin" : user.title == "Onboarding Technician" ? "ReadOnlyGuestAdmin" : "ReadOnlyAdmin"
    3. In the Apply on field, select the Create and update option.
    4. Click on the Save button.
Note:
To check the result of the expression for a specific user before you save it, enter the user’s name in the Preview field at the bottom of the window.

Set administrator types when assigning users

In this section, you will prepare the administrator type attribute so that you can select the administrator type for each user when you assign them to the application.

In this approach, you select the administrator type for each user when you assign them to the application.

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 select the administrator type for each user.

  • 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 Okta tab, in the SCIM Attribute Mappings section, make sure that the Portnox role attribute shows the Not mapped value. If it is mapped, click on the  ×  icon to unmap it.

If you map this attribute, Okta overwrites the value that you select when you assign users.

Assign users

In this section, you will select the Okta users that become Portnox Cloud administrators.

  1. In the Okta tab, click on the Assignments tab of the application, click on the Assign button, and then select the Assign to People option.

  2. Click on the Assign button next to a user that should have a Portnox Cloud administrator account.

    Note:
    Repeat this step and the next step for each user.
  3. Optional: If you set administrator types when assigning users, in the Portnox role field, select the administrator type for the user.

  4. Click on the Save and Go Back button. After you assign all users, click on the Done button.

Result: The assigned users show in the Assignments tab of the application. Okta provisions them to Portnox Cloud immediately.

The accounts show in the Settings > Administrators list in Portnox Cloud.

Note:
If an account doesn’t show in Portnox Cloud, in the Okta tab, click on the View Logs link next to the application name to see the details of the provisioning request.