@sap/xssec/types/context/XsuaaLegacyExtension.d.ts

XS Advanced Container Security API for node.js

export = XsuaaLegacyExtension;
/**
 * XsuaaLegacyExtension
 * --------------------------------------------- *
 * When this extension is enabled, it extends {@link IdentityServiceSecurityContext}s created on that service
 * by exchanging IAS user tokens for XSUAA user tokens.
 * Important: It *never* applies to XSUAA tokens or IAS technical user tokens. In these cases, the result of createSecurityContext is unaffected by this extension!
 * Non-CAP applications with hybrid authentication must be prepared to deal with both context types depending on the incoming tokens.
 *
 * By default, it will embed the XsuaaSecurityContext created from the fetched token to the optional property `xsuaaContext`:
 *
 * IdentityServiceSecurityContext\
 *  └─ xsuaaContext: XsuaaSecurityContext
 *
 * Alternatively, it can be configured the other way around, so that `createSecurityContext` will instead return the XsuaaSecurityContext with the original
 * IdentityServiceSecurityContext embedded inside on property `iasContext`:
 *
 * XsuaaSecurityContext\
 *  └─ iasContext: IdentityServiceSecurityContext
 *
 * This is controlled by passing either the IdentityServiceSecurityContext constructor name or the XsuaaSecurityContext constructor name to `primaryContextType`.
 *
 * Use case: Migrate XSUAA-based authentication/authorization to IAS (and optionally AMS) for some tenants.
 *  - Some tenants may still log-in via XSUAA sending XSUAA tokens
 *    ==> createSecurityContext will always return XsuaaSecurityContext independent of this extension
 *  - Other tenants have migrated already to log-in via IAS sending IAS tokens
 *    ==> When this extension is enabled, createSecurityContext will return IdentityServiceSecurityContext with an embedded XsuaaSecurityContext or vice versa - depending on configuration
 *
 * Hybrid applications that have not adopted AMS, can use `primaryContextType='XsuaaSecurityContext'` to keep using their existing XSUAA-based authorization checks.\
 * Hybrid applications that have adopted AMS, can use `primaryContextType='IdentityServiceSecurityContext'` to get the IAS context as primary one and map
 * XSUAA scopes to additional base policies for users of legacy tenants, so the existing XSUAA authorizations stay in effect until they have fully migrated user roles to AMS policies.
 *
 * Conditional application:
 *  - The method {@link appliesTo} determines per created IdentityServiceSecurityContext whether the XsuaaLegacyExtension shall be applied or not.
 *  - Default implementation: applies only to regular user tokens because technical user tokens cannot be exchanged.
 *  - You can subclass or supply an override of this method to implement additional tenant allow-lists / feature flags.
 *
 * **When the extension does not apply, createSecurityContext will result in an IdentityServiceSecurityContext, even for `primaryContextType=XsuaaSecurityContext`!**
 *
 * Token fetching logic:
 *  - If the incoming IAS token is a "weak" (app2app) token (identified by `consumedApis.length > 0`), it is first exchanged for a strong JWT by `IdentityServiceSecurityContext#getIdToken`.
 *  - Then, an XSUAA JWT is requested from the given XsuaaService using the (possibly exchanged) IAS token as assertion in a `jwt bearer` flow.
 *  - An `XsuaaSecurityContext` is created from the resulting XSUAA JWT.
 *
 * Caching:
 *  - The created XsuaaSecurityContext is cached by the original IAS token's ias_iss, jti and (if present) app_tid until 5 minutes before expiration.
 *  - Default cache: LRU cache with max size 100. A custom cache (implementing { get(key), set(key, value) }) can be configured via cache configuration using the `impl` property.
 */
declare class XsuaaLegacyExtension {
    static IDENTITY_SERVICE_SECURITY_CONTEXT: string;
    static XSUAA_SECURITY_CONTEXT: string;
    /** @type {import("../util/Types").CacheConfig} */
    static DEFAULT_CACHE_CONFIG: import("../util/Types").CacheConfig;
    /**
     * Create an XsuaaLegacyExtension instance.
     *
     * @param {import("../util/Types").XsuaaLegacyExtensionConfig} [config] - Configuration for the extension.
     */
    constructor(config?: import("../util/Types").XsuaaLegacyExtensionConfig);
    /**
     * Indicates which context type should become the primary one returned to the application.
     * @type {IDENTITY_SERVICE_SECURITY_CONTEXT | XSUAA_SECURITY_CONTEXT}
     */
    primaryContextType: "IdentityServiceSecurityContext" | "XsuaaSecurityContext";
    /**
     * A cache used for caching XsuaaSecurityContexts. Can be either an external cache implementation or a per-instance LRUCache.
     * @type {import("../util/Types").Cache}
     */
    cache: import("../util/Types").Cache;
    /**
     * Extend (augment) an IAS security context with an XSUAA context, or replace it as primary depending on `primaryContextType`.
     * @param {import("./IdentityServiceSecurityContext")} iasCtx - The initial IAS-derived security context.
     * @returns {Promise<import("./IdentityServiceSecurityContext") | import("./XsuaaSecurityContext") | undefined>} The primary context (after augmentation) or undefined if no augmentation occurred.
     */
    extendSecurityContext(iasCtx: import("./IdentityServiceSecurityContext")): Promise<import("./IdentityServiceSecurityContext") | import("./XsuaaSecurityContext") | undefined>;
    /**
     * Decides whether the extension should fetch an XsuaaSecurityContext for the given IdentityServiceSecurityContext.
     * Override this for custom logic, e.g. decision per tenant.
     * Default: applies to user tokens only (`sub !== azp`).
     * @param {import("./IdentityServiceSecurityContext")} iasCtx
     * @returns {Promise<boolean>}
     */
    appliesTo(iasCtx: import("./IdentityServiceSecurityContext")): Promise<boolean>;
    /**
     * Obtain (and cache) an XsuaaSecurityContext corresponding to the provided IdentityServiceSecurityContext.
     * Handles weak-token exchange (app2app) before requesting an XSUAA JWT.
     * @param {import("./IdentityServiceSecurityContext")} iasCtx
     * @returns {Promise<import("./XsuaaSecurityContext")>}
     */
    getXsuaaContext(iasCtx: import("./IdentityServiceSecurityContext")): Promise<import("./XsuaaSecurityContext")>;
    /**
     * Returns the first XsuaaService instance from the list of services and implements error handling and debug logging.
     * @param {import("../service/Service")} services
     */
    findXsuaaService(services: import("../service/Service")): any;
    #private;
}
//# sourceMappingURL=XsuaaLegacyExtension.d.ts.map