Understanding Proxy System Transformations

Objectives

After completing this lesson, you will be able to:

  • How proxy transformations work
  • Query parameters for Proxy SCIM API

How Proxy Transformations Work

The proxy Read Transformation is used when the external client application (for example, SAP Identity Management) makes initial load, that is, executing GET requests to the resource endpoints (/Users or /Groups) to retrieve the corresponding entities of the particular type. The external client application can also execute GET requests to a single resource endpoint (querying a single resource is supported). In this case, the proxy system acts as a source one.

The proxy Write Transformation is used when the external application manages the entities in the proxy system – creates new entities, updates existing ones, or deletes existing ones. In this case, the proxy system acts as a target one.

However, after a Create or Update operation is performed on the proxy system, the Read Transformation is applied to the result, so that the created or updated entity is sent back to the external application. This behavior demonstrates that the proxy, Read Transformation, is also used for write cases.

Example - Conditions in Proxy Scenarios

Using conditions is supported for both the proxy, Read Transformation, and the proxy, Write Transformation. However, when conditions are applied to users or groups in the proxy, Read Transformation, the number of returned resources may be "0" or less than the actual number of read entities. This is because some of the entities are filtered out as they do not match the applied condition.

In the following example, the returned resources are "0" because all 5 users (items) returned per page are filtered out as they do not match a condition.

Code snippet

SCIM proxy client request: GET /Users?startIndex=6&count=5
SCIM proxy application response:
{
 "startIndex": 6,
 "itemsPerPage": 5,
 "totalResults": 11,
 "Resources": [],
 "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"]
}
Expand

How to Call a Proxy System

As proxy operations cannot be maintained by the Identity Provisioning UI, you need to manage resources (users, groups, and schemas) by sending SCIM 2.0 API requests to certain endpoints. The following contains a list of all endpoints and operations available in the Identity Provisioning service. Each provisioning system, however, supports only a specific set of operations.

Note

The ID of each proxy system (system_ID in the table below) is a dash-separated string. You can see it at the end of the system URL in the Identity Provisioning UI.

Depending on the infrastructure/environment your Identity Provisioning tenant (bundle or standalone) runs on, use the relevant URI patterns to call an endpoint:

Endpoints and Operations Available

Resource OperationHTTP MethodEndpoint
Read usersGET

SAP BTP, Neo Environment

  • OAuth Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.<host>/ipsproxy/api/v1/scim/<system_id>/Users
  • Certificate Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.cert.<host>/ipsproxy/certapi/v1/scim/<system-id>/Users
  

Infrastructure of SAP Cloud Identity Services

  • Basic Authentication: https://<ias-tenant-host>/ipsproxy/service/api/v1/scim/<system_id>/Users
  • Certificate Authentication: https://<ias-tenant-host>/ipsproxy/service/certapi/v1/scim/<system_id>/Users
Read a userGET

SAP BTP, Neo Environment

  • OAuth Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.<host>/ipsproxy/api/v1/scim/<system_id>/Users/<user_id>
  • Certificate Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.cert.<host>/ipsproxy/certapi/v1/scim/<system-id>/Users/<user_id>
  Infrastructure of SAP Cloud Identity Services:
  • Basic Authentication: https://<ias-tenant-host>/ipsproxy/service/api/v1/scim/<system_id>/Users/<user_id>
  • Certificate Authentication: https://<ias-tenant-host>/ipsproxy/service/certapi/v1/scim/<system_id>/Users/<user_id>
Create a userPOST

SAP BTP, Neo Environment

  • OAuth Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.<host>/ipsproxy/api/v1/scim/<system_id>/Users
  • Certificate Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.cert.<host>/ipsproxy/certapi/v1/scim/<system-id>/Users
  

Infrastructure of SAP Cloud Identity Services

  • Basic Authentication: https://<ias-tenant-host>/ipsproxy/service/api/v1/scim/<system_id>/Users
  • Certificate Authentication: https://<ias-tenant-host>/ipsproxy/service/certapi/v1/scim/<system_id>/Users
Update a user (full)PUT

SAP BTP, Neo Environment

  • OAuth Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.<host>/ipsproxy/api/v1/scim/<system_id>/Users/<user_id>
  • Certificate Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.cert.<host>/ipsproxy/certapi/v1/scim/<system-id>/Users/<user_id>
  

Infrastructure of SAP Cloud Identity Services

  • Basic Authentication: https://<ias-tenant-host>/ipsproxy/service/api/v1/scim/<system_id>/Users/<user_id>
  • Certificate Authentication: https://<ias-tenant-host>/ipsproxy/service/certapi/v1/scim/<system_id>/Users/<user_id>
Update a user (partial)PATCHSAP BTP, Neo Environment
  • OAuth Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.<host>/ipsproxy/api/v1/scim/<system_id>/Users/<user_id>
  • Certificate Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.cert.<host>/ipsproxy/certapi/v1/scim/<system-id>/Users/<user_id>
  

Infrastructure of SAP Cloud Identity Services

  • Basic Authentication: https://<ias-tenant-host>/ipsproxy/service/api/v1/scim/<system_id>/Users/<user_id>
  • Certificate Authentication: https://<ias-tenant-host>/ipsproxy/service/certapi/v1/scim/<system_id>/Users/<user_id>
Delete a userDELETE

SAP BTP, Neo Environment

  • OAuth Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.<host>/ipsproxy/api/v1/scim/<system_id>/Users/<user_id>
  • Certificate Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.cert.<host>/ipsproxy/certapi/v1/scim/<system-id>/Users/<user_id>
  

Infrastructure of SAP Cloud Identity Services

  • Basic Authentication: https://<ias-tenant-host>/ipsproxy/service/api/v1/scim/<system_id>/Users/<user_id>
  • Certificate Authentication: https://<ias-tenant-host>/ipsproxy/service/certapi/v1/scim/<system_id>/Users/<user_id>
Read groupsGET

SAP BTP, Neo Environment

  • OAuth Authentication: https://ipsproxy<provider_subaccount?-<consumer_subaccount>.<host>/ipsproxy/api/v1/scim/<system_id>/Groups
  • Certificate Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.cert.<host>/ipsproxy/certapi/v1/scim/<system-id>/Groups
  

Infrastructure of SAP Cloud Identity Services

  • Basic Authentication: https://<ias-tenant-host>/ipsproxy/service/api/v1/scim/<system_id>/Groups
  • Certificate Authentication: https://<ias-tenant-host>/ipsproxy/service/certapi/v1/scim/<system_id>/Groups
Read a groupGET

SAP BTP, Neo Environment

  • OAuth Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.<host>/ipsproxy/api/v1/scim/<system_id>/Groups/<group_id>
  • Certificate Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.cert.<host>/ipsproxy/certapi/v1/scim/<system-id>/Groups/<group_id>
  

Infrastructure of SAP Cloud Identity Services

  • Basic Authentication: https://<ias-tenant-host>/ipsproxy/service/api/v1/scim/<system_id>/Groups/<group_id>
  • Certificate Authentication: https://<ias-tenant-host>/ipsproxy/service/certapi/v1/scim/<system_id>/Groups/<group_id>
Create a groupPOST

SAP BTP, Neo Environment

  • OAuth Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.<host>/ipsproxy/api/v1/scim/<system_id>/Groups
  • Certificate Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.cert.<host>/ipsproxy/certapi/v1/scim/<system-id>/Groups
  

Infrastructure of SAP Cloud Identity Services

  • Basic Authentication: https://<ias-tenant-host>/ipsproxy/service/api/v1/scim/<system_id>/Groups
  • Certificate Authentication: https://<ias-tenant-host>/ipsproxy/service/certapi/v1/scim/<system_id>/Groups
Update a group (full)PUT

SAP BTP, Neo Environment

  • OAuth Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.<host>/ipsproxy/api/v1/scim/<system_id>/Groups/<group_id>
  • Certificate Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.cert.<host>/ipsproxy/certapi/v1/scim/<system-id>/Groups/<group_id>
  

Infrastructure of SAP Cloud Identity Services

  • Basic Authentication: https://<ias-tenant-host>/ipsproxy/service/api/v1/scim/<system_id>/Groups/<group_id>
  • Certificate Authentication: https://<ias-tenant-host>/ipsproxy/service/certapi/v1/scim/<system_id>/Groups/<group_id>
