API to Set Identity Profile Priorities

API to Set Identity Profile Priorities

An identity profile represents the identity information loaded from a specific authoritative source and the authentication method assigned to users from that source. For more information, refer to the online help for identity profiles.

 

NOTE: All RESTful APIs present in this document can change at any point without notice.  Always refer to this documentation for the latest supported RESTful APIs to complete this operation.

 

IMPORTANT: These APIs are being deprecated in favor of the IdentityNow Platform APIs. While these APIs will continue to be available for the foreseeable future, SailPoint recommends that you transition to the new versions as soon as possible. For detailed information about all new platform APIs, visit the SailPoint API Reference.

 

In some environments, a single user identity may belong to multiple authoritative sources and thus could belong to one of many profiles. In these circumstances, those profiles need to have precedence, also known as priority in this doc. In other words, the identities for those users can only come from one profile and the customer needs to be able to specify which profile they come from. We do this by assigning a priority to each profile. If a user exists in multiple profiles, IdentityNow will assign them to the profile with the highest priority.

 

The priority of the profile cannot be edited from the UI. When an Identity profile is created in the UI, a default priority is set that always places the new profile at the bottom of the list.  In the Identity Profiles panel, the identities are listed from the highest to the lowest priority which means that by default, the oldest profile always has the highest priority.

 

If a priority is not passed in, which is standard when creating profiles in the UI, the profile priority number is set as 10 + current maximum Identity Profile priority for the org. This means that, by default, the profiles that are older (created earlier) have higher priority.

 

The priority value of a profile must be unique within an org. This means that two profiles with in the same org cannot have the same priority. Create and Update calls will return an error if a unique priority is not specified.

 

To change the order of the identity profiles you will have to make one or more of the REST calls described below.

 

NOTE: DevOps will need to perform a full user sync in the CIS before you can use this feature.

 

Working with Identity Profile Priorities

 

The value set in the priority parameter is inverse to how high the identity profile appears in the priority list. In other words, the lower the Value for the priority parameter, the higher the priority. For example, if you have identity profile A's priority set to 100 and identity profile B's priority set to 110, identity profile A has a higher priority than B.

 

This document covers the following tasks:

 

 

Prerequisites:

 

  • Sign in to the org as an administrator. Click Admin and strong authenticate.

  • Get the source ID
  • Open your preferred tool for making API calls

 

NOTE: If you're making these API calls, you'll need to use on of our supported authentication methods. As a best practice SailPoint recommends using OAuth 2. Also, the endpoint you use must be changed slightly based on the authentication method. For details, see the Authentication section of the Developer portal documentation.

REST APIs:

 

You might need any of the following REST APIs to determine or set the priority of an identity profile:

 

NOTE: The lower the value of the priority parameter, the higher in the list the profile will appear.

 

  • <org>/cc/api/profile/list - Returns a list of identity profiles and related information, sorted in priority order from highest to lowest.
  • <org>/cc/api/profile/create - Creates a new identity profile. You can specify the priority parameter (is this optional) to determine where a new profile falls in the priority order
  • <org>/cc/api/profile/update/<profile_id> - Changes the value of the profile parameter to move the identity profile up or down in the  priority order.

 

Increase the Priority of an Existing Identity Profile

 

Let's say a customer has two profiles created. One is an Active Directory profile called Flat File AD which configured to use Active Directory authoritative source The second one is an Workday profile called another id profile which configured to use Workday authoritative source.  Let say the requirement is that the users who exist in both authoritative sources must be mapped to the Active Directory profile. In this case the Flat File AD profile needs to have a higher priority than another id profile.

 

In the procedure that follows, our goal is to shift the order the following identity profiles, as seen in the Identities > Identity Profiles list in the Admin interface of IdentityNow. We want Flat File AD to appear higher in the list than another id profile.

 

GET <org>/cc/api/profile/list

 

old ID order.png

 

Complete the following steps:

 

1. Make the API call:

 

GET <org>/cc/api/profile/list

 

You should see results similar to the image on the right.

 

