OAuth SAML Bearer Client

This is a basic implementation of an OauthSAMLBearer client as used by SAP Cloud 4 Customer (C4C) and other SAP applications.

The OAuthSAMLBearer flow allows a client application to make requests to the SAP OData API within the context of a regular user. No elevated permissions are required by the client application, and the OData API will respect access rights of the user in whose name the request is being made.

Usage

Setup an OAuth identity provider in the target application. Generate an SSL keypair for the identity provider and store the key and certificate of the identity provider in PEM format (see generate.sh).

Prepare a config object with the following properties:

| Property | Description | | ------------- | ------------------------------------------------------------------------------------ | | clientId | ClientID of the OAuth token endpoint credentials | | clientSecret | Secret of the OAuth token endpoint credentials | | tokenEndPoint | URL of the OAuth token endpoint | | entityId | SSO base URL of the target application tenant | | issuer | Name of the OAuth 2.0 identity provider configured in target application | | nameIdFormat | Format of the user ID, either emailAdress or unspecified | | certificate | Certificate assigned to the OAuth identity provider in C4C (PEM string) | | signingKey | Private key of the OAuth identity provider used for signing (unencrypted PEM string) |

import { OAuthSAMLBearerClient } from 'oauth-saml-bearer-client';
import fs from 'fs';

const certificate = fs.readFileSync('certificate.pem', 'utf8');
const private_key = fs.readFileSync('private_key.pem', 'utf8');

const client = new OAuthSAMLBearerClient({
    clientId: '_123456789',
    clientSecret: 'ABC123456789',
    entityId: 'HTTPS://my123456-sso.crm.ondemand.com',
    tokenEndPoint: 'https://my123456.crm.ondemand.com/sap/bc/sec/oauth2/token',
    issuer: 'MY-IDP',
    certificate: certificate,
    signingKey: private_key,
    nameIdFormat: 'emailAddress',
    scope: 'UIWC:CC_HOME',
});

const user = '[email protected]';

const token = await client.getAccessToken(user);

console.log(token);

If successful, the response is an access token with scope and validity.

{
    "access_token": "ABY-0tpvHtyn8V_Y0kZFExeEUsu41FIi9fP45VdLXfd2Mlf_",
    "token_type": "Bearer",
    "expires_in": "3600",
    "scope": "UIWC:CC_HOME"
}

Optional settings

| Property | Description | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | assertionTemplate | Custom template to build the assertion from. If not provided, assets/assertion_template_minimal.xml is used. | | cacheTokens | Optional boolean to indicate whether requested tokens should be cached in memory until they expire (default=false). If not set or false, client will always request a new token. |

This can be used to transparently request the token on requests to the OData API, for example with axios:

axios.interceptors.request.use(async (axiosConfig) => {
    const token = await oauthClient.getAccessToken(nameId);
    axiosConfig.headers.Authorization = `Bearer ${token}`;
    return axiosConfig;
});

Caution with server implementations (C4C)

The C4C token endpoint API is extremely sensitive. The API will return 400 and a generic exception if there is the slightest deviation from the expected assertion format. The exception doesn't give any indication whether the error is in XML syntax, the signature, the expected values within the assertion, or anything else. All one can do is trial and error until it works.

Documentation

Documentation of the OAuth SAML Bearer flow is unfortunately rare. Here is a basic overview from SAP: https://wiki.scn.sap.com/wiki/display/Security/Using+OAuth+2.0+from+a+Web+Application+with+SAML+Bearer+Assertion+Flow

To set up a trusted third party who is allowed to authenticate users using the OAuthSAMLBearer flow, follow these instructions: https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/40d20a26f3dd445facff151b249fcf94.html

The OAuth SAML Bearer specification proposal: https://tools.ietf.org/id/draft-ietf-oauth-saml2-bearer-10.html