What is XSUAA and xs-security.json

Learn what XSUAA does, how it fits in the BTP authentication flow, and use cds add xsuaa to generate and configure xs-security.json.

What is XSUAA and xs-security.json

Every BTP application that needs to know who the user is — or restrict access by role — must use XSUAA.

What XSUAA does

XSUAA (Extended Services for User Account and Authentication) is BTP's OAuth2 authorization server. It:

Issues JWT tokens to authenticated users
Embeds scopes (permissions) into those tokens based on the user's role assignments
Lets your CAP service verify the token and read req.user without writing any auth code yourself

How it fits in a BTP app

Browser / Client
    │
    ▼
AppRouter  ─── redirects unauthenticated users to ───►  XSUAA (login page)
    │                                                         │
    │◄── returns JWT token with user info + scopes ──────────┘
    │
    │  forwards request with Authorization: Bearer <token>
    ▼
CAP Service  ─── validates token via XSUAA public key ───► allows / denies

Your CAP service never sees passwords — it only sees a signed JWT that XSUAA already verified.

Add XSUAA to a CAP project

cds add xsuaa

This does three things:
1. Creates xs-security.json in the project root
2. Adds @sap/xssec and passport to package.json
3. Adds a requires.auth section to the cds config in package.json

The generated xs-security.json — explained

{
  "xsappname": "bookshop",
  "tenant-mode": "dedicated",
  "description": "Security descriptor for bookshop",
  "scopes": [
    {
      "name": "$XSAPPNAME.admin",
      "description": "Full administrative access"
    },
    {
      "name": "$XSAPPNAME.viewer",
      "description": "Read-only access"
    }
  ],
  "attributes": [],
  "role-templates": [
    {
      "name": "admin",
      "description": "Administrators",
      "scope-references": ["$XSAPPNAME.admin"]
    },
    {
      "name": "viewer",
      "description": "Read-only users",
      "scope-references": ["$XSAPPNAME.viewer"]
    }
  ],
  "role-collections": [
    {
      "name": "Bookshop Admin",
      "description": "Full access to Bookshop",
      "role-template-references": ["$XSAPPNAME.admin"]
    }
  ],
  "oauth2-configuration": {
    "redirect-uris": ["https://*.hana.ondemand.com/**"]
  }
}

Field	What it means
`xsappname`	Unique app identifier — scopes are prefixed with this
`tenant-mode`	`dedicated` = single-tenant, `shared` = multi-tenant (SaaS)
`scopes`	Atomic permissions your app checks for
`$XSAPPNAME`	Placeholder that becomes your actual xsappname at deployment
`role-templates`	Named collections of scopes — assigned to role collections
`role-collections`	What admins assign to users in the BTP cockpit
`oauth2-configuration`	Allowed redirect URIs after login — use wildcards for CF

Create the XSUAA service instance on BTP

You need an actual service instance before deploying. Either:

Option A — via CF CLI:

cf create-service xsuaa application bookshop-xsuaa -c xs-security.json

Option B — via mta.yaml (recommended):
Declare it as a resource (covered in topic 763) — the MTA deployer creates it automatically.

Key rule

$XSAPPNAME prefix is mandatory on scope names. If you write the scope as just admin (without the prefix), the JWT token your XSUAA issues will never contain that scope and all @restrict checks will fail silently.