Identity Brokerage REST APIs
The Identity Brokerage provides a REST APIs for managing accounts, targets, target profiles, groups membership (modify only), and permissions.
Supported REST APIs
The APIs implement the Simple Cloud Identity Management (SCIM) standard Version 2.0 with custom schema extensions. This implementation enables developers to access and manage identity resources directly by developing client applications that can be invoked from anywhere within the network.
The following table lists the Verify Governance supported Identity Brokerage REST APIs.
Note:
- For resource search, limited filtering capability is supported for User and Group resources. All other Identity Brokerage resources do not support filtering.
- For resource search, sorting and pagination are not supported. A search limit is specified in the Identity Brokerage properties file to specify the maximum number of returns that are supported by Identity Brokerage. This search limit applies to all Identity Brokerage managed resources.
- For resource search, the attributes query parameter is supported for User and Group resources to adjust the information that is returned.
| Category | API Name | Resource | Endpoint | Operation | Description |
|---|---|---|---|---|---|
| Group Management | Get All groups | Groups | ../igi/v2/Targets/{target_id}[/v2]/Groups | GET | Retrieves all groups from a target. |
| Get Group | Groups | ../igi/v2/Targets/{target_id}[/v2]/Groups/{group_id} | GET | Looks up a group from the target cache. | |
| Modify Group | Groups | ../igi/v2/Targets/{target_id}[/v2]/Groups/{group_id} | PATCH | Modifies a group's attribute including membership assignments. | |
| Target Management | Get All Targets | Targets | ../igi/v2/Targets | GET | Retrieves all targets from the target cache. |
| Get Schema for a target | Schemas | ../igi/v2/Targets/{target_id}[/v2]/Schemas | GET | Gets the schema for a target. This is used by client to generate correct input and to validate output when creating SCIM requests on the target. | |
| Get Service Provider Config for a target | ServiceProviderConfig | ../igi/v2/Targets/Target_ID/ServiceProviderConfig | GET | Gets the Service Provider Config for a target. This is used by client to get information about a target. | |
| Get Target | Targets | ../igi/v2/Targets/{target_id} | GET | Looks up a target from the target cache. | |
| Target Profile Management | Delete Target Profile | TargetProfiles | ../igi/v2/TargetProfiles/{profileName} | DELETE | Deletes an adapter profile. |
| GET All Target Profiles | TargetProfiles | ../igi/v2/TargetProfiles/ | GET | Gets a list of all the target profiles imported into Identity Brokerage. | |
| Get Localized labels by the profile name | BrokerageService | ../BrokerageService/config/labels?profile='profileName'&key='messageKey' | GET | Gets the localized labels for a profile. | |
| Get Schema by TargetProfile name | Schemas | ../igi/v2/TargetProfiles/{profileName}/Schemas | GET | Gets the schema for a target type. This is used by client to get the schema prior to creating a target. The profile name is obtained from the adapter. | |
| Get Target Form by TargetProfile name | BrokerageService | ../BrokerageService/config/Forms/{profileName}/Target | GET | Gets the target form for a profile. This is used by a client to get a target form to collect information to create a target instance. The profile must have been imported prior to calling this API. | |
| GET Target Profile | TargetProfiles | ../igi/v2/TargetProfiles/{profileName} | GET | Gets an adapter profile. | |
| Upload an adapter profile jar | TargetProfiles | ../igi/v2/TargetProfileJar | POST | Uploads the adapter profile jar file contents into Identity Brokerage. | |
| Upload Language pack jar | LanguagePack | ../igi/v2/LanguagePack | POST | Uploads the language pack jar file contents into Identity Brokerage for localization. | |
| Upload Target Profile Definition | TargetProfiles | ../igi/v2/TargetProfiles | POST | Uploads a target profile definition into Identity Brokerage. This enables a quick way to modify the target profile definition without the need to upload a new adapter profile on Verify Governance. | |
| User Management | Add User | Users | ../igi/v2/Targets/{target_id}[/v2]/Users | POST | Adds a user to the target. This creates a user in the target endpoint, and if succeeded, adds the user to the cache. |
| Delete User | Users | ../igi/v2/Targets/{target_id}[/v2]/Users/{user_id} | DELETE | Deletes a user from the target. | |
| Get All Supporting Data Endpoints | ResourceTypes | ../BrokerageService/identity/Targets/{target_id}/ResourceTypes | GET | Retrieves all dynamic supporting data endpoints of a target. | |
| Get All Users | Users | ../igi/v2/Targets/{target_id}[/v2]/Users[?filter=userName eq 'joe'|?filter=userName sw 'j'] | GET | Retrieves all users from a target. | |
| Get Canonical Values mapping Endpoint | CanonicalValuesMapping | ../igi/v2/Targets/{target_id}/CanonicalValuesMapping | GET | Retrieves canonical values mapping for extended attributes. | |
| Get Data from dynamic Supporting Data Endpoint | ../igi/v2/Targets/{target_id}/{resource} | GET | Retrieves all data from one dynamic supporting data endpoint of a target. | ||
| Get Supporting Data | ../igi/v2/Targets/{target_id}/{resource}/{id} | GET | Retrieves a supporting data by ID. | ||
| Get User | Users | ../igi/v2/Targets/{target_id}[/v2]/Users{user_id} | GET | Retrieves a user of a target using its ID in Identity Brokerage. | |
| Modify (Patch) User | Users | ../igi/v2/Targets/{target_id}[/v2]/Users{user_id} | PATCH | Replaces a user's attributes on cache and endpoint, based on patch request. | |
| Modify (Replace) User | Users | ../igi/v2/Targets/{target_id}[/v2]/Users/{user_id} | PUT | Replaces a user's attributes on cache and target endpoint. |
Note: The /labels and the
/Forms APIs do not implement SCIM v2.0. The differences between the APIs that
are not SCIM-compliant as compared to the SCIM-compliant APIs are listed:
- The data that is returned by the non-compliant APIs are not SCIM resources and cannot be managed through the Identity Brokerage.
- The APIs are accessed through the /config context, not the
/identity context. For example,
https://{host}:{port}/BrokerageService/config/Forms/{profile}/Target - The response messages that are returned by these APIs are in JSON format, but they are not SCIM-compliant. Therefore, the caller must provide an Accept header of "application/json" instead of "application/scim+json".
Procedure
- The Identity Brokerage REST API is disabled by default. To enable it, see Enabling or disabling the Identity Brokerage REST API.
- Set up basic authentication to access REST APIs by creating Identity Brokerage users. See Managing Identity Brokerage users and passwords to create the authentication credentials.
- Enable HTTPS communication to the Identity Brokerage. Only
HTTPS communication is supported. See Managing certificates to
enable secure communication.Note:
- The Identity Brokerage profile uses the same certificate store as the Verify Governance.
- Use port 8443 for the external client to use the Identity Brokerage REST API. This port is blocked by default. To enable it, see Enabling or disabling the Identity Brokerage REST API.
- View and run the sample client.
API documentation
To access the REST APIs documentation:
- Download the SVG_REST_API_10_Brokerage.zip file from https://www.ibm.com/support/pages/node/6356563 into a folder on your local computer.
- Extract the SVG_REST_API_10_Brokerage.zip file.
- Open the index.html file.
Limitations
Attribute values are case-sensitive. When you delete an attribute value, make sure to specify the value in its exact case when it was added to the account. Otherwise, the delete request fails.