Note that each profile has an id and a priority. In this example the first profile in the results has an id of 24 and a priority of 240.

profile+list+results.png

2. In the list of results, find the id of the identity profile for which you want to change the priority.

 

3. Make note of the priority value for this profile.

priority to change.png

4. Find the identity profile you want to be lower in priority than the profile from step 2.

 

5. Make note of the priority value for this profile.

 

In this case, we want "Flat File AD" profile to have a higher priority than "another id profile" so we need to set the priority value of Flat File AD to a lower number than "another id profile."

priority to be above.png

6. Make the following API call:

 

POST <org>/cc/api/profile/update/<profile_id>

 

where <profile_id> is the ID of the profile from step 3. In our example, the ID is 92.

 

Use the parameter:

 

  • priority = n

 

where n is a number higher than the profile from step 4

reset priority.png

 

Postman should return results similar to the image on the right. Note the new priority for the identity profile.

 

This will start a sync in the background and common users will be removed from another id profile and added to the Flat File AD profile.

new priority.png

 

7. To verify the new priority order, repeat the call from steps 1 through 3.

 

You can also go to Identities > Identity Profiles in the Admin interface of IdentityNow for the org and verify the new order of the identity profiles.

new ID order.png

 

Set the Priority of a New Identity Profile

 

Let's say the customer now wants to add a new identity profile based on a ServiceNow source. In this case, the customer wants the new profile to be second in priority to the Acme Now Profile. that means that any users shared between the Acme Now source and ServiceNow will be added to the AcmeNow source. However, users shared between ServiceNow and Active Directory or any other identity profile should belong to the ServiceNow source.

 

Our goal is to add the ServiceNow Identities profile between the Acme Now Profile and the Flat File AD profile.

 

Prerequisites:

 

  • Sign in to the org as an administrator
  • Get the source ID
  • Open your preferred tool for making API calls

NOTE: Because of changes to the way IdentityNow deals with cross-site request forgeries, all non-GET Postman calls require an additional header described here.

 

Complete the following steps:

 

1. Make the API call:

 

 

GET <org>/cc/api/profile/list

 

In this example, we want the new identity profile to appear immediately below the Acme Now Profile.

profile+list+results2.png

2. Make the following API call

 

POST <org>/cc/api/profile/create

 

3. Specify the following in your call:

  • name - The name of the profile as it will appear in the list
  • description - A description of the profile
  • sourceID - The ID of the source to be used for the identity profile. To learn how to get a source ID, see How do I find the ID for an source?.
  • priority - A value that is higher than the profile that you want the new profile to appear below in the list but lower than the profile you want it to appear above.
 

In this example, we want the profile to appear immediately below Acme Now ID Profile, which is show in step 2 above and is the first profile in the list.

Postman should return results similar to the image on the right. Note the new priority for the identity profile.

 

This will start a sync in the background and common users will be removed from another id profile and added to the Flat File AD profile.

create results.png
4. To verify the new priority order, repeat the call from step 1.

 

 

You can also go to Identities > Identity Profiles in the Admin interface of IdentityNow for the org and verify the new order of the identity profiles.

create idp.png
Labels (2)
Comments

The BETA API documentation (https://developer.sailpoint.com/apis/beta/#operation/updateIdentityProfile) makes it seem possible to do this, but it seems to be failing when passing the following JSON.

JSON

[
  {
    "op""replace",
    "path""/priority",
    "value""10"
  }
]

RESPONSE (ERROR = 405 Method not allowed)

{
    "errorName""NotSupportedException",
    "errorMessage""RESTEASY003065: Cannot consume content type",
    "trackingId""d56db50a24384b2992debb54ea09d91d"
}

Hi Ed,

 

     We have seen this issue when manually crafting the API call, but the problem does not occur when using the API when using the downloaded collection :-  https://developer.sailpoint.com/5b3e7d7b-d0d6-4cba-bac4-61fbd39d0636

 

 

 

Version history
Revision #:
5 of 5
Last update:
‎Sep 09, 2021 12:06 PM
Updated by: