@saptools/cf-xsuaa

✨ Features

• 🔑 Zero-config OAuth2 — fetches client_credentials tokens straight from the XSUAA binding of any CF app
• 💾 Smart caching — reuses tokens until they expire so you do not hand out stale JWTs
• 🧩 CLI & API — drop into shell scripts, Node pipelines, or your favorite test runner
• 🔗 CF-aware — resolves CF API endpoints from region keys via @saptools/cf-sync, no manual URLs
• 🔒 Type-safe — shipped with full TypeScript definitions
• 🪶 Tiny — one dependency (commander) and zero runtime magic

📦 Install

# Global CLI
npm install -g @saptools/cf-xsuaa

# Or as a dependency
npm install @saptools/cf-xsuaa
# pnpm add @saptools/cf-xsuaa
# yarn add @saptools/cf-xsuaa

Note

Requires Node.js ≥ 20 and the cf CLI on PATH. For the first secret fetch, set SAP_EMAIL and SAP_PASSWORD.

Updates

Every command first checks npm for a newer @saptools/cf-xsuaa (at most once an hour, one small request with a 2-second timeout) and, when one exists, installs that exact version with the package manager that owns the running binary and re-runs the command you typed on the new version. Both steps are announced on stderr; nothing is printed when the install is already current:

cf-xsuaa: updating 0.2.0 -> 0.3.0 ...
cf-xsuaa: updated to 0.3.0; re-running the command

If the install cannot complete, one stderr line gives the manual command and the command runs on the installed version; that version is not retried for a day. cf-xsuaa self-update forces the check and install now; cf-xsuaa self-update --check only reports.

The updater switches itself off in CI (CI set), under NODE_ENV=test or NO_UPDATE_NOTIFIER, when the binary runs from a source checkout, an npm link or an npx cache, and inside the re-run itself. It never writes to stdout, never asks for input, never uses sudo, and never moves onto a prerelease. Its state lives in ~/.saptools/updates/.

🚀 Quick Start

# 1. Tell cf-xsuaa who you are (only needed for the first secret fetch)
export SAP_EMAIL="you@company.com"
export SAP_PASSWORD="your-sap-password"

# 2. Grab a token (auto-fetches the XSUAA binding on first call, caches it forever)
cf-xsuaa get-token-cached \
  --region ap10 --org my-org --space dev --app my-srv

That's it. Copy the printed JWT into curl, Postman, bruno, or wherever you need it. Next call reuses the cached token until it expires.

🧰 CLI

Every command identifies an app with the same four flags:

🔎 cf-xsuaa fetch-secret

Pull the XSUAA client credentials out of the app's VCAP_SERVICES and cache them to disk. Run this once per app, or whenever the binding rotates.

cf-xsuaa fetch-secret --region ap10 --org my-org --space dev --app my-srv

🎟️ cf-xsuaa get-token

Fetch a fresh OAuth2 client_credentials token and print the JWT to stdout. Auto-runs fetch-secret first if the binding isn't cached yet.

cf-xsuaa get-token --region ap10 --org my-org --space dev --app my-srv

⚡ cf-xsuaa get-token-cached

Return the cached token if it's still valid, otherwise fetch a new one. This is what you want 99% of the time.

TOKEN=$(cf-xsuaa get-token-cached --region ap10 --org my-org --space dev --app my-srv)
curl -H "Authorization: Bearer $TOKEN" https://my-srv.cfapps.ap10.hana.ondemand.com/api/health

Tip

Cached tokens are refreshed before they become stale, so callers do not receive a JWT that is about to expire.

📁 Output File

All state lives in a single JSON file under your home directory:

~/.saptools/xsuaa-data.json

{
  "version": 1,
  "entries": [
    {
      "region": "ap10",
      "org": "my-org",
      "space": "dev",
      "app": "my-srv",
      "credentials": {
        "clientId": "sb-xsappname!t123",
        "clientSecret": "<redacted>",
        "url": "https://my-org.authentication.ap10.hana.ondemand.com",
        "xsappname": "my-app!t123"
      },
      "token": {
        "accessToken": "eyJhbGciOi...",
        "expiresAt": "2026-04-18T12:34:56.000Z"
      },
      "fetchedAt": "2026-04-18T12:20:00.000Z"
    }
  ]
}

Important

Prefer the CLI or exported APIs over parsing this file directly — the on-disk format is an implementation detail.

❓ FAQ

🛠️ Development

From the monorepo root:

pnpm install
pnpm --filter @saptools/cf-xsuaa build
pnpm --filter @saptools/cf-xsuaa typecheck
pnpm --filter @saptools/cf-xsuaa test:unit
pnpm --filter @saptools/cf-xsuaa test:e2e

The e2e suite auto-discovers a real CF app with an xsuaa service binding by scoring candidates from ~/.saptools/cf-structure.json. To pin a specific target:

export E2E_TARGET="ap10/my-org/my-space/my-srv"

🌐 Related

• 📦 @saptools/cf-sync — sync the CF region → org → space → app tree to disk
• 🗂️ saptools monorepo — the full toolbox

👨‍💻 Author

dongtran ✨

📄 License

MIT

Made with ❤️ to make your work life easier!