SAP BTP Platform Members (Cloud Foundry)

Follow this procedure to set up the SAP BTP Platform Members (Cloud Foundry) as а proxy system.

Prerequisites

You have а global account in SAP BTP with at least one multi-environment subaccount with enabled Cloud Foundry environment.
You have established trust between your SAP Cloud Identity Services tenant as custom identity provider for platform users and your global account(s) containing these subaccounts. For more information, see Establish Trust and Federation of Custom Identity Providers for Platform Users.
You have created a CF provisioning user (which is a regular user of type Employee in the local identity directory of your SAP Cloud Identity Services tenant) that will be used for provisioning. Give this user an email address with the following pattern cf-user-provisioning-<origin_key>@sap.invalid, where <origin_key> is the origin key of the trust configuration for BTP platform users which points to your SAP Cloud Identity Services tenant. You have set an initial password for the user and marked its email adress as verified. For more information, see Create a New User and List and Edit User Details.

Note

The password lifetime for the CF provisioning user depends on the password policy set for the SAP Business Technology Platform application in the administration console of SAP Cloud Identity Services. For more information, see Set a Password Policy for an Application.
You have activated the account of the CF provisioning user by opening the Profile Page of SAP Cloud Identity Services, in a separate browser session, and changing its initial password. The URL has the following pattern: https://<tenant ID>.accounts.ondemand.com or https://<tenant ID>.accounts.cloud.sap
You have created the group cf-user-provisioning in your SAP Cloud Identity Services tenant and added the CF provisioning user to it. For more information, see Create a New Group and Add Users to a Group.
You have added the CF provisioning user as org member with role Org Manager to each Cloud Foundry organization where you want to provision users, in the SAP BTP cockpit For more information, see Add Org Members and About Roles in the Cloud Foundry Environment.

Context

The Cloud Foundry environment enables you to create polyglot cloud applications in Cloud Foundry. It contains the SAP BTP, Cloud Foundry runtime service, which is based on the open-source application platform managed by the Cloud Foundry Foundation. For more information, see Cloud Foundry Environment.

When you enable the Cloud Foundry environment in your subaccount, the system automatically creates a Cloud Foundry organization for you. You are able to add platform users as org members and space members and assign roles to grant these users platform access. For more information, see Valid role types Information published on non-SAP site .

SAP BTP Platform Members (Cloud Foundry) connector manages org and space members, as well as their role assignments, in the Cloud Foundry environment of a multi-environment subaccount, where a single SAP Cloud Identity Services tenant acts as custom identity provider. We recommend that you use the Identity Provisioning service enabled in this SAP Cloud Identity Services tenant.

In SAP BTP Platform Members (Cloud Foundry), groups correspond to roles in particular Cloud Foundry orgs or spaces, thus group members are user assignments of a role in a specific Cloud Foundry org or space. Group names must follow a defined pattern, explained below, to ensure the correct mapping and provisioning of users and their role assignments to the relevant Cloud Foundry organization or space.

Note

The attribute name, defined within the urn:sap:cloud:scim:schemas:extension:custom:2.0:Group schema, is used to map the users and user assignments of a role to the relevant Cloud Foundry organization or space. The group names follow the respective patterns:

organization group name: <org_ID> <org_role>
space group name: <org_ID> <space_ID> <space_role>, where space_ID can be retrieved using the Cloud Foundry Command Line Interface by executing the command cf space --guid.

Whereas the group display names adhere to the following patterns:

organization group display name: <btp.cf.pm.group.prefix><btp.cf.pm.landscape>:<org_name>:<org_role>
space group display name: <btp.cf.pm.group.prefix><btp.cf.pm.landscape>:<org_name>:<space_name>:<space_role>

You can use SAP BTP Platform Members (Cloud Foundry) as a proxy connector to execute hybrid scenarios. That means, it can provision its entities to another (external) back-end system by request, and then can continue executing CRUD operations back to SAP BTP Platform Members (Cloud Foundry), whenever the external back-end requests such.

The proxy system consumes User Account and Authentication API and Cloud Foundry V3 API provided by Cloud Foundry.

Procedure

To enable provisioning of platform users and user role assignments to and from Cloud Foundry environment, create a Support Ticket on component BC-CP-CF-SEC-IAM.

Specify your SAP Cloud Identity Services tenant ID and the origin key of the trust configuration for BTP platform users which points to your SAP Cloud Identity Services tenant. You can find the origin key value in theSAP BTP cockpit. Go to your SAP BTP subaccount, choose Trust Configuration and see the value under Origin Key for the relevant Custom Identity Provider for Platform Users.
Open your subaccount in SAP BTP cockpit (valid for OAuth authentication to the Identity Provisioning proxy system).

Note

If you have a bundle tenant, then in the cockpit → Neo → Overview, 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.
Create a technical user with the necessary authorizations. It will later be used by the external consumer to connect to Identity Provisioning.
- For Certificate-based authentication, follow the procedure in Manage Certificates for Inbound Connection → SAP BTP, Neo Environment
- For OAuth authentication, proceed as follows:
  1. Go to Security OAuth Clients and choose Register New Client.
  2. From the Subscription combo box, select <provider_subaccount>/ipsproxy.
  3. From the Authorization Grant combo box, select Client Credentials.
  4. In the Secret field, enter a password (client secret) and remember it. You will need it later, for the repository configuration in the external system.
  5. Copy/paste and save (in a notepad) the generated Client ID. You will need it later, too.
  6. From the left-side navigation, choose Subscriptions Java Applications ipsproxy .
  7. From the left-side navigation, choose Roles IPS_PROXY_USER.
  8. Choose Assign and enter oauth_client_<client_ID>.
    
    For <client_ID>, enter the one you have saved in the previous main step.
Access the Identity Provisioning UI.
- Access Identity Provisioning UI of Bundle Tenants
- Access Identity Provisioning UI of Standalone Tenants
Add SAP BTP Platform Members (Cloud Foundry) as a proxy system. For more information, see Add New Systems.

Choose the Properties tab to configure the connection settings for your system.

Mandatory Properties
Property Name	Description & Value
Type	Enter: HTTP
ProxyType	Enter: Internet
Authentication	Enter: BasicAuthentication
User	Enter the email of the CF provisioning user (see Prerequisites).
Password	(Credential) Enter the password for the CF provisioning user (see Prerequisites).
btp.cf.pm.origin	Enter the origin key of your SAP Cloud Identity Services tenant (see Step 1). The value of this property is a string, which always ends with the suffix -platform. It will be used as the origin attribute in the system transformation.
btp.cf.pm.landscape	Enter the technical key or the host name of the landscape in which your multi-environment subaccount with enabled Cloud Foundry environment is located. The techical key is available only for the SAP BTP Cloud Foundry regions. For more information, see Regions and API Endpoints Available for the Cloud Foundry Environment. Please note that when the technical key contains an extension index, the correct value is displayed in the API Endpoint column instead of the Technical Key column of the table. This is an example of a technical key: `cf-eu10-002`, corresponding to the API endpoint api.cf.eu10-002.hana.ondemand.com and host name cf.eu10-002.hana.ondemand.com The host name of the landscape can be found by looking up the API Endpoint field in the Overview tab of your Cloud Foundry Environment on subaccount level of the SAP BTP cockpit. The API endpoint has the following format: https://api.<landscape-hostname> Note If your provisioning job finishes with error 'Name or service not known', the value used for technical key is not correct. In that case you can use the host name of the landscape instead.
(Optional) btp.cf.pm.user.filter	When specified, only those SAP BTP Platform Members (Cloud Foundry) users matching the filter expression will be read. For example: userName eq "SmithJ"

To learn what additional properties are relevant to this system, see List of Properties. You can use the main search, or filter properties by the Name or System Type columns.

(Optional) Configure the transformations.

Transformations are used to map the user attributes from the data model of the source system to the data model of the target system, and the other way around. The Identity Provisioning offers a default transformation for the SAP BTP Platform Members (Cloud Foundry) proxy system, whose settings are displayed under the Transformations tab after saving its initial configuration.

You can change the default transformation mapping rules to reflect your current setup of entities in your SAP BTP Platform Members (Cloud Foundry) system. For more information, see:

Manage Transformations

Cloud Foundry V3 API Information published on non-SAP site

Caution

Keep in mind that when you add or delete users and user role assignments in SAP BTP Platform Members (Cloud Foundry), the operations order must adhere to the Cloud Foundry Environment hierarchy. In this case, you can expect the following behavior:

When adding a user as space member, it must already be present as member of the relevant organization with assigned role Org User. When deleting an org member, it should be first removed from the spaces of the relevant organization. In case you end up with erroneous entity structure, you can manually add or delete users via the administration console for SAP Cloud Identity Services.
When adding user role assignments, you should first add the org roles and afterwards proceed with the space roles. Also, when deleting user role assignments, you should first delete the space roles and then proceed with the org roles. If this condition is not fullfiled the job will finish with error. In that case, you can rerun the job until it finishes successfully.

Default read and write transformations:

Tip

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.

Read Transformation	Write Transformation
Code Syntax { "user": { "scimEntityEndpoint": "Users", "mappings": [ { "sourcePath": "$.id", "targetPath": "$.id", "targetVariable": "entityIdSourceSystem" }, { "sourcePath": "$.userName", "targetPath": "$.userName", "correlationAttribute": true }, { "sourcePath": "$.name.givenName", "targetPath": "$.name.givenName", "optional": true }, { "sourcePath": "$.name.familyName", "targetPath": "$.name.familyName", "optional": true }, { "sourcePath": "$.name.formatted", "targetPath": "$.name.formatted", "optional": true }, { "sourcePath": "$.emails", "targetPath": "$.emails", "preserveArrayWithSingleElement": true }, { "sourcePath": "$.emails[?(@.primary== true)].value", "optional": true, "correlationAttribute": true }, { "sourcePath": "$.active", "targetPath": "$.active", "optional": true }, { "sourcePath": "$.verified", "targetPath": "$.verified", "optional": true }, { "sourcePath": "$.meta", "targetPath": "$.meta", "optional": true }, { "sourcePath": "$.origin", "targetPath": "$.origin", "optional": true }, { "sourcePath": "$.zoneId", "targetPath": "$.zoneId", "optional": true }, { "sourceVariable": "entityBaseLocation", "targetPath": "$.meta.location", "targetVariable": "entityLocationSourceSystem", "functions": [ { "type": "concatString", "suffix": "${entityIdSourceSystem}" } ] } ] }, "group": { "scimEntityEndpoint": "Groups", "mappings": [ { "sourcePath": "$.id", "targetPath": "$.id", "targetVariable": "entityIdSourceSystem" }, { "sourcePath": "$.id", "targetPath": "$['urn:sap:cloud:scim:schemas:extension:custom:2.0:Group']['name']" }, { "constant": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "targetPath": "$.schemas" }, { "sourcePath": "$.displayName", "targetPath": "$.displayName", "functions": [ { "condition": "'%btp.cf.pm.group.prefix%' !== 'null'", "function": "concatString", "prefix": "%btp.cf.pm.group.prefix%" } ] }, { "sourcePath": "$.members", "targetPath": "$.members", "preserveArrayWithSingleElement": true, "optional": true }, { "sourceVariable": "entityBaseLocation", "targetPath": "$.meta.location", "targetVariable": "entityLocationSourceSystem", "functions": [ { "type": "concatString", "suffix": "${entityIdSourceSystem}" } ] }, { "constant": "authorization", "targetPath": "$['urn:ietf:params:scim:schemas:extension:sap:2.0:Group']['type']" }, { "constant": "userOnlyMembership", "targetPath": "$['urn:ietf:params:scim:schemas:extension:sap:2.0:Group']['supportedOperations']" } ] } }	Code Syntax { "user": { "skipOperations": [ "update" ], "mappings": [ { "sourceVariable": "entityIdTargetSystem", "targetPath": "$.id" }, { "sourcePath": "$.userName", "targetPath": "$.userName" }, { "sourcePath": "$.name.givenName", "targetPath": "$.name.givenName", "optional": true }, { "sourcePath": "$.name.familyName", "targetPath": "$.name.familyName", "optional": true }, { "sourcePath": "$.name.formatted", "targetPath": "$.name.formatted", "optional": true }, { "sourcePath": "$.emails", "targetPath": "$.emails", "preserveArrayWithSingleElement": true }, { "condition": "$.emails[?(@.primary == true)].value == []", "targetPath": "$.emails[0].primary", "constant": true }, { "constant": "urn:scim:schemas:core:1.0", "targetPath": "$.schemas[0]" } ], "scimEntityEndpoint": "Users" }, "group": { "mappings": [ { "sourcePath": "$['urn:sap:cloud:scim:schemas:extension:custom:2.0:Group']['name']", "targetVariable": "entityIdTargetSystem", "scope": "createEntity" }, { "sourceVariable": "entityIdTargetSystem", "targetPath": "$.id" }, { "sourcePath": "$.displayName", "targetPath": "$.displayName" }, { "sourcePath": "$.members", "targetPath": "$.members", "preserveArrayWithSingleElement": true, "optional": true }, { "sourcePath": "$.Operations", "targetPath": "$.Operations", "preserveArrayWithSingleElement": true, "scope": "patchEntity" }, { "sourcePath": "$.schemas", "targetPath": "$.schemas", "preserveArrayWithSingleElement": true, "scope": "patchEntity" } ], "scimEntityEndpoint": "Groups" } }

Read Transformation

Write Transformation

Code Syntax

{
  "user": {
    "scimEntityEndpoint": "Users",
    "mappings": [
      {
        "sourcePath": "$.id",
        "targetPath": "$.id",
        "targetVariable": "entityIdSourceSystem"
      },
      {
        "sourcePath": "$.userName",
        "targetPath": "$.userName",
        "correlationAttribute": true
      },
      {
        "sourcePath": "$.name.givenName",
        "targetPath": "$.name.givenName",
        "optional": true
      },
      {
        "sourcePath": "$.name.familyName",
        "targetPath": "$.name.familyName",
        "optional": true
      },
      {
        "sourcePath": "$.name.formatted",
        "targetPath": "$.name.formatted",
        "optional": true
      },
      {
        "sourcePath": "$.emails",
        "targetPath": "$.emails",
        "preserveArrayWithSingleElement": true
      },
      {
        "sourcePath": "$.emails[?(@.primary== true)].value",
        "optional": true,
        "correlationAttribute": true
      },
      {
        "sourcePath": "$.active",
        "targetPath": "$.active",
        "optional": true
      },
      {
        "sourcePath": "$.verified",
        "targetPath": "$.verified",
        "optional": true
      },
      {
        "sourcePath": "$.meta",
        "targetPath": "$.meta",
        "optional": true
      },
      {
        "sourcePath": "$.origin",
        "targetPath": "$.origin",
        "optional": true
      },
      {
        "sourcePath": "$.zoneId",
        "targetPath": "$.zoneId",
        "optional": true
      },
      {
        "sourceVariable": "entityBaseLocation",
        "targetPath": "$.meta.location",
        "targetVariable": "entityLocationSourceSystem",
        "functions": [
          {
            "type": "concatString",
            "suffix": "${entityIdSourceSystem}"
          }
        ]
      }
    ]
  },
  "group": {
    "scimEntityEndpoint": "Groups",
    "mappings": [
      {
        "sourcePath": "$.id",
        "targetPath": "$.id",
        "targetVariable": "entityIdSourceSystem"
      },
      {
        "sourcePath": "$.id",
        "targetPath": "$['urn:sap:cloud:scim:schemas:extension:custom:2.0:Group']['name']"
      },
      {
        "constant": [
          "urn:ietf:params:scim:schemas:core:2.0:Group"
        ],
        "targetPath": "$.schemas"
      },
      {
        "sourcePath": "$.displayName",
        "targetPath": "$.displayName",
        "functions": [
          {
            "condition": "'%btp.cf.pm.group.prefix%' !== 'null'",
            "function": "concatString",
            "prefix": "%btp.cf.pm.group.prefix%"
          }
        ]
      },
      {
        "sourcePath": "$.members",
        "targetPath": "$.members",
        "preserveArrayWithSingleElement": true,
        "optional": true
      },
      {
        "sourceVariable": "entityBaseLocation",
        "targetPath": "$.meta.location",
        "targetVariable": "entityLocationSourceSystem",
        "functions": [
          {
            "type": "concatString",
            "suffix": "${entityIdSourceSystem}"
          }
        ]
      },
      {
        "constant": "authorization",
        "targetPath": "$['urn:ietf:params:scim:schemas:extension:sap:2.0:Group']['type']"
      },
      {
        "constant": "userOnlyMembership",
        "targetPath": "$['urn:ietf:params:scim:schemas:extension:sap:2.0:Group']['supportedOperations']"
      }
    ]
  }
}

Code Syntax

{
  "user": {
    "skipOperations": [
      "update"
    ],
    "mappings": [
      {
        "sourceVariable": "entityIdTargetSystem",
        "targetPath": "$.id"
      },
      {
        "sourcePath": "$.userName",
        "targetPath": "$.userName"
      },
      {
        "sourcePath": "$.name.givenName",
        "targetPath": "$.name.givenName",
        "optional": true
      },
      {
        "sourcePath": "$.name.familyName",
        "targetPath": "$.name.familyName",
        "optional": true
      },
      {
        "sourcePath": "$.name.formatted",
        "targetPath": "$.name.formatted",
        "optional": true
      },
      {
        "sourcePath": "$.emails",
        "targetPath": "$.emails",
        "preserveArrayWithSingleElement": true
      },
      {
        "condition": "$.emails[?(@.primary == true)].value == []",
        "targetPath": "$.emails[0].primary",
        "constant": true
      },
      {
        "constant": "urn:scim:schemas:core:1.0",
        "targetPath": "$.schemas[0]"
      }
    ],
    "scimEntityEndpoint": "Users"
  },
  "group": {
    "mappings": [
      {
        "sourcePath": "$['urn:sap:cloud:scim:schemas:extension:custom:2.0:Group']['name']",
        "targetVariable": "entityIdTargetSystem",
        "scope": "createEntity"
      },
      {
        "sourceVariable": "entityIdTargetSystem",
        "targetPath": "$.id"
      },
      {
        "sourcePath": "$.displayName",
        "targetPath": "$.displayName"
      },
      {
        "sourcePath": "$.members",
        "targetPath": "$.members",
        "preserveArrayWithSingleElement": true,
        "optional": true
      },
      {
        "sourcePath": "$.Operations",
        "targetPath": "$.Operations",
        "preserveArrayWithSingleElement": true,
        "scope": "patchEntity"
      },
      {
        "sourcePath": "$.schemas",
        "targetPath": "$.schemas",
        "preserveArrayWithSingleElement": true,
        "scope": "patchEntity"
      }
    ],
    "scimEntityEndpoint": "Groups"
  }
}

Connect the external consumer to Identity Provisioning with the technical user you have created in step 2.
If the external consumer system is SAP Identity Management, you can export the newly created proxy system as a SCIM repository from Identity Provisioning and import it in SAP Identity Management. This will create a SCIM repository in SAP Identity Management where most of the repository constants will be automatically filled in. You need to provide the technical user credentials that you have set up in step 2 and the SCIM assignment method as described below:
- For AUTH_USER and AUTH_PASSWORD, enter your client ID and secret.
- For the SCIM_ASSIGNMENT_METHOD constant, make sure the value is PUT.
Note

For external consumer systems, other than SAP Identity Management, you should also use the PUT method for modifying entities.
Run an initial load job.

Next Steps

When a proxy system is connected to an external backend system (in the case of SAP Identity Management this means the exported CSV file is imported into the Identity Management Admin UI and a repository is configured), you can start managing the users and groups into this external system. Usually, the first operation is the initial load of the existing entities into your external system. When this load has finished, changes in the external system, such as creating new users or updating existing ones, can trigger CRUD requests back to the proxy system.

To see an example with SAP Identity Management, see Hybrid Scenario: SAP Identity Management → sections Next Steps and Future Identity Lifecycle.