Configuring Access to S4HANA Cloud with Basic Auth

Configuring Access to S/4HANA Cloud with Basic Auth

This guide explains how to connect sap-dev and sap-bridge to an SAP S/4HANA Cloud system (e.g. S/4HANA Cloud Public Edition or sandbox environments) using Basic Authentication with a dedicated Technical Communication User.

---

1. Background & Architecture

In SAP S/4HANA Cloud, authentication differs fundamentally from traditional on-premise systems:

• No Basic Auth for Dialog Users: Human dialog users log in via SAP Cloud Identity Services (SAML 2.0 / OpenID Connect). Sending basic auth credentials for a dialog account causes the cloud gateway to return an HTML SAML SSO login redirect rather than authenticating the API call.
• Technical Communication Users: Programmatic HTTPS access (OData, REST) requires creating a dedicated technical Communication User and assigning it to one or more Communication Arrangements.
• API Hostname (-api): Cloud systems separate end-user UI traffic from API traffic. Always connect to the API gateway host (e.g. myXXXXXX-api.s4hana.cloud.sap), not the Fiori Launchpad user interface hostname.
• Non-ABAP Mode: Unless your tenant is a 3-System Landscape (3SL) Development Tenant with Developer Extensibility (SAP_COM_0510), S/4HANA Cloud instances operate in pure OData/API mode without classic ADT workbench or SAP GUI access.

---

2. Step-by-Step Setup in S/4HANA Cloud

Step 1: Create the Communication User

1. Log into your S/4HANA Cloud Fiori Launchpad.
2. Open the app Maintain Communication Users (App ID F2268).
3. Click New.
4. Enter:
   • User Name: e.g., TECH_SAPDEV or CC_SAPDEV
   • Description: Technical User for sap-bridge OData Integration
   • Password: Set a strong password (or use Propose Password). Save this password securely.
5. Click Create.

Step 2: Create the Communication System

1. Open the app Communication Systems (App ID F1762).
2. Click New.
3. Enter:
   • System ID: e.g., SAP_BRIDGE_SYS
   • System Name: SAP Bridge Integration System
4. Click Create.
5. In General Data:
   • Set Host Name to your company domain or an external FQDN (e.g. yourcompany.com or bridge.sapdev.local).
     (Do not use localhost or loopback IPs; communication scenarios with outbound notification capabilities reject localhost as an invalid outbound target).
6. Scroll down to Users for Inbound Communication:
   • Click ＋ (Add).
   • Authentication Method: Select User Name and Password.
   • User Name: Select the user created in Step 1 (TECH_SAPDEV).
7. Click Save.

Step 3: Create the Communication Arrangement(s)

1. Open the app Communication Arrangements (App ID F1763).
2. Click New.
3. Scenario: Select the business scenario you wish to access, for example:
   • SAP_COM_0109 for Sales Orders (API_SALES_ORDER_SRV)
   • SAP_COM_0008 for Business Partner / Customer / Vendor (API_BUSINESS_PARTNER)
   • SAP_COM_0002 for Financials / Journal Entries (API_JOURNALENTRYITEMBASIC_SRV)
   • Or any custom scenario (YY1_...) created from Custom CDS Views.
4. Click Create.
5. Select your Communication System (SAP_BRIDGE_SYS).
   • The Inbound Communication User will populate automatically.
6. Check Inbound Services to confirm the service URL path and verify that the hostname contains -api.
7. Click Save.

(Repeat Step 3 for any additional communication arrangements you want to access under the same technical user).

---

3. Configuring the System in the sap-bridge Dashboard

1. Open your sap-bridge Web Dashboard (http://127.0.0.1:58454/?workspace_id=...).

2. Click Add System (or edit your existing system card):

   • Host: myXXXXXX-api.s4hana.cloud.sap (make sure to include -api)
   • Port: 443
   • Scheme: https
   • Auth Type: Basic Auth
   • Username: The technical Communication User ID (TECH_SAPDEV)
   • Password: The Communication User password
   • Client: Configure the assigned tenant SAP client (e.g. 100). Both SAP S/4HANA Cloud and SAP BTP ABAP Environment have assigned clients (typically 100 for development or business tenants).
   • Language: Configure the supported logon language (e.g. EN, DE).
   • Non-ABAP System: Checked (activates pure OData/API mode)

   [!NOTE] Checking Non-ABAP System activates pure OData/API mode, suppressing classic ADT workbench and Agent RPC requirements. Client and language parameters can and should still be configured whenever required by target OData services or gateway routing.

3. Click Save System.

---

4. Configuring the Universal API Root Path (Heartbeat Probe)

When you assign multiple communication arrangements to the same technical user, point the dashboard liveness probe to SAP's standard OData Catalog Service:

1. On your system card in the Web Dashboard, click the Agent Settings icon ().
2. Set API Root Path to:

   /sap/opu/odata/IWFND/CATALOGSERVICE;v=2/
   

3. Save the settings.

Why this endpoint?

• Universal Catalog: /sap/opu/odata/IWFND/CATALOGSERVICE;v=2/ lists all OData services exposed to the authenticated user.
• Arrangement Agnostic: It verifies end-to-end connectivity, TLS, and basic auth credentials without binding the health check to a single specific business object.
• Standard OData Document: It returns an AtomPub service collection document, resolving cleanly with HTTP 200 OK on the dashboard.

---

5. Querying Data via AI Agents

Once configured, AI agents can query any active communication arrangement using the sap_odata_call tool:

Example: Reading Sales Orders (SAP_COM_0109)

{
  "system_alias": "JYF-100",
  "service_path": "/sap/opu/odata/sap/API_SALES_ORDER_SRV",
  "entity_set": "A_SalesOrder",
  "action": "READ",
  "select": "SalesOrder,SalesOrderType,SoldToParty,TotalNetAmount,TransactionCurrency"
}

Example: Reading Business Partners (SAP_COM_0008)

{
  "system_alias": "JYF-100",
  "service_path": "/sap/opu/odata/sap/API_BUSINESS_PARTNER",
  "entity_set": "A_BusinessPartner",
  "action": "READ",
  "filter": "BusinessPartnerType eq '0001'"
}