48 · XSUAA Service Binding

Create an xs-security.json, bind XSUAA, obtain a service key, and configure local .env for development.

Episode 48 — XSUAA Service Setup

What you'll learn

• Creating and binding the XSUAA service instance
• The xs-security.json file — basic structure
• OAuth client credentials vs authorization code flow
• Binding XSUAA to your CAP app
• Testing JWT validation locally

Why this matters

XSUAA is the gate between the internet and your CAP app. Setting it up correctly — with the right scopes, the right oauth2-configuration, and the right service key — is the foundation for all authorization work. One misconfiguration here causes 401/403 errors everywhere.

Creating XSUAA via BTP Cockpit

1. BTP Cockpit → Subaccount → Service Marketplace → Authorization & Trust Management Service (XSUAA)
2. Select plan: application (for browser + CAP apps)
3. Click "Create" → enter service instance name (e.g., bookshop-xsuaa)
4. Provide xs-security.json as service parameters

xs-security.json — minimum viable

{
  "xsappname":    "bookshop",
  "tenant-mode":  "dedicated",
  "scopes": [
    { "name": "$XSAPPNAME.Admin",  "description": "Full access"    },
    { "name": "$XSAPPNAME.Buyer",  "description": "Buy books"      },
    { "name": "$XSAPPNAME.Reader", "description": "Browse catalog" }
  ],
  "role-templates": [
    {
      "name":        "Admin",
      "description": "Administrator role",
      "scope-references": ["$XSAPPNAME.Admin"]
    },
    {
      "name":        "Buyer",
      "description": "Buyer role",
      "scope-references": ["$XSAPPNAME.Buyer", "$XSAPPNAME.Reader"]
    }
  ],
  "oauth2-configuration": {
    "token-validity":    43200,
    "redirect-uris":     ["https://your-app.cfapps.eu10.hana.ondemand.com/**"]
  }
}

Create service via CF CLI

# Create XSUAA service instance
cf create-service xsuaa application bookshop-xsuaa \
  -c xs-security.json

# Update after changing xs-security.json
cf update-service bookshop-xsuaa -c xs-security.json

# Create a service key for local development
cf create-service-key bookshop-xsuaa bookshop-xsuaa-key
cf service-key bookshop-xsuaa bookshop-xsuaa-key
# Copy the credentials JSON

Binding to the CAP app

# mta.yaml
modules:
  - name: bookshop-srv
    type: nodejs
    requires:
      - name: bookshop-xsuaa  # binds the XSUAA service

resources:
  - name: bookshop-xsuaa
    type: org.cloudfoundry.managed-service
    parameters:
      service:      xsuaa
      service-plan: application
      path:         ./xs-security.json

Local testing with service key

# Create .env with VCAP_SERVICES from the service key
export XSUAA_CREDENTIALS=$(cf service-key bookshop-xsuaa bookshop-xsuaa-key | tail -n +2)

# Or write to .env (add to .gitignore!)
echo "VCAP_SERVICES=$(cf service-key bookshop-xsuaa bookshop-xsuaa-key | tail -n +2 | \
  python3 -c 'import sys,json; creds=json.load(sys.stdin); print(json.dumps({"xsuaa":[{"credentials":creds}]}))')" > .env

// .cdsrc.json
{
  "requires": {
    "auth": {
      "[production]": {
        "kind": "xsuaa",
        "vcap": { "label": "xsuaa" }
      }
    }
  }
}

Getting a test JWT (client credentials flow)

# Get a JWT for service-to-service testing
CLIENT_ID=<from service key>
CLIENT_SECRET=<from service key>
TOKEN_URL=<from service key uaadomain>/oauth/token

curl -s -X POST "$TOKEN_URL" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials&response_type=token" \
  | jq .access_token

### Use the token in a request
GET http://localhost:4004/catalog/Books
Authorization: Bearer <access_token>

Rotate XSUAA credentials

# Regenerate the client secret (rotates credentials)
cf delete-service-key bookshop-xsuaa bookshop-xsuaa-key
cf create-service-key bookshop-xsuaa bookshop-xsuaa-key

# Re-create .env with new credentials

Hands-on exercise

1. Create an XSUAA service instance with Admin and Buyer roles in your BTP trial
2. Create a service key and configure .env
3. Run cds watch with production auth profile and request a JWT via client credentials
4. Use the JWT in a REST client request and verify req.user is populated

Checkpoint ✓

• [ ] xsappname in xs-security.json is the prefix for all scope names
• [ ] Service binding injects XSUAA credentials via VCAP_SERVICES
• [ ] Client credentials flow gives a service token (no user context)
• [ ] cf update-service -c xs-security.json applies changes to an existing instance