A proxy system is a special connector type you can use for hybrid scenarios.
It exposes any Identity Provisioning supported backend system as a SCIM 2.0 service provider, which can be consumed by any SCIM 2.0 compatible client application, without making a direct connection between them.
After the proxy connector is configured, a consumer application can start sending CRUD requests to the Identity Provisioning proxy connector (which will play the role of a target system). The proxy connector will then read the entities (playing the role of a source system) and provision them to the back-end of the SCIM 2.0 system.
Identity Provisioning exposes a SCIM 2.0 based system (connector) as a proxy. Then, an external consumer system regards this proxy connector as its back-end system. To start using a proxy system in your Identity Provisioning tenant, whether it's a bundle or standalone, and depending on the infrastructure or environment it runs on, the following steps need to be performed.
Your tenant type meets one of the following requirements:
-
Your bundle tenant is created after March 15, 2022.
-
Your Identity Provisioning is purchased as a standalone product between September 1, 2020 and October 20, 2020.
-
Sign in to the SAP Cloud Identity Services administration console and navigate to Users & Authorizations > Administrators.
-
Choose your technical user (administrator user of type System). If you don't have a technical user yet, create one. For more information, see Add System as Administrator
-
Configure the technical user authentication.
-
Certificate
Choose Certificate > Configure certificate and Upload your certificate.
Client certificates are used by HTTP REST clients as a means for SSL certificate authentication.
-
Secrets
Choose Secrets > Add and provide the required information. After saving it, a Client ID and Client Secret are generated for the technical user. Make sure you copy and save the client secret.
-
-
Enable the Access Proxy System API permission for the technical user.
-
Then navigate to Identity Provisioning > Proxy Systems, and create a proxy system.
-
(Optional) Export this system as a .csv file. This will help an administrator of the external consumer application to import the proxy configuration as a SCIM repository in SAP Identity Management, for example.
The entities exposed by the back-end system will be mapped to SCIM 2.0 entities, if possible. If not possible, the SCIM standard provides a mechanism to define a new resource type with the appropriate schema. You can use the custom resource type to map the back-end entities.
-
Finally, the external application can start sending REST web service requests to the proxy system in order to read identities from the back end of the SCIM 2.0 system. For the authentication, you need to use the user ID and password of the Identity Authentication technical user for which you have set permission Access Proxy System API. In case you decide to use OAuth authentication, the OAuth token URL should follow the pattern:
https://<ias-tenant-host>/oauth2/token
Your tenant type meets one of the following requirements:
-
Your bundle tenant is created before March 15, 2022.
-
Your Identity Provisioning is purchased as a standalone product before September 1, 2020.
-
Create a technical user that will be used to connect to the Identity Provisioning proxy system and assign the necessary authorizations to your technical user.
-
For Certificate-based authentication, follow the procedure in Manage Certificates for Inbound Connection → SAP BTP, Neo Environment
-
For OAuth authentication, proceed as follows:
Step a. and b. are relevant for Identity Provisioning bundle tenants. For standalone tenants, proceed from step c.
-
Open the Identity Provisioning admin console and choose section Security > Authorizations.
-
Select your admin user and set role Manage OAuth Clients to it. You can grant additional administrators with this role.
-
Go to the SAP BTP cockpit → Neo → Overview and open your subaccount.
You can see the Global account, which SAP provides for your bundle in the corresponding Identity Provisioning region. Then, in the global account, you can see your subaccount, where the Identity Provisioning is enabled as a service for the bundle. The display name of the subaccount starts with SAP_BUNDLE.
-
Register a new OAuth client for the subscription to the ipsproxy application.
-
Assign role IPS_PROXY_USER to the oauth_client_<client_ID>**.
-
-
-
Then open again the Identity Provisioning admin console, and create a proxy system.
-
(Optional) Export this system as a .csv file. This will help an administrator of the external consumer application to import the proxy configuration as a SCIM repository in SAP Identity Management, for example.
The entities exposed by the back-end system will be mapped to SCIM 2.0 entities, if possible. If not possible, the SCIM standard provides a mechanism to define a new resource type with the appropriate schema. You can use the custom resource type to map the back-end entities.
-
Finally, the external application can start sending REST web service requests to the proxy system in order to read identities from the back end of the SCIM 2.0 system. For the authentication, you need to use the client ID and secret of the registered OAuth client for which you have assigned the IPS_PROXY_USER role.
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 used for write cases, as well.
Conditions in Proxy Scenarios
Using conditions is supported for both - proxy Read Transformation and proxy Write Transformation. However, when conditions are applied to users or groups in 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 don’t match the applied condition.
In the example below, the returned resources are "0" because all 5 users (items) returned per page are filtered out as they don't match a condition.
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"] }
As proxy operations cannot be maintained by the Identity Provisioning UI, you need to manage resources (users and groups) by sending SCIM 2.0 API requests to certain endpoints. Below are listed all endpoints and operations available in the Identity Provisioning service. Each provisioning system, however, supports only a specific set of operations.
Tip: 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.
Effective September 2020, Shanghai (China) tenants that reside on SAP BTP, Neo environment should be accessed on the following domain: dispatcher.cn1.platform.sapcloud.cn
So make sure you use the correct domain when you construct your REST API requests.
For example: GET https://ipsproxyabcd12345-xyz789.dispatcher.cn1.platform.sapcloud.cn/ipsproxy/api/v1/scim/bbb111aa-1234-aaaa-7777-1234567abcde/Users/s123456789
Depending on the infrastructure/environment your Identity Provisioning tenant (bundle or standalone) runs on, use the relevant URI patterns to call an endpoint:
|
Resource Operation |
HTTP Method |
Endpoint |
|---|---|---|
|
Read users |
|
Infrastructure of SAP Cloud Identity Services
|
|
Read users |
|
SAP BTP, Neo environment
|
|
Read a user |
|
SAP BTP, Neo environment
|
|
Read a user |
|
Infrastructure of SAP Cloud Identity Services
|
|
Create a user |
|
SAP BTP, Neo environment
|
|
Create a user |
|
Infrastructure of SAP Cloud Identity Services
|
|
Update a user (full) |
|
SAP BTP, Neo environment
|
|
Update a user (full) |
|
Infrastructure of SAP Cloud Identity Services
|
|
Update a user (partial) |
|
SAP BTP, Neo environment
|
|
Update a user (partial) |
|
Infrastructure of SAP Cloud Identity Services
|
|
Delete a user |
|
SAP BTP, Neo environment
|
|
Delete a user |
|
Infrastructure of SAP Cloud Identity Services
|
|
Read groups |
|
SAP BTP, Neo environment
|
|
Read groups |
|
Infrastructure of SAP Cloud Identity Services
|
|
Read a group |
|
SAP BTP, Neo environment
|
|
Read a group |
|
Infrastructure of SAP Cloud Identity Services
|
|
Create a group |
|
SAP BTP, Neo environment
|
|
Create a group |
|
Infrastructure of SAP Cloud Identity Services
|
|
Update a group (full) |
|
SAP BTP, Neo environment
|
|
Update a group (full) |
|
Infrastructure of SAP Cloud Identity Services
|
|
Update a group (partial) |
|
SAP BTP, Neo environment
|
|
Update a group (partial) |
|
Infrastructure of SAP Cloud Identity Services
|
|
Delete a group |
|
SAP BTP, Neo environment
|
|
Delete a group |
|
Infrastructure of SAP Cloud Identity Services
|
When using Identity Provisioning Proxy System 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. The membersType query parameter is applicable for groups and defines the type of members (user or group) to be included in the response.
The query parameters work for first-level attributes only.
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.
"name": { "familyName": "Armstrong", "givenName": "Julie", "middleName": "Grace" },
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, paging of multi-value attributes.
When specified, the attributes 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.
GET /Users?attributes=active,userName
This request example returns all groups with the displayName attribute in the response.
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.
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. This way, 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.
GET /Users?attributes=urn:ietf:params:scim:schemas:extension:sap:2.0:User:emails
When specified, the excludedAttributes 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.
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.
GET /Users?startIndex=1&count=3&excludedAttributes=schemas
When specified, the membersType query parameter defines the type of group members (user or group) to be included in the response. You can query for members of all groups or within a certain group. This parameter is supported only for SAP Ariba Applications proxy system.
This request example returns only the user members of all groups.
GET /Groups?membersType=user
This request example returns only the user members of a specific group.
GET /Groups/{group-id}?membersType=user
This request example returns only the group members of a specific group.
GET /Groups/{group-id}?membersType=group
This request example returns the group members of all groups matching the specified query.
GET /Groups?<query>&membersType=group
The Identity Provisioning implementation of the Proxy System SCIM API (based on the SCIM Query standard) supports the following filtering capabilities for users and groups:
-
Single entity filter - Refers to a filtering mechanism that is used to identify a specific single resource (user or group) within a system, based on unique identifiers. Typically, these are userName and email attributes for users and displayName attribute for groups. Identity Provisioning supports only the 'eq' (equal) operator. For example:
GET .../Users?filter=userName eq "johnsmith03"GET .../Groups?filter=displayName eq "accountants" -
Delta read filter - Refers to a filter mechanism used to get a list of resources that have been modified after a specified period of time. Identity Provisioning supports only the 'gt' (greater than) operator. For example:
GET .../Users?filter=meta.lastModified gt "2024-02-14T04:42:34Z"
If your system supports native read filtering, the Identity Provisioning proxy application will translate the SCIM filter to the native system filter, and will try to combine it with the relevant read filter property (for example, <system_prefix>.user.filter, <system_prefix>.group.filter or <system_prefix>.origin). For more information about all read filter properties, see List of Properties.
Combining filters from the properties and the SCIM request
You have the following user mapping in the Read Transformation of a proxy system.
Use Case 1
Use Case 2
{ "sourcePath": "$.userName", "targetPath": "$.userName", "correlationAttribute": true },{ "sourcePath": "$.emails[0].value", "preserveArrayWithSingleElement": true, "targetPath": "$.emails[0].value" },You set a filter on the Properties tab of the proxy system. For example:
scim.user.filter= timezone eq "US". For more information on the system specific filtering properties, see List of Properties.You execute the SCIM Proxy endpoint request to get a user with a given username or email.
Use Case 1:
GET .../Users?filter=userName eq "johnsmith03"Use Case 2:
GET .../Users?filter=emails[0].value eq "[email protected]"This query request to the proxy system API will result into:
Use Case 1:
/Users?filter=timezone eq "US" and userName eq "johnsmith03"Use Case 2:
/Users?filter=timezone eq "US" and emails[0].value eq "[email protected]"
If the Identity Provisioning finds:
-
0 users that meet the filtering criteria, the service returns HTTP status code 200 (OK) with 'totalResults' set to a value of 0.
-
1 user that meets the filtering criteria, the service returns HTTP status code 200 (OK), and includes the result in the body of the response.
-
More than 1 users that meet the filtering criteria, the service returns HTTP status code 400 (Bad Request) with detail error type 'tooMany'.
-
In the Read Transformation, there must be a mapping between the attribute names in
"sourcePath"and"targetPath"(see the example mapping above, where targetPath matches the left side of the used 'eq' filter). -
Fully qualified names (
<schema>:<attribute>) are not supported.For example:
GET .../Users/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employee Number eq '<attribute>' -
If your system supports multivalued e-mails (that is $.emails[0].value,$.emails[1].value, etc.), the search criteria will always resolve only one user e-mail. This is the first user e-mail ($.emails[0].value).
Lean more about system types: System Types
Learn more about SCIM 2.0 protocol: SCIM protocol
Proxy scenario example: Hybrid Scenario: SAP Identity Management
SAP Community Blog: Hybrid Scenarios with Identity Provisioning Proxy