XS Advanced Container Security API for node.js
npm install @sap/xssec@sap/xssec: SAP BTP Security Services Node.js Integration Library
==========================================================
This module allows Node.js applications to authenticate users via JWT tokens issued by SAP Business Technology Platform (BTP) security services (SAP Cloud Identity Services and XSUAA). It also provides an API for fetching tokens from these services.
v3 package
v3 package. While we strongly recommend to migrate to the new API, backward-compatibility should be achievable by changing the import to this package:
js
const { createSecurityContext, requests, constants, TokenInfo, JWTStrategy } = require("@sap/xssec").v3;
`
- isTokenIssuedByXSUAA, getConfigType have been removed. Replace with class check:
`js
securityContext.token instanceof XsuaaToken // or: IdentityServiceToken, XsaToken, UaaToken
`
- getHdbToken has been removed. It should be replaceable with the following code:
`js
const hdbToken = securityContext.token.payload.ext_cxt?.['hdb.nameduser.saml'] || securityContext.token.payload['hdb.nameduser.saml'] || securityContext.token.jwt;
`
- Configuration option IAS_XSUAA_XCHANGE_ENABLED has been removed because it was unclear from which service instance to which service instance the exchange should be made when multiple instances of the same type were present. Applications can implement the exchange themselves with the new API as described here.
- Configuration option disableCache has been removed. It is also not supported by implementations from the v3 compatibility package.
- isInForeignMode has been removed.
Installation
Add a dependency to @sap/xssec to your package.json, e.g. via:
`bash
npm i @sap/xssec
`
We strongly recommend to declare the version of this dependency with a ^ (caret) to consume future minor and hotfix releases when you update your dependencies (also see Maintenance):
`json
"dependencies": {
"@sap/xssec": "^4"
}
`
Important: @sap/xssec requires at least Node.js 18 which is the current LTS version.
Maintenance
Keep the version of this dependency up-to-date as it is a crucial part of your application's security, e.g. by regularly running:
`bash
npm update @sap/xssec # or: npm update
`
This is especially important when you deploy your application with a package-lock.json that locks the version that gets installed to a fixed version, until the next npm update.
When in doubt, check which version of the module is installed via
`bash
npm list @sap/xssec
`
This will print a dependency tree that shows which versions of the module are installed, including transitive dependencies.
Example
$3
The following example gives an overview of the most important APIs of this module for user authentication in express:
`js
const { createSecurityContext, XsuaaService, SECURITY_CONTEXT, errors: { ValidationError }} = require("@sap/xssec");
const credentials = { clientid, ... } // access service credentials, e.g. via @sap/xsenv
const authService = new XsuaaService(credentials) // or: IdentityService, XsaService, UaaService ...
async function authMiddleware(req, res, next) {
try {
const secContext = await createSecurityContext(authService, { req });
// or: const secContext = await createSecurityContext([xsuaaService, identityService]], { req }); for hybrid authentication
// user is authenticated -> tie the SecurityContext to this req object via the dedicated Symbol
req[SECURITY_CONTEXT] = secContext;
return next();
} catch (e) {
// user could not be authenticated
if(e instanceof ValidationError) {
// request has invalid authentication (e.g. JWT expired, wrong audience, ...)
LOG.debug("Unauthenticated request: ", e);
return res.sendStatus(401);
} else {
// authentication could not be validated due to Error
LOG.error("Error while authenticating user: ", e);
return res.sendStatus(500);
}
}
}
app.use(authMiddleware);
// access SecurityContext in endpoint handlers
app.get('/helloWorld', (req, res) => {
if (!req[SECURITY_CONTEXT].checkLocalScope('read')) {
return res.sendStatus(403);
}
// access token information via SecurityContext
return res.send("Hello " + req[SECURITY_CONTEXT].token.givenName);
});
`
$3
As an alternative to writing the middleware manually, you can use the provided XssecPassportStrategy for passport:
`js
const { XssecPassportStrategy, XsuaaService, SECURITY_CONTEXT } = require("@sap/xssec");
const credentials = { clientid, ... } // access service credentials, e.g. via @sap/xsenv
const authService = new XsuaaService(credentials) // or: IdentityService, XsaService, UaaService ...
passport.use(new XssecPassportStrategy(authService, SECURITY_CONTEXT));
// or: passport.use(new XssecPassportStrategy([xsuaaService, identityService], SECURITY_CONTEXT)); for hybrid authentication
app.use(passport.initialize());
app.use(passport.authenticate('JWT', { session: false }));
app.get('/helloWorld', (req, res) => {
if (!req.authInfo.checkLocalScope('read')) { // access SecurityContext via req.authInfo
return res.sendStatus(403);
}
return res.send("Hello " + req.authInfo.token.givenName) // access token via SecurityContext or ...
// return res.send("Hello " + req.user.name.givenName); // access passport user via req.user
};
`
However: Once you need access to ValidationErrors for logging or analyzing requests with invalid authentication, using the passport strategy becomes more or less the same effort as writing a middleware yourself:
`js
const { errors: { XssecError, ValidationError }} = require("@sap/xssec");
...
// configure passport to failWithError to be able to catch ValidationErrors.
// Otherwise it will swallow the ValidationError and directly send a 401/403 response
app.use(passport.authenticate('JWT', { session: false, failWithError: true }));
// in your express error handler, check for errors passed on by XssecPassportStrategy and handle accordingly
app.use((err, req, res, next) => {
if(e instanceof ValidationError) {
// request with invalid authentication (e.g. JWT expired, wrong audience, ...)
LOG.debug("Unauthenticated request: ", e);
return res.sendStatus(401);
} else if (e instanceof XssecError) {
// authentication could not be validated due to an Error
LOG.error("Error while authenticating user: ", e);
return res.sendStatus(500);
} else {
// ToDo: handle other errors ...
}
});
`
Unless you have a reason to use passport, we suggest to write the middleware yourself. This gives you full control with comparable effort.
Recommendation: SAP Cloud Identity Services
For new SAP BTP applications, we recommend to directly start with SAP Cloud Identity Services and Authorization Policies instead of the other services supported by this module to get the following benefits:
- SAP BTP Landscape independent integrations
- Support for custom domains
- Fine granular (instance-based) authorization concept
- Avoid future migration effort: as customer data needs to be migrated, this migration will not be possible fully automated lateron
Major new features will only be made available for SAP Cloud Identity Services. Also, it allows consumption of XSUAA-based services that have not yet migrated.
$3
Migration for older applications from XSUAA to SAP Cloud Identity Services with Authorization Policies is currently in the pilot phase. There will be guides for different migration stages available soon.
The XsuaaLegacyExtension is the first official solution to support hybrid authentication during migration from XSUAA to SAP Cloud Identity Services.
Usage
As a basis for all usage scenarios, instantiate a new Service instance of one of the following classes exported by the module that corresponds to the authentication service your application is bound to:
- IdentityService
- XsuaaService
- XsaService (legacy systems)
- UaaService (legacy systems)
Pass the service credentials as parsed object:
`js
const { IdentityService } = require("@sap/xssec");
const credentials = { clientid ...} // access service credentials, e.g. via @sap/xsenv
const authService = new IdentityService(credentials);
`
If your application is bound to more than one authentication service, create multiple instances using the corresponding class and credentials for each service.
$3
To authenticate users, use the createSecurityContext function.
`js
try {
const secContext = await createSecurityContext(authService, { req });
// user is authenticated
} catch (e) {
// user could not be authenticated
if(e instanceof XssecError) {
// e was thrown intentionally by this module with details for the cause of the failure
}
}
`
:warning: To prevent information overlap from one user's SecurityContext to another's, do not re-use the same contextConfig object for multiple invocations of createSecurityContext!
Create a new object each time, as in the sample code. Changing the req property and then passing the same object a second time is not enough.
Since version 4.0.1, the module has mechanisms in place to avoid these issues even when used wrongly but you should not willingly trust it.
The createSecurityContext function resolves with a service-specific SecurityContext object, e.g. XsuaaSecurityContext.
The SecurityContext will always have the token property that contains a service-specific Token object, e.g. XsuaaToken that provides access to the decoded information of the token.
$3
The library can also be used for authorization checks.
#### XSUAA
An XsuaaSecurityContext provides different methods to check if the token contains a specific scope.
#### SAP Cloud Identity Service
The recommended way to perform authorization for tokens issued by SAP Cloud Identity Service, is to use Authorization Policies. After authenticating requests with this module, the authorization checks are done with a dedicated module called @sap/ams.
$3
Each Service subclass has dedicated methods that can be used to fetch tokens via the following flows:
- Client Credentials: fetchClientCredentialsToken({ options })
- Password: fetchPasswordToken(username, password, { options })
- JWT Bearer: fetchJwtBearerToken(assertion, { options })
Error Handling
The API of this module throws instances of XssecError or hierarchical subclasses thereof that can be identified like so:
`js
try {
await xsuaaService.fetchClientCredentialsToken()
} catch(e) {
if(e instanceof XssecError) {
// it is an error thrown by this module
}
}
`
There are three important subclasses of XssecError that divide the Errors into different categories like so:
`bash
XssecError
├── ConfigurationError
├── InvalidCredentialsError
├── ...
├── NetworkError
│ ├── ResponseError
├── ...
├── ValidationError
├── ExpiredTokenError
├── ...
`
- ConfigurationError indicates that your application is not using this library correctly or the authentication service is not correctly configured. You should not encounter this Error outside of development as these Errors require fixing.\
Examples:
- passing credentials to a Service constructor that are missing mandatory properties
- fetching a token via a grant_type that is not supported by the authentication server because it is disabled in the server configuration etc.
- NetworkError means the authentication server was unreachable or responded with an unexpected error. This is not necessarily an issue of this module.\
Examples:
- the authentication server is down
- a token fetch uses invalid credentials resulting in a response error etc.
- ValidationError occurs during authentication when the request did not contain valid authentication information. This is the most common type of Error thrown by this module. It has many subclasses that provide detailed information about the reason why the validation result was negative.
Examples:
- the request contained no JWT
- the JWT in the request was expired
- the JWT was not issued for this application audience
- the JWT was forged by an attacker with an invalid signature
- the JWT is valid but its x5t thumbprint does not match the client's certificate (see x5t validation) etc.
The Error classes contain error-specific properties as details:
Example:
`js
const { errors: { UnsupportedAlgorithmError }} = require("@sap/xssec");
catch(e) {
if(e instanceof UnsupportedAlgorithmError) {
// e.token contains the token whose algorithm is not supported
// e.alg contains the algorithm of the token that is not supported, e.g. "HS256"
}
}
`
Testing
We discourage application developers from basing their integration tests against BTP Security Services on a local setup that feeds this module with self-signed JWTs and a self-hosted JWKS on localhost. This was a common strategy in the past but has several problems:
- it provides a false sense of safety: Due to additional validations done by real BTP JWKS endpoints (that you will not be able to mock), the test may suceed for token payloads that would be considered invalid in productive environments. This is especially true for multi-tenant applications and micro-service based applications with inter-service communication.
- JWKS hosted via http is not supported anymore: To improve the security of the module, only URLs beginning with https scheme are supported for JWKS fetching.
- it is wasted development effort: there is no value in knowing if this module can validate signatures of tokens that you signed yourself.
Testing the signature validation capabilities of this module is already well covered by the test pipeline of this module.
If you need to weaken the validation mechanisms of this module for testing, you should commit fully to this strategy.
Consider using a simpler authentication strategy like Basic Auth with mocked users or creating mocked SecurityContext or Token instances of this module for local tests.
Cloud application frameworks typically offer mechanisms to configure different strategies in test and production profiles (CAP Example).\
In addition, complement your local tests with proper integration tests against real service instances on a dedicated test cloud landscape.
API
This section describes the public API of v4 of this module.
:warning: Accessing other properties and methods is discouraged as they may change during minor and hotfix releases of this module, even if they are not marked private via # (ECMAScript private fields/methods) or @private (JsDoc)
$3
Instances of Service(credentials, serviceConfig) are created from parsed service credentials and an optional configuration:
`js
const { IdentityService } = require("@sap/xssec");
const credentials = { clientid ...} // access service credentials, e.g. via @sap/xsenv
const serviceConfig = {
// optional, service-specific configuration object...
validation: {
x5t: {
enabled: true // enables token ownership validation via x5t signature thumbprint
}
}
};
const identityService = new IdentityService(credentials, serviceConfig);
`
#### Certificate Rotation
It is possible to update the cert and key of a Service instance by calling Service#setCertificateAndKey(cert, key) with PEM-encoded values that will be used in subsequent calls to the server.
Note: Updating the cert and key property of the credentials object passed in the Service constructor is not enough because the Service makes a copy of the credentials for internal use and then discards the original reference.
This method is useful in different scenarios, e.g:
- applications using ZTIS to manage their SAP Identity Service certificate. Whenever ZTIS provides a new pair of cert and key, the application can update the credentials of the Service instance via this method.
- credential rotation without application re-start: In SAP BTP Kyma, it is possible to rotate service bindings of a running application. Typically, this is used to refresh certificates. In that case, the method can be used to update the Service instance.
##### Full Credential Rotation
Applications that expect their credentials to be rotated with other properties besides cert and key changing, must construct a fresh new Service instance whenever new credentials are received.
#### Token Flows
The subclasses of Service provide the following service-specific methods that can be used to fetch tokens:
- Client Credentials: fetchClientCredentialsToken({ options })
- Password: fetchPasswordToken(username, password, { options })
- JWT Bearer: fetchJwtBearerToken(assertion, { options })
They resolve with the parsed JSON response from the authentication server. Typically, the desired token is the one under property access_token. However, for user-specific IdentityService tokens (Password, JWT Bearer), the desired token is typically id_token:
`js
const accessTokenJwt = (await xsuaaService.fetchClientCredentialsToken()).access_token;
const idTokenJwt = (await identityService.fetchPasswordToken(username, password)).id_token;
`
Of course, the other properties of the response, for example refresh_token, are also accessible.
The methods are annotated with service-specific JSDoc type definitions that should provide IDE-support for the function signatures and following options.
##### options
The options parameter is optional. It supports:
correlationId (string) a correlation id that allows tracing debug logs and Errors thrown by this module to the request\
token_format (jwt|opaque) can be used to explicitly specify token format \
timeout (number) maximum time in ms to wait for a response
It also supports the following service-specific options:
XSUAA:
scope (string|string[]) requested scope(s)\
tenant (string) the subdomain of a tenant on the same subaccount from which to fetch a token. Note: this parameter does not accept a zone ID. Use the zid parameter instead to pass a zone ID.\
zid (string) the zone id from which to fetch a token\
authorities (object) additional authorities that can be freely chosen during token fetch and will be put into the token under az_attr claim
Identity Service:
resource (string|string[]) name(s) of API dependency to another application that shall be consumed with this token in the format urn:sap:identity:application:provider:name:\\
refresh_expiry (number) Can be used to reduce the expiry time of the refresh token. If set to 0, no refresh token will be issued.
#### acceptsToken
Furthermore, each subclass of Service offers the method acceptsToken(token) which checks if a Token is accepted by this service instance:
`js
const jwt = ... // extract JWT from req object
const token = new Token(jwt);
if(identityService.acceptsToken(token)) {
// the JWT was issued for an application bound to this Identity Service instance but it MUST still be validated!
}
`
$3
createSecurityContext(service, contextConfig) can be called with a single Service instance or an array of Service instances as first parameter. In the latter case, the service from which the Security Context is created, will be determined based on the audience of the token.
The second parameter is a unique (!) contextConfig object that is used to pass information for the creation of this specific context.
#### contextConfig
Mandatory properties:
- req request object from which the JWT will be extracted as Bearer token from req.headers.authorization. Additionally, if present, the client's certificate will be extracted from req.headers["x-forwarded-client-cert"] where it is typically put by Cloud Foundry after SSL termination.
or:
- jwt manually provided JWT token as String
or:
- token manually provided pre-decoded Token instance. This prevents costly double-decoding of the jwt token when it has already been decoded before.
Optional properties:
- correlationId a correlation id that allows tracing debug logs and Errors thrown by this module to the request
- clientCertificatePem manually provided client certificate in PEM format
- skipValidation if true, the SecurityContext is created without validating the token. Caution! This flag MUST NOT BE ENABLED, except for testing or when the token has already been validated before, e.g. in DwC contexts.
The client certificate is only required in features such as x5t validation or proof token validation for SAP Cloud Identity Service.
$3
SecurityContext instances are returned by createSecurityContext. They have the following properties:
- service (Service) the Service on which the security context was opened
- token (Token) the parsed Token (previously TokenInfo) instance with getters for its header, payload and most important claims
- config (object) the (sanitized) contextConfig from which the SecurityContext was created
- legacy methods for v3 backward-compatibility, e.g. getAppToken(), getUserInfo()
The service-specific subclasses of SecurityContext extend this class as follows.
#### XsuaaSecurityContext
Instances of XsuaaSecurityContext additionally have methods for authorization checks:
- checkScope(scope) Checks if the scopes of the token include the given scope exactly as provided to the function. As the scopes of the token begin with the xsappname of the Xsuaa service instance, this means, the provided scope parameter must include this prefix:
`js
if(secContext.checkScope(${authService.credentials.xsappname}.READ)) {
// user is authorized
}
`
- checkLocalScope(scope) Checks if the scopes of the token include , where the xsappname comes from the credentials of the service that was used to create the SecurityContext. This is a quality-of-life function to check for scopes without passing this xsappname to the function:
`js
if(secContext.checkLocalScope("READ")) {
// user is authorized
}
`
- checkFollowingInstanceScope(scope) Checks if the scopes of the token include , where followingInstanceXsAppName is the xsappname of the XSUAA clone instance for which the token was issued. This is a quality-of-life function to check for scopes of following XSUAA instances.
#### IdentityServiceSecurityContext
- servicePlans (string[]) requires [proof token validation] contains the service plans of the caller when authenticated with proof token validation enabled
- isInternal() (boolean) requires [x5t validation] Checks whether the token from which this context was created is a token fetched by the OAuth 2.0 client for internal use. It returns true if the token was fetched via client credentials flow with the credentials of this context's IdentityService instance, false otherwise.
$3
In production, only trust information of Token instances returned by createSecurityContext (see Authentication).
However, for the purposes of testing, instances of Token can be constructed directly from a raw jwt or a combination of parsed header and payload like so:
`js
const jwt = "eyJraWQiOi...."
let token = new IdentityServiceToken(jwt);
const header = { alg: "RS256" };
const payload = { foo: "bar" };
token = new IdentityServiceToken(null, { header, payload });
`
:warning: The resulting token object is created without validating the jwt for authenticity, integrity, expiration etc.
The Token class provides easier access to the most common claims of the jwt, as well as its parsed header and payload:
- audiences (string[]) or [] if token has no audiences
- azp (string)
- clientId (string)
- email (string)
- expired (boolean)
- expirationDate (Date)
- familyName (string)
- givenName (string)
- grantType (string)
- header (object)
- issuer (string)
- issueDate (Date)
- jwt (string) from which this Token instance was created
- notYetValid (boolean) based on the optional nbf (no use before) claim. If true, the token must not be accepted yet
- origin (string)
- payload (object)
- remainingTime (integer) in seconds based on claim exp (expiration time)
- subject (string)
- legacy methods for v3 backward-compatibility, e.g. getAudiencesArray(), getTokenValue()
#### IdentityServiceToken
Instances of IdentityServiceToken additionally have
- appTid (string) application tenant id
- customIssuer (string) or null if no custom issuer has been configured
- scimId (string)
#### XsuaaToken, XsaToken, UaaToken
Instances of XsuaaToken, XsaToken, UaaToken additionally have
- azAttributes (object) az_attr claim
- extAttributes (object) ext_attr claim
- scopes (string[]) or [] if token has no scope(s)
- serviceInstanceId (string) from ext_attr
- subAccountId (string) from ext_attr or zid
- xsUserAttributes (object) xs.user.attributes from ext_ctx or direct claim
- xsSystemAttributes (object) xs.system.attributes from ext_ctx or direct claim
- zid (string) zone id
Performance optimization by caching
The library makes use of caching to improve performance and reduce latency for certain operations. This includes caching network requests, as well as caching results of computationally expensive operations.
The caching strategy ensures that the library is not any less secure when using caches. The only exception to this is that a JWKS rotation reaches the application after a (configurable) delay. However, this is a well-established trade-off to make offline token validation feasible.
Caching network requests
The library uses the following caches for responses from the authentication servers:
- OIDC Cache: Caches the OIDC configuration fetched from the authentication server.
- JWKS Cache: Caches results from the JWKS endpoint for different payloads that are required for signature validation.
These caches are crucial to achieve acceptable latency in the application, so they are enabled by default.
Caching CPU intensive operations
Optionally, caches for the results of the following CPU-intensive operations can be enabled:
- Signature Cache Caches the result of the cryptographic signature validation of a JWT token.
- Token Decode Cache: Caches header/payload after base64-decoding of a JWT token.
These caches can drastically improve latency on subsequent requests with the same token. This is especially useful in applications where the user client makes many requests in parallel or in quick succession with the same token. Experiments measured up to 500% throughput (req/s) on a ping endpoint with both caches enabled compared to the default configuration with no caching. Of course, the effect on latency gets relatively smaller in endpoints with more complex processing logic, e.g. due to database access.
For backward-compatibility, those caches are disabled by default until the next major version but we generally recommend their usage already today.
Configuration
$3
It is possible to configure the XssecPassportStrategy with scope(s) such that incoming requests must have at least one of them. Otherwise, a response with code 403 is returned:
`js
app.use(passport.authenticate('JWT', { session: false, scope: "read" }));
app.use(passport.authenticate('JWT', { session: false, scope: ["read", "write"] }));
`
$3
The default configuration for requests against a Service instance can be overridden via the requests property in the Service configuration.
#### Default request configuration
`json
{
"timeout": 2000
}
`
#### Manual request configuration
If you frequently encounter TimeoutErrors during createSecurityContext or upon OIDC configuration retrieval before a token request, you can increase the default timeout of requests:
`js
const authService = new IdentityService(identityServiceCredentials,
{
requests: {
timeout: 5000 // maximum possible value is 10000ms
}
});
`
Consequently, this timeout value will be used for fetching the OIDC configuration from the .well-known endpoint as well as fetching the JWKS.\
For token flows, you can pass an individual timeout for the token request itself that takes priority over the default timeout of the Service instance.
$3
To verify the validity of a token, the library needs to ensure that it was signed with a private key belonging to one of the public keys from the authentication server's JWKS (JSON Web Key Set). The application retrieves the JWKS via HTTP from the authentication server. It is cached to reduce both the load on the server and the latency of requests introduced by the signature validation.
Please note that the JWKS endpoint is parameterized and does additional service-specific validations based on those parameters. For this reason, among others, more than one JWKS is typically cached and individually refreshed under different cache keys that include those parameters.
There are three values that are used to control the cache:
- expiration time (integer) when a JWKS is needed for validation whose cache entry has expired (time since last refresh > expiration_time), a refresh of the JWKS is performed (if not already in progress) and the token validation of the request needs to wait synchronously until the JWKS has been succesfully refreshed.
- refresh period (integer) When a JWKS is needed for validation whose cache entry is within the refresh period (time until expiration < refresh_period), the cached JWKS will be used for validation (unless it has expired completely) and the JWKS will be refreshed asynchronously in the background.
- shared (boolean) when true, shares the cache with all Service instances of the same subclass (e.g. IdentityService) created with shared=true.\
The shared cache's configuration will be determined by the first instance created with shared=true!
Only one HTTP request at a time will be performed to refresh the JWKS.
In effect, productive systems with regular incoming requests should not experience delays from refreshing a JWKS after the initial fetch of that JWKS. Delays will only happen when the JWKS could not be refreshed during the refresh period, e.g. due to a prolonged outage of the JWKS endpoint or when no requests were received during the refresh period that would have triggered an asynchronous refresh.
##### Default cache configuration
`json
{
"shared": false,
"expirationTime": 1800000, // 1800000ms = 30min
"refreshPeriod": 900000, // 900000ms = 15min
}
`
##### Manual cache configuration
In rare situations you might need to change the cache configuration.
The expiration time is important to support key rotation scenarios and should not be too high. Otherwise, the security of the application is impacted.
:exclamation: Normally you don't need to overwrite the default values!
To overwrite cache parameters, you need to specify them as key/value pairs in :
`js
const authService = new IdentityService(identityServiceCredentials,
{
// override one default value or many
validation: {
jwks: {
expirationTime: 3600000,
// refreshPeriod: 1800000,
// shared: true
}
}
});
`
$3
A Signature Cache is a cache for the results of the cryptographic signature validation of a JWT token. It is used to improve the latency of subsequent requests with the same token (see Caching CPU intensive operations).
Each cache entry consists of the size of the cached JWT as string plus the boolean for the result.
To enable this cache, you can enable the simple, built-in LRU cache or alternatively, provide any Node.js cache implementation with the standard get/set signature. The entries of the cache do not need to be timed out with a TTL for secure operation because a signature that is (in)valid now will always be (in)valid in the future. The validation result is only used when the JWKS still contains a valid key for the token's kid, so JWKS rotation can still be used to invalidate tokens by removing the corresponding public key.
The following configuration snippet is an example that uses the built-in LRU cache:
`js
const authService = new IdentityService(identityServiceCredentials,
{
validation: {
signatureCache: {
enabled: true // enables the built-in LRU cache with default size 100
}
}
}
);
const authService = new XsuaaService(xsuaaCredentials,
{
validation: {
signatureCache: {
size: 1000 // enables the built-in LRU cache with a custom size of 1000 entries
}
}
}
);
`
The following configuration snippet is an example that uses the well-known lru-cache module as a custom cache implementation:
`js
const LRUCache = require("lru-cache");
const signatureCache = new LRUCache({ max: 100 });
const authService = new IdentityService(identityServiceCredentials,
{
validation: {
signatureCache: {
impl: signatureCache
}
}
}
);
`
$3
The Token Decode Cache is a cache for the base64 decoded header/payload objects of a JWT token. It is used to improve the latency of subsequent requests with the same token (see Caching CPU intensive operations).
Each cache entry consists of the size of the cached JWT as string plus the header/payload objects.
To enable this cache, you can enable the simple, built-in LRU cache or alternatively, provide any Node.js cache implementation with the standard get/set signature.
The following configuration snippets are examples that use the built-in LRU cache:
`js
const { Token } = require("@sap/xssec");
Token.enableDecodeCache(); // enables the built-in LRU cache with default size 100
`
`js
Token.enableDecodeCache({
size: 1000 // enables the built-in LRU cache with a custom size of 1000 entries
});
`
The following configuration snippet is an example that uses the well-known lru-cache module as a custom cache implementation:
`js
const LRUCache = require("lru-cache");
const tokenDecodeCache = new LRUCache({ max: 100 });
Token.enableDecodeCache({
impl: tokenDecodeCache // enables the built-in LRU cache with a custom implementation
});
`
$3
The library supports a configurable retry mechanism for network requests, such as fetching tokens or JWKS. This ensures resilience against temporary network issues or service unavailability.
The retry logic is based on an exponential backoff strategy with the following configurable parameters:
`json
{
"strategy": "exponential", // The retry strategy (currently only "exponential" is supported)
"retries": 3, // Maximum number of retry attempts
"initialDelay": 500, // Initial delay in milliseconds before the first retry
"factor": 3, // Multiplier for the delay after each retry
"maxDelay": 4000 // Maximum delay in milliseconds between retries
}
`
#### How it works:
1. The first retry occurs after the initialDelay (e.g., 500ms).
2. Subsequent retries increase the delay exponentially, multiplied by the factor (e.g., 500ms → 1500ms → 4000ms).
3. The delay will not exceed the maxDelay (e.g., 4000ms).
#### Example:
With the default configuration:
- Retry 1: 500ms delay
- Retry 2: 1500ms delay
- Retry 3: 4000ms delay (capped by maxDelay)
If all retries fail, the operation will throw a RetryError object, containing all errors during the attempt.
:exclamation: Note: The retry logic is only applied to network-related errors (e.g., timeouts or unreachable endpoints). It also applies to HTTP error status codes in the range 500–599, as well as 429 (Too Many Requests) and 408 (Request Timeout).
Errors such as invalid configurations or authentication failures are not retried.
`js
const authService = new IdentityService(identityServiceCredentials,
{
requests: {
retry: {
"strategy": "exponential", // The retry strategy (currently only "exponential" is supported)
"retries": 3, // Maximum number of retry attempts
"initialDelay": 500, // Initial delay in milliseconds before the first retry
"factor": 3, // Multiplier for the delay after each retry
"maxDelay": 4000 // Maximum delay in milliseconds between retries
}
}
}
);
//for the default configuration you can also just set it to true
const authService = new IdentityService(identityServiceCredentials,
{
requests: {
retry: true //take the default configuration
}
}
);
`
$3
JWKS rotation is supported out-of-the-box and you do not need to configure anything for this:
- The standard JWKS cache timings provide plenty of leeway for key rotations performed by the authentication servers.
For example, the automatic key rotation in XSUAA has a 24 hours period for both phasing out old keys and phasing in new keys while the cached JWKS is not used longer than 30 minutes.
If you are using non-default JWKS cache timings, please ensure that they are not set too high to receive JWKS updates within the leeway period.
- The token signature cache supports phasing out of old keys. Its results will not be used for tokens whose public key hase been removed from the JWKS. Also, it does not cache the absence of public keys from the JWKS, so once a new key is added to the JWKS, tokens signed with that key will be validated correctly even if they have been seen before.
$3
#### X509_GENERATED
If your authentication service instance is configured to manage certificates and keys on its own, there will be certificate and key properties in the service credentials that work out-of-the-box with this module when you use it for authenticated requests to the authentication service, e.g. when fetching tokens.
#### X509_PROVIDED
If your authentication service instance is configured to use an externally managed certificate/key you might need to add them to the service credentials before passing the credentials to the Service constructor:
`js
const { XsuaaService } = require("@sap/xssec");
const credentials = { clientid, ... } // access service credentials, e.g. via @sap/xsenv
credentials.key = // in PEM format
credentials.certificate = // in PEM format
const authService = new XsuaaService(credentials) // or IdentityService ...
`
$3
The following are Identity Service specific configuration options.
#### x5t Validation
The library optionally supports token ownership validation via x5t thumbprint (RFC 8705) for tokens issues by SAP Cloud Identity Service.
:grey_exclamation: x5t token validation should only be enabled for applications using mTLS because the x5t validation will fail when there is no client certificate used for the request. SAP BTP will automatically put the client certificate in the x-forwarded-client-cert header of requests performed against cert application routes. From there it will be picked up by this lib to do the validation against the fingerprint claim from the token payload.
To enable x5t validation, set flag to true:
`js
const authService = new IdentityService(identityServiceCredentials,
{
validation: {
x5t: {
enabled: true
}
}
});
`
#### Proof Token Validation
To enable proof token validation, set flag to true:
`js
const authService = new IdentityService(identityServiceCredentials,
{
validation: {
proofToken: {
enabled: true
}
}
});
`
After creating a SecurityContext on a service with proof token validation enabled, the service plans of the caller can be retrieved:
`js
const securityContext = await createSecurityContext(identityService, { reqWithForwardedClientCertificate });
// service plans are available via securityContext.servicePlans
`
#### XSUAA Legacy Extension
The XsuaaLegacyExtension enables hybrid authentication during migration from XSUAA to SAP Cloud Identity Services. It automatically exchanges IAS user tokens for XSUAA tokens, allowing applications to support both authentication methods.
##### Use Case
Applications migrating from XSUAA-based authentication to SAP Cloud Identity Services may need to:
- Support tenants that still authenticate via XSUAA (sending XSUAA tokens)
- Support tenants that have migrated to IAS (sending IAS tokens)
- Maintain existing XSUAA-based authorization for migrated tenants
The extension handles this by automatically fetching an XSUAA token after an IAS user token has been successfully validated, giving the application full flexibility which token to use.
##### Basic Setup
Enable the extension in the IdentityService configuration:
`js
const { IdentityService, XsuaaService, createSecurityContext } = require("@sap/xssec");
const xsuaaService = new XsuaaService(xsuaaCredentials);
const identityService = new IdentityService(identityServiceCredentials, {
xsuaaLegacyExtension: true
});
// The extension is now active with default settings (IAS-primary mode)
// Both services must be passed to createSecurityContext
const securityContext = await createSecurityContext([identityService, xsuaaService], { req });
`
The extension fetches the XSUAA token from the first XsuaaService instance from the services array passed to createSecurityContext.
##### Primary Context Type
The extension supports two modes, controlled by the primaryContextType configuration property:
IAS-Primary Mode (Default) - For applications adopting AMS authorization
`js
const { IdentityService, XsuaaService, XsuaaLegacyExtension, createSecurityContext } = require("@sap/xssec");
const xsuaaService = new XsuaaService(xsuaaCredentials);
const identityService = new IdentityService(identityServiceCredentials, {
xsuaaLegacyExtension: true // defaults to IAS-primary
});
// Or explicitly:
const identityService = new IdentityService(identityServiceCredentials, {
xsuaaLegacyExtension: {
primaryContextType: XsuaaLegacyExtension.IDENTITY_SERVICE_SECURITY_CONTEXT
// or: primaryContextType: "IdentityServiceSecurityContext"
}
});
const securityContext = await createSecurityContext([identityService, xsuaaService], { req });
`
In this mode, createSecurityContext for IAS user tokens returns an IdentityServiceSecurityContext with the XSUAA context embedded:
`
IdentityServiceSecurityContext
└─ xsuaaContext: XsuaaSecurityContext
`
This mode is recommended for applications that have adopted @sap/ams for authorization checks. It is possible to configure the AMS library so that in addition to the policies assigned to users in the IAS directory, additional base policies are granted based on XSUAA scopes. This allows tenants a graceful migration path where existing XSUAA scopes continue to provide equivalent authorization via base policies while the administrator is not yet finished with policy assignments in the directory.
XSUAA-Primary Mode - For applications keeping XSUAA authorization
`js
const { IdentityService, XsuaaService, XsuaaLegacyExtension, createSecurityContext } = require("@sap/xssec");
const xsuaaService = new XsuaaService(xsuaaCredentials);
const identityService = new IdentityService(identityServiceCredentials, {
xsuaaLegacyExtension: {
primaryContextType: XsuaaLegacyExtension.XSUAA_SECURITY_CONTEXT
// or: primaryContextType: "XsuaaSecurityContext"
}
});
const securityContext = await createSecurityContext([identityService, xsuaaService], { req });
`
In this mode, createSecurityContext for IAS user tokens returns an XsuaaSecurityContext with the IAS context embedded:
`
XsuaaSecurityContext
└─ iasContext: IdentityServiceSecurityContext
`
This mode allows applications to continue using existing XSUAA-based authorization checks such as securityContext.checkLocalScope without further code changes.
Applications following this approach must ensure that IAS technical user tokens are either rejected after token validation or authorized with custom logic as they would still result in an IdentityServiceSecurityContext without the expected methods for checking scopes.
##### Customizing Extension Behavior
The extension only applies to user tokens by default (not technical/client credentials tokens). You can customize this behavior by subclassing and overriding the appliesTo method:
`js
const { IdentityService, XsuaaService, XsuaaLegacyExtension, createSecurityContext } = require("@sap/xssec");
class TenantSpecificXsuaaLegacyExtension extends XsuaaLegacyExtension {
async appliesTo(iasCtx) {
// First check the default condition (user token)
if (!await super.appliesTo(iasCtx)) {
return false;
}
// Additional custom logic, e.g., tenant allowlist
const allowedTenants = ["tenant1", "tenant2", "tenant3"];
return allowedTenants.includes(iasCtx.token.appTid);
}
}
// Register the custom extension using context.extensions
const xsuaaService = new XsuaaService(xsuaaCredentials);
const identityService = new IdentityService(identityServiceCredentials, {
context: {
extensions: [
new TenantSpecificXsuaaLegacyExtension({
primaryContextType: XsuaaLegacyExtension.XSUAA_SECURITY_CONTEXT
})
]
}
});
const securityContext = await createSecurityContext([identityService, xsuaaService], { req });
`
##### Cache Configuration
The extension caches fetched XSUAA contexts to improve performance. By default, it uses an in-memory LRU cache with a maximum size of 100 entries. When accessed, cached XSUAA contexts with less than 5 minutes token lifetime are removed from the cache and a fresh token is fetched.
Default cache:
`js
const identityService = new IdentityService(identityServiceCredentials, {
xsuaaLegacyExtension: true // Uses default: LRU cache with size 100
});
`
Custom cache size:
`js
const identityService = new IdentityService(identityServiceCredentials, {
xsuaaLegacyExtension: {
cache: { size: 500 }
}
});
`
Disable caching:
`js
const identityService = new IdentityService(identityServiceCredentials, {
xsuaaLegacyExtension: {
cache: { enabled: false }
}
});
`
Custom cache implementation:
`js
const customCache = {
get: (key) => { / your implementation / },
set: (key, value) => { / your implementation / }
};
const identityService = new IdentityService(identityServiceCredentials, {
xsuaaLegacyExtension: {
cache: { impl: customCache }
}
});
`
##### Important Notes
- The extension only applies to IAS user tokens. It does not apply to:
- XSUAA tokens (returned as XsuaaSecurityContext without modification)
- IAS technical user tokens fetched via client credentials flow
- When the extension does not apply, createSecurityContext returns an IdentityServiceSecurityContext even if primaryContextType is set to XsuaaSecurityContext
- The extension supports also IAS access tokens by exchanging them for IAS id tokens first which is necessary input for requesting the XSUAA token
- Remember to pass both IdentityService and XsuaaService instances to createSecurityContext as an array
Troubleshooting
$3
#### Requests get unexpectedly declined with 401/403
Analyze the ValidationError thrown by createSecurityContext or passed on by the passport strategy to find the cause for this, e.g. by logging its message or if possible, by inspecting it in the debugger.
#### SyntaxErrors
@sap/xssec 4 uses ECMAScript 2020 syntax. This means it requires at least Node.js 18 which is the current LTS version. Version 4 does not support Node.js versions that are out of maintenance. If you try, you will encounter SyntaxErrors such as
`
SyntaxError: Unexpected token '??='
`
$3
To enable debug logging, set the environment variable DEBUG as follows when starting your application: DEBUG=xssec. Note that DEBUG=xssec:* works only for xssec 3.
:warning: Do not enable in production unless absolutely necessarily to analyze a problem. Sensitive information might be logged when debug logs are enabled, including (but not necessary limited to):
- JWT tokens that do not pass token validation (if application logs (subclasses of) TokenValidationError to console)
- Service credentials as part of the request payload that is logged to the console before any HTTP request from the library (if application performs service requests that require authentication, e.g. token fetches)
$3
Please use official SAP support channels to get support under component BC-CP-CF-SEC-LIB or Security Client Libraries.\
Before opening support tickets, please check the Troubleshooting section first.
Make sure to include the following mandatory information:
- Installed version of @sap/xssec, preferrably full output of npm list @sap/xssec`