Update a group (partial)PATCH

SAP BTP, Neo Environment

  • OAuth Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.<host>/ipsproxy/api/v1/scim/<system_id>/Groups/<group_id>
  • Certificate Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.cert.<host>/ipsproxy/certapi/v1/scim/<system-id>/Groups/<group_id>
  

Infrastructure of SAP Cloud Identity Services

  • Basic Authentication: https://<ias-tenant-host>/ipsproxy/service/api/v1/scim/<system_id>/Groups/<group_id>
  • Certificate Authentication: https://<ias-tenant-host>/ipsproxy/service/certapi/v1/scim/<system_id>/Groups/<group_id>
Delete a groupDELETE

SAP BTP, Neo Environment

  • OAuth Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.<host>/ipsproxy/api/v1/scim/<system_id>/Groups/<group_id>
  • Certificate Authentication: https://ipsproxy<provider_subaccount>-<consumer_subaccount>.cert.<host>/ipsproxy/certapi/v1/scim/<system-id>/Groups/<group_id>
  

Infrastructure of SAP Cloud Identity Services

  • Basic Authentication: https://<ias-tenant-host>/ipsproxy/service/api/v1/scim/<system_id>/Groups/<group_id>
  • Certificate Authentication: https://<ias-tenant-host>/ipsproxy/service/certapi/v1/scim/<system_id>/Groups/<group_id>

Query Parameters for Proxy SCIM API

When you are using Identity Provisioning Proxy SCIM API, you can specify the attributes and the excludedAttributes query parameters to control which user or group resource attributes to be included or excluded from the response.

Note

The query parameters work for first-level attributes only.

Code Syntax

In this example, "name" is the first-level attribute. The "familyName", "givenName" and "middleName" are second-level attributes and cannot be used as the query parameter value.

Code snippet
"name": { 
 "familyName": 
 "Armstrong", "givenName": 
 "Julie", "middleName": "Grace" 
 },
Expand

The query parameter value is the resource attribute name. In case you want to specify multiple attribute names, you need to separate them by comma. Using " " (space) or "," (comma) is not a valid value and results in returning all the resource attributes.

In order for an attribute to be included or excluded from the response, the attribute's schema must be defined in the Schemas attribute of the user resource. For example, if you want to return all users with the custom attribute roomNumber in the response, the custom schema must be defined in the Schemas attribute of the user resource.

The attributes and the excludedAttributes query parameters can be combined with other parameters, such as filtering, paging of resources, and paging of multi-value attributes.

  • attributes - When specified, this query parameter defines which user or group resource attributes to be included in the response.

This request example returns all users with the active and userName attributes in the response.

Code Syntax

GET /Users?attributes=active,userName

Code Syntax

GET /Groups?attributes=displayName

This request example combines the attributes query parameter with filtering of a user by userName. It returns only the TestUser with both attributes: active and displayName in the response.

Code Syntax

GET /Users?filter=userName eq "TestUser"&attributes=active,displayName

In case an attribute is defined in two schemas (for example, the emails attribute is defined in the core schema and in the custom schema), you need to specify the schema URI and the attribute name as the query parameter value. By doing this, the users will be returned with emails attribute from the specified schema. Otherwise, if you only specify emails without the schema URI, the emails attribute from both schemas will be returned.

Code Syntax

GET /Users?attributes=urn:ietf:params:scim:schemas:extension:sap:2.0:User:emails
  • excludedAttributes - When specified, this query parameter defines which user or group resource attributes to be excluded in the response.

This request example returns all users with all attributes excluding userType in the response.

Code Syntax

GET /Users?excludedAttributes=userType

This request example returns all groups with all attributes excluding schemas in the response.

GET /Groups?excludedAttributes=schemas

This request example combines the excludedAttributes query parameter with paging parameters startIndex and count of users. It returns 3 users starting with the first one as the first query result with all attributes, excluding schemas in the response.

Code Syntax

GET /Users?startIndex=1&count=3&excludedAttributes=schemas

Proxy Systems - Read and Write Transformations

Activate the following video and audio to learn to explore the functionality available for proxy transformations.

Log in to track your progress & complete quizzes