SAP OAuth and Certificates

OAuth 2.0 is the industry standard for authorizing access to APIs without sharing passwords. Instead of giving a caller your actual credentials, you issue a short-lived access token. The token proves the caller is authorized, but it expires quickly and carries only the specific permissions granted — nothing more.

Think of OAuth like a hotel key card. When you check in, the front desk verifies your identity (authentication). They then give you a key card (access token) that only opens your room (limited scope). When you check out, the key card deactivates (token expiration). If someone finds your key card in the hallway, it only opens one room and only for the duration of your stay.

OAuth 2.0 Flows

OAuth 2.0 defines several flows (called grant types) for different scenarios. CPI works with two main flows:

Client Credentials Flow (Machine-to-Machine)

Used when a server application calls another server application, with no human user involved. The calling system (client) presents its own credentials — a client ID and client secret — to the authorization server. The authorization server issues an access token. The client uses that token to call the protected API.

1. CPI sends: POST /token
   Body: grant_type=client_credentials
         client_id=my-cpi-app
         client_secret=secret-value

2. Auth Server responds:
   {
     "access_token": "eyJhbGciOiJSUzI1...",
     "token_type": "Bearer",
     "expires_in": 3600
   }

3. CPI calls SAP API:
   GET /sap/opu/odata/sap/API_SALES_ORDER_SRV/A_SalesOrder
   Authorization: Bearer eyJhbGciOiJSUzI1...

4. SAP validates token, returns data

Authorization Code Flow (User-Delegated Access)

Used when an application needs to access resources on behalf of a human user. The user logs in through their identity provider, approves the access, and the application receives a code that it exchanges for a token. This flow appears when CPI needs to access a resource that belongs to a specific user — for example, reading files from that user's Google Drive.

OAuth in CPI Configuration

When configuring a receiver adapter in CPI that uses OAuth, you store the OAuth credentials as a OAuth2 Client Credentials security material:

• Token Service URL – The authorization server endpoint that issues tokens
• Client ID – The application identifier registered with the authorization server
• Client Secret – The application's password (stored securely, never in plain text)
• Scope – The specific permissions requested (e.g., "read:orders write:invoices")

CPI handles token fetching and renewal automatically. You configure the OAuth artifact once. CPI obtains a token before the first call, caches it, and renews it automatically when it expires — all without any iFlow changes.

JWT: The Token Format

Most OAuth 2.0 tokens today use the JWT (JSON Web Token) format. A JWT is a self-contained token that carries claims — pieces of information about the caller and the granted permissions.

A JWT has three parts separated by dots:

eyJhbGciOiJSUzI1NiJ9    ←  Header (algorithm used)
.
eyJzdWIiOiJDUEktQVBQIiw  ← Payload (claims: who, what, when)
  JleHAiOjE3MTQ2NjIwMDB9
.
SflKxwRJSMeKKF2QT4fwpMeJ  ← Signature (proof of authenticity)

The receiver (SAP) validates the JWT signature using the authorization server's public key. If the signature is valid and the token has not expired, the request is allowed. CPI can both consume JWTs (when calling external APIs) and validate incoming JWTs (when external systems call CPI endpoints).

Digital Certificates in CPI

Certificates prove identity. A digital certificate contains a public key, the owner's identity, and a digital signature from a Certificate Authority (CA) that vouches for the certificate's authenticity. Certificates power several CPI functions: TLS connections, mutual TLS authentication, digital message signing, and PGP encryption.

The CPI Keystore

The CPI Keystore is the secure storage area for certificates and private keys. You access it through the Monitor section under Manage Security. The keystore holds:

• Private Key Pairs – Your private key and its associated public certificate. Used for signing messages you send and decrypting messages others send to you.
• Trusted Certificates – Public certificates from external parties. CPI trusts these when establishing TLS connections or verifying digital signatures from those parties.

Certificate Lifecycle

Certificates expire. A certificate that was valid when you built your integration will stop working on its expiry date. Expired certificates cause integration failures — sometimes unexpectedly, sometimes months after you last thought about the integration.

Certificate lifecycle:
[Issued] → [Active: used for authentication] → [Near Expiry] → [Expired]
   ↓             (months to years)                 (alert!)       (BREAKS)
[Store in                                     [Renew before
 CPI Keystore]                                 expiry date]

Best practice: Set calendar reminders 60 and 30 days before each certificate's expiry date. Many organizations use monitoring tools that automatically alert when a certificate approaches expiry. Renewing a certificate involves generating or receiving a new certificate file and uploading it to the CPI Keystore, then updating any adapters that reference it.

Setting Up Mutual TLS in CPI

Mutual TLS (mTLS) requires both CPI and the external system to present certificates. Here is the setup process:

1. Generate a key pair (private key + certificate signing request) in CPI Keystore
2. Send the certificate signing request to a CA — either your internal CA or a public one
3. Receive the signed certificate from the CA and import it into the CPI Keystore
4. Provide your CPI certificate to the external system so they can trust it
5. Import the external system's certificate into CPI as a trusted certificate
6. Configure the receiver adapter to use the client certificate for authentication

PGP Keys for Message Encryption

PGP (Pretty Good Privacy) uses a pair of keys for encryption and decryption: a public key for encrypting and a private key for decrypting. If a partner wants to send you an encrypted file:

• You generate a PGP key pair and give the partner your public key
• The partner encrypts the file using your public key
• CPI receives the encrypted file and decrypts it using your private key (stored in CPI Keystore)
• Nobody else can decrypt the file without your private key

CPI's PGP Decryptor step handles this automatically. You configure the alias of the private key stored in the keystore, and CPI decrypts every message that arrives in PGP-encrypted format.

Rotating Credentials Safely

When a secret or certificate must be changed (due to expiry, compromise, or policy), follow this rotation sequence to avoid downtime:

1. Add the new credential/certificate to CPI Keystore under a new alias
2. Update iFlows to reference the new alias (in a non-production environment first)
3. Test that connections work with the new credential
4. Deploy the updated iFlows to production
5. Only then, deactivate or remove the old credential

Removing the old credential before updating the iFlows causes an immediate outage. Following this sequence keeps integrations running throughout the rotation process.