> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/connector-configuration/sap.md). # SAP S/4HANA connector This page describes how to set up connection to SAP S/4 Hana The SAP S/4 Hana connector provides the ability to manage users, their attributes, and memberships (roles and profiles) in the SAP system. This connector also supports connection with an older versions of SAP known as SAP R/3. The connector communicates with SAP over the **JCo/RFC** interface (BAPI calls) and requires the SAP JCo native library. | Operation | Supported | | ------------------------------------------------------- | ----------------- | | Create / modify user | ✅ | | Remove user | ✅ | | Suspend / resume user | ✅ | | Set / change password | ✅ | | Assign roles (activity groups) and profiles | ✅ | | Assign SAP user groups (USGRP) as memberships | ❌ not implemented | | Synchronize users | ✅ | | Import roles, profiles, and user groups as entitlements | ✅ | | Test connection | ✅ | {% hint style="info" %} **Which SAP connector do I need?** This page covers the **SAP S/4HANA / ERP (ABAP)** system. For the Java-stack **User Management Engine**, see the [SAP UME connector](/connector-configuration/sapume.md); for SAP systems serving the **Fiori** UX layer, see the [SAP Fiori connector](/connector-configuration/sap-fiori.md). {% endhint %} ## Use cases * Managing **SAP application users** — creation, changes, deactivation — from OpenIAM. * Driving **SAP role and profile assignments** from OpenIAM roles/entitlements. * **Importing SAP roles and profiles** into OpenIAM for use in the catalog and access review. ## Versions and compatibility The end application is an **ABAP-stack SAP system** — S/4HANA, and the older SAP R/3 — reached over **JCo/RFC** rather than over HTTP. The connector calls BAPIs through SAP's own Java Connector library, so what it supports is what JCo and the target release support, not a version range of its own.
PropertyValue
SAP systemsS/4HANA and SAP R/3, ABAP stack
InterfaceJCo/RFC, using BAPI calls and RFC_READ_TABLE
Not this connectorThe Java-stack User Management Engine is the SAP UME connector; systems serving the Fiori UX layer are the SAP Fiori connector
## Prerequisites ### On the connector host * A **Linux host**. The connector is deployed as a JAR. * **Java 11**. * The **SAP JCo native library** (`libsapjco3.so`), with `LD_LIBRARY_PATH` pointing at the directory holding it. * Network access to the SAP application server. The port is **33** followed by the two-digit system number — system number `00` is port `3300`, `01` is `3301`, and so on. ### From the SAP team Four things, and they are worth requesting together. Granted piecemeal, each round trip is a change request on the SAP side, and a partial grant fails in a way that looks like a connector fault rather than a missing authorization.
What to requestFrom
A dedicated RFC service user with a non-expiring password, exempt from password-change policySAP Basis
The connection details — application server host, system number, client, languageSAP Basis
The authorizations belowSAP Security or Basis
Network access from the connector host to the SAP application serverNetwork or infrastructure
{% hint style="warning" %} **Ask whether the host address works from outside their network.** Basis teams often read it off their own SAP GUI, which points at an internal address — typically a `10.x` one — reachable only from inside. It looks correct and simply times out. If OpenIAM is hosted rather than on-premises, confirm which address to use and whether a firewall rule is needed. {% endhint %} #### Authorization objects | Object | Field | Value | Why | | ------------ | ----------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------- | | `S_RFC` | `ACTVT` | `16` (Execute) | Permission to call anything over RFC at all | | `S_RFC` | `RFC_TYPE` / `RFC_NAME` | The function groups holding the modules below | Basis maps modules to groups; `*` is simplest for a proof of concept | | `S_TABU_NAM` | `ACTVT` / `TABLE` | `03` (Display), the tables below | Table-level read | | `S_TABU_DIS` | `ACTVT` / `DICBERCLS` | `03`, the authorization groups of those tables | Grant alongside `S_TABU_NAM` — which of the two SAP checks depends on the release | | `S_USER_GRP` | `ACTVT` / `CLASS` | `03`, `*` | Read user master records | | `S_USER_AGR` | `ACTVT` / `ACT_GROUP` | `03`, `*` — add `02` to assign roles | Read role assignments and definitions; assigning a role to a user needs `02` | | `S_USER_PRO` | `PROFILE` | `*` | Read profile assignments | | `S_USER_SYS` | `SUBSYSTEM` | `*` | Required by the user BAPIs even for reading | {% hint style="danger" %} **A narrow value on an `S_USER_*` object does not produce an error.** SAP returns fewer rows, and the connector reports what it was given as though it were complete. A synchronization then looks clean while silently missing users or roles. If the full scope cannot be granted, agree and record what it covers, so that anything built on the data can state its limits. {% endhint %} #### Tables the connector reads Display access only. | Table | Holds | | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `USR02` | User master — login, user type, lock status | | `USRSTAMP` | Change timestamps, used for incremental synchronization | | `USGRP`, `USGRPT` | User groups and their texts | | `AGR_DEFINE` | The role catalog itself — every role, including the `SAP_*` roles | | `AGR_TEXTS` | Role descriptions | | `AGR_AGRS` | Composite-to-single role relationships | | `AGR_USERS` | Role assignments, with their validity dates | | `AGR_1016` | Role-to-profile mapping | | `AGR_1251` | The authorizations inside each role, and its `S_TCODE` transactions | | `AGR_1252` | Organizational-level values, used to resolve placeholders such as `$BUKRS` | | `AGR_TCODES` | The role menu | | `TOBJT`, `AUTHX`, `DD04T`, `TSTCT`, `TACTT`, `T001`, `T001W`, `T024E`, `T024` | Texts for objects, fields, transactions, activities, company codes, plants and purchasing groups | {% hint style="info" %} **The text tables are optional.** Without access to them a search still succeeds and simply leaves descriptions empty; a lost connection is still a failure. {% endhint %} #### Function modules These must be callable over RFC. Basis will translate them into function groups for `S_RFC`. * `RFC_READ_TABLE` — every table read above. * `BAPI_USER_GET_DETAIL`, `BAPI_USER_EXISTENCE_CHECK` — users and their roles. * `BAPI_HELPVALUES_GET` — the profile catalog. Roles no longer use it. * `RFCPING` — the connection health check. Note this is **not** `RFC_PING`; they are different modules. * `RFC_METADATA_GET` and `DDIF_FIELDINFO_GET` on newer releases, or `RFC_GET_FUNCTION_INTERFACE`, `RFC_GET_STRUCTURE_DEFINITION` and `RFC_GET_UNICODE_STRUCTURE` on older ones. {% hint style="info" %} **The metadata modules are the ones most often missed.** The JCo library chooses between the two sets at run time based on the release, so which set it needs cannot be predicted in advance — request both. Without them the connector cannot describe the function it is about to call, and every operation fails before it starts. {% endhint %} #### Only if provisioning is in scope Reading users and roles needs none of these, and asking for them invites a longer security review than a read-only project needs. | Object | Field | Value | For | | ------------ | ------- | ---------------------- | ------------------------------------- | | `S_USER_GRP` | `ACTVT` | `01`, `02`, `05`, `06` | Create, change, lock and unlock users | | `S_USER_AGR` | `ACTVT` | `22` | Assign roles | | `S_USER_PRO` | `ACTVT` | `22` | Assign profiles | Also: `BAPI_USER_CREATE1`, `BAPI_USER_CHANGE`, `BAPI_USER_DELETE`, `BAPI_USER_LOCK`, `BAPI_USER_UNLOCK`, `BAPI_USER_ACTGROUPS_ASSIGN`, `BAPI_USER_PROFILES_ASSIGN`, `BAPI_TRANSACTION_COMMIT` and `BAPI_TRANSACTION_ROLLBACK`. {% hint style="danger" %} **`BAPI_TRANSACTION_COMMIT` is easy to overlook and is not optional.** Without it SAP accepts every write and then discards it — the change reports success and never persists. {% endhint %} ## Installing the connector The connector runs as a standalone JAR on a Linux host — there is no Kubernetes deployment for this connector. ### Standard (RPM) environment Use an `.sh` script to start the connector. It is important to provide the path to where the SAP library is stored. Example of a startup script: {% code overflow="wrap" %} ```bash #!/bin/bash . /usr/local/openiam/env.conf export LD_LIBRARY_PATH=/usr/local/openiam/conf/connectors/sap/ export LIBPATH=/usr/local/openiam/conf/connectors/sap/ export VAULT_CERTS="$HOME_DIR/vault/certs/" export JAVA_HOME="$HOME_DIR/jdk" setenforce 0 JAVA_OPTS="$2" JAR_FILE="$1" $JAVA_HOME/bin/java -Dlogging.level.root=WARN -Dlogging.level.org.openiam=INFO -Dspring.config.location=/usr/local/openiam/conf/connectors/sap/application.properties -Dconfpath=$HOME_DIR -jar $JAVA_OPTS $HOME_DIR/connectors/bin/saps4hana-connector-rabbitmq.jar > $HOME_DIR/logs/saps4hana-connector-rabbitmq.log & ``` {% endcode %} ### When the connector runs on another host The connector needs to reach the secret store on **8200** and the message broker on **5672**. Where it runs on a different machine from OpenIAM, make sure nothing between them blocks those ports. ``` firewall-cmd --add-port=8200/tcp --permanent firewall-cmd --add-port=5672/tcp --permanent firewall-cmd --reload ``` Download the connector to a directory which, for this document, will be referred to as your\_folder. In your\_folder, create a file entitled `sap_application.properties` with the following contents: ``` org.openiam.connector.queue=SAP_Connector_1_Request org.openiam.connector.queueResponseName=SAP_Connector_1_Response org.openiam.connector.name=SAPS4HANA org.openiam.connector.type=SAP Connector org.openiam.connector.broadcast.binding.connector.key=52 spring.application.name=saps4hana-connector-rabbitmq org.openiam.health.check.sweeptime=30000 management.health.elasticsearch.enabled=false management.health.redis.enabled=false spring.jmx.enabled=false sap.property.date.format=yyyy-MM-dd sap.general.checkIfUserHasPwdAlreadySet=false CIPHER_sap.general.dummyPassword={rym2+zCJlbSuPzuFl2p2T4foDlleyNAL} ``` Install Java 11. Copy the vault certificate entitled vault.crt and import it. You can then drop this file from the box. {% code overflow="wrap" %} ``` keytool -noprompt -import -v -trustcacerts -alias vault_$(pwgen -s 13 1) -file path_to_vault.crt -keystore /usr/lib/jvm/java-11-openjdk-11.0.11.0.9-1.el7_9.x86_64/lib/security/cacerts -keypass changeit -storepass changeit ``` {% endcode %} In your\_folder we will add two files. The first will be entitled rabbitmq.properties: {% code overflow="wrap" %} ``` spring.rabbitmq.host=rabbitmq_host_name spring.rabbitmq.port=5672 org.openiam.rabbitmq.hosts=${spring.rabbitmq.host}:${spring.rabbitmq.port} spring.rabbitmq.username=openiam org.openiam.rabbitmq.concurrent.consumers=20 org.openiam.rabbitmq.max.concurrent.consumers=50 org.openiam.rabbitmq.prefetch.count=2 org.openiam.rabbitmq.channelTransacted=true org.openiam.rabbitmq.channelCacheSize=10 org.openiam.mq.broker.encryption.key=ff808181670838e0016708610547001b ``` {% endcode %} Next, create vault.properties: ``` vault.uri=https://rabbitmq_host_name:8200 vault.authentication=CERT vault.ssl.key-store=file://path_to_vault.jks vault.ssl.key-store-password=passwd00 ``` Create a directory entitled 'your\_directory/conf/vault/client' in your\_folder and put vault.jks (you have to grab it from the OpenIAM box) in it. Download libsapjco3.so and add it to your\_directory. Create a file entitled sap\_startup.sh with the following content: {% code overflow="wrap" %} ```bash #!/bin/bash kill -9 $(pgrep -f saps4hana-connector-rabbitmq) export LD_LIBRARY_PATH=full path to your_directory export LIBPATH=full path to your_directory setenforce 0 /usr/bin/java -Dlogging.level.root=WARN -Dlogging.level.org.openiam=INFO -Dspring.config.location=sap_application.properties -Dconfpath=full path to your_directory -jar saps4hana-connector-rabbitmq.jar > saps4hana-connector-rabbitmq.log & ``` {% endcode %} ## Starting, stopping, and restarting
DeploymentCommands
Standalone JARStart with your sap_startup.sh script; stop with kill -9 $(pgrep -f saps4hana-connector-rabbitmq) (the startup script does this automatically before starting).
RPM (systemd)systemctl start|stop|restart openiam-connector@saps4hana-connector-rabbitmq
## Command-line parameters and properties The connector is a Spring Boot application. Its defaults ship inside the jar, and you override them in either of two places: * **An external property file**, read at `${confpath}/conf/properties/saps4hana-connector-rabbitmq.properties`. The file is optional, and `confpath` is itself a system property, set with `-Dconfpath=/data/openiam/`. * **Directly on the command line**, as `-D` arguments, which win over the file. {% code overflow="wrap" %} ```bash java -Dconfpath=/data/openiam/ -Dlogging.level.org.openiam=DEBUG -Dorg.openiam.connector.queue=SAP_Connector_1_Request -jar saps4hana-connector-rabbitmq.jar ``` {% endcode %} The SAP connection values themselves are **not** set here — they are managed system parameters, listed under [Configuring the managed system](#configuring-the-managed-system). ## Verifying the connector is running {% stepper %} {% step %} In the Webconsole, open the managed system — the **Running connector status** indicator must be green. {% endstep %} {% step %} Click **Test Connection** — it must return success. {% endstep %} {% step %} In the RabbitMQ management console, confirm the `SAP_Connector_1_Request` queue exists and has a consumer. {% endstep %} {% step %} Check the connector log (`saps4hana-connector-rabbitmq.log`) for startup errors. {% endstep %} {% endstepper %} ### How to find and validate a user in SAP Login to SAP logon system. Name of the transaction is SU01. Type and press enter, you will be moved to User Maintenance window, there you can search for user. When find a user click on glass icon to see the details. Address, role and other tabs contain data that OpenIAM could manage by provisioning. ## Troubleshooting Connector troubleshooting could be done by raising logging level to DEBUG mode: `-Dlogging.level.org.openiam=DEBUG`. | Symptom | Likely cause | Resolution | | ---------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Connector never receives messages | Queue-name mismatch | The connector record's queue in OpenIAM must equal `SAP_Connector_1_Request` exactly. | | Connector fails to start with a native-library error | `libsapjco3.so` not found | `LD_LIBRARY_PATH`/`LIBPATH` must point to the directory containing the SAP JCo library. | | Connection fails | Port 3300 blocked, or wrong JCO\_CLIENT/JCO\_SYSNR | Verify network access to SAP on port 3300 and the managed-system parameters. | | Group memberships don't appear in SAP | Not implemented | SAP user-group (`GROUP:GROUPS`) assignment is not supported by the connector; use roles and profiles. | See also: [general connector troubleshooting](/connector-configuration/4-troubleshootingconnector.md) and the [connector error-code reference](/connector-configuration/4-troubleshootingconnector.md#connector-error-codes). ### When an authorization is missing A missing authorization rarely produces a clear error, which is what makes these worth recognising. | Symptom | Likely cause | | ------------------------------------------------ | --------------------------------------------------------------------- | | Test Connection passes, every operation fails | `S_RFC` missing, or the metadata modules not granted | | Roles or users come back empty, with no error | A table read refused, or an `S_USER_*` value too narrow | | Writes report success but nothing changes in SAP | `BAPI_TRANSACTION_COMMIT` not granted | | The connection times out after about 60 seconds | Network rather than authorizations — usually an internal host address | ## Registering the connector in OpenIAM Register the connector under **Provisioning → Connectors** and attach it to the managed system — see [Registering the connector](/administration-guide/lifecycle/connectors-and-managed-systems.md). | Property | Default | Purpose | | ----------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `org.openiam.connector.queue` | `SAP_Connector_1_Request` | Must match the connector record in OpenIAM. | | `sap.property.date.format` | `yyyy-MM-dd` | Date format used with SAP date fields. | | `sap.general.checkIfUserHasPwdAlreadySet` | `false` | When `true`, the connector first checks whether the user's SAP password already equals the new value and skips the change if so. | | `CIPHER_sap.general.dummyPassword` | (encrypted) | Encrypted temporary password. When setting a password, the connector first applies this dummy value, then performs a password change from the dummy to the real password, so the resulting password is not flagged as "initial" by SAP. | ## Configuring the managed system **Service account information:** During the Managed System configuration you should provide login (service account username), password, host or IP address where SAP is hosted. We will also need the following SAP instance specific parameters: | Parameter name | Description | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | JCO\_CLIENT | Specifies the SAP client. Three-digit client number; preserve leading zeros if they appear in the number | | JCO\_LANG | Specifies the login language. ISO two-character language code (for example, EN, DE, FR), or SAP-specific single-character language code. | | JCO\_SYSNR | Indicates the SAP system number. | ### Connecting through a message server Where the system sits behind a message server rather than a named application server, the connector takes the message server's details instead of `JCO_ASHOST`: | Parameter | Description | | ------------ | ---------------------------------- | | `JCO_MSHOST` | The message server host | | `JCO_MSSERV` | The message server service or port | | `JCO_GROUP` | The logon group | ## Attribute mapping and policy map The out-of-the-box configuration of the SAP managed system provides rules for writing into the following SAP fields of the user object: * USERNAME * BAPIPWD:PASSWORD * E\_MAIL:ADDRESS * FIRSTNAME:ADDRESS * LASTNAME:ADDRESS * PROFILE:PROFILES * ROLE:ROLES {% hint style="warning" %} Role (`ROLE:ROLES`) and profile (`PROFILE:PROFILES`) memberships are provisioned to SAP. SAP **user group** memberships (`GROUP:GROUPS`) are not implemented in the current connector — such values are logged and skipped. {% endhint %} ## Reconciliation and synchronization Instructions on how to set up synchronization are provided in [Configuring synchronization](/administration-guide/lifecycle/synchronize-and-import-data.md). OpenIAM ships five SAP synchronizations, and they are listed with their scripts and run order in [SAP S/4HANA reference](/connector-configuration/sap/sap-reference.md#shipped-synchronizations). A **user** search query is a filter on the login: `USERNAME LIKE 'TEST.USERSAP'`, or `USERNAME LIKE '%'` for all. An **entitlement** search query starts with a prefix naming what to read. The connector reads more than role names now, and the prefix is what selects between them: | Prefix | Reads | | ------------------------ | ----------------------------------------------------- | | `role:` *(or no prefix)* | the roles themselves, with descriptions and role type | | `roleauth:` | the authorization values inside each role | | `tcode:` | the transactions each role grants | | `composite:` | which single roles each composite holds | | `menu:` | the role menu | | `profile:` | profiles | | `group:` | user groups | Each becomes roles and groups in OpenIAM — see [What OpenIAM stores](/connector-configuration/sap/sap-reference.md#what-openiam-stores) for the shape, and [Filter syntax](/connector-configuration/sap/sap-reference.md#filter-syntax) for what the pattern after the prefix may contain. The older uppercase forms (`ROLE:`, `PROFILE:`, `GROUP:`) still work. ### Role searches read the role table, not the search help The role list used to come from SAP's role search help — the F4 list a person sees when picking a role. That list leaves roles out: at one customer it hid `SAP_EHS_OH_ASSIGN` and roughly 120 other `SAP_*` roles, with or without `S_USER_AGR`. The authorization searches read the `AGR_*` tables, which do hold them, so a role could have its authorizations linked and yet never be created. Role searches now read `AGR_DEFINE`, the role table itself, which has every role. Each role also carries its `description`, `PARENT_ROLE` and `ROLE_TYPE`. ### Saving a user keeps the roles the request did not mention `BAPI_USER_ACTGROUPS_ASSIGN` replaces a user's whole role list rather than adding to it, so a save that named one role used to drop every other role the user held. The connector now reads the current assignments from `AGR_USERS` and sends the merged list. Two related behaviors follow from the same work: * **A role held only through a composite is not reported as a direct assignment.** Those rows carry `COL_FLAG = X` in `AGR_USERS` and arrive with the composite. * **Every user carries `ACTIVITY_GROUPS_COUNT`, including `0`.** OpenIAM drops attributes with no value, so without the count a user whose last role had been removed looked identical to one whose roles were never read. The count is what lets the user sync remove that last role — and a count that disagrees with the roles actually read removes nothing and logs a warning. {% hint style="warning" %} **On a large SAP system, split the authorization sync.** `AGR_1251` can hold hundreds of thousands of rows, and a single `roleauth:*` run can outlast RabbitMQ's default 30-minute consumer timeout. Either split it by role prefix — `roleauth:Z*`, `roleauth:SAP_*` — or raise `consumer_timeout`. {% endhint %} ## Video tutorial {% embed url="" %} Configuring the SAP S/4HANA connector {% endembed %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openiam.com/connector-configuration/sap.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.