SAP BTP Security Services Integration Libraries

This repository offers a comprehensive set of libraries designed to simplify the integration of SAP Business Technology Platform (SAP BTP) security services (XSUAA and Identity Services). Tailored to support Jakarta EE and Spring Boot applications running on Cloud Foundry or Kubernetes environments. The libraries focus on streamlining OAuth 2.0 access token validation for tokens issued by XSUAA and Identity Services. In addition, it offers a token-client library to easily fetch tokens without cumbersome setup for http requests. Finally, it offers testing utility that mocks Xsuaa and Identity service behaviour and makes it easy to write integration and unit tests.

:mega: What's New in 4.0.1

Major version upgrade with breaking changes - upgraded to Spring Boot 4.x and Jakarta EE 10!

:white_check_mark: Migrating from 3.x? We've got you covered: - Spring Boot 4.x users: Update to resourceserver-security-spring-boot-starter 4.0.1 - Spring Boot 3.x users: Use new resourceserver-security-spring-boot-3-starter 4.0.1 - same features, full compatibility - spring-xsuaa users: Module removed - follow our migration guide

Key Changes: - :rocket: Spring Boot 4.0.3, Spring Framework 7.0.5, Spring Security 7.0.3 - :package: New Spring Boot 3.x compatibility layer via legacy modules - :zap: Token-client now uses Java 11 HttpClient by default (Apache HttpClient support via custom integration) - :x: Removed deprecated modules: spring-xsuaa, spring-xsuaa-test, spring-xsuaa-it, spring-security-compatibility

See CHANGELOG.md for complete details.

Table of Contents

1. What's New in 4.0.1
2. Prerequisites
3. Usage
4. 2.1 Token Validation
   • 2.1.1 Jakarta EE web applications
   • 2.1.2 Spring Boot applications
5. 2.2 Token Flows
6. 2.3 Testing utilities
7. 2.4 Token Exchange for Hybrid Authentication
   • 2.4.1 Jakarta Example
   • 2.4.2 Spring Boot Example
8. Installation
9. Migration Guide
10. Troubleshooting
11. Common Pitfalls
12. Contributing
13. How to get support
14. License

Prerequisites

Before you can use the SAP Cloud Security Services Integration libraries, you must fulfil the following requirements:

1. Knowledge of Java programming and (Optional) Spring Boot framework.
2. Access to an SAP BTP account and the XSUAA or Identity service.
3. Familiarity with OAuth 2.0 and JWT (JSON Web Tokens).
4. Java 17
5. Maven 3.9.0 or later
6. (Optional) Spring Boot 4.0.1 or later, Spring Security 7.0.0 or later if using the Spring integration
7. Spring Boot 3.x users: Use the legacy compatibility modules (see Spring Boot 3.x Compatibility)

:exclamation: For Java 8 and 11 please use 2.x release of this library.

Usage

Typical web applications consist of a gateway server serving HTML content to the user client and one or more servers behind the gateway providing REST APIs. The gateway server acts as OAuth2 client executing an OAuth2 Authorization Code Flow to retrieve an access token when a new user client session is created. Requests from the user client are correlated with a session id on the gateway server which appends the access token to subsequent requests and forwards them to the REST APIs. The session flow looks as follows: 1. A user accesses the web application using a browser or mobile device which begins a new server session. 2. The web application redirects the user client to the OAuth2 server for authentication. In typical SAP Business Technology Platform scenarios, this is handled by an application router. Upon authentication, the web application receives an authorization code from the user client issued by the OAuth2 server. 3. An access token is retrieved from the OAuth2 server in exchange for the authorization code. 4. The web application uses the access token to access resources on an OAuth2 resource server via a REST API. The OAuth2 resource server validates the token using online or offline validation to restrict access to the API.

OAuth2 resource servers (as the one in step 4) require libraries for validating access tokens.

2.1. Token Validation

Key features: * Automatic OAuth2 service configuration based on SAP BTP service bindings found in the environment * OAuth2 Token Validation based on these service configurations * Easy access to principal and token claims within request handlers * Automatic or sample integrations for common web application frameworks (i.e. Jakarta EE / Spring Security)

2.1.1. Jakarta EE web applications

Developers who need OAuth2 token validation and token access in their Jakarta EE applications can utilize the java-security library. This library simplifies the process of acquiring token information such as principal and audiences from the security context and takes over token validation for tokens issued by Xsuaa or Identity services. This library is also integrated in SAP Java Buildpack.

In the table below you'll find links to detailed information.

java-security-usage-ias demonstrates java-security usage with Identity service

[sap-java-buildpack-api-usage](/samples/sap-java-buildpack-api-usage) demonstrates java-security usage with SAP Java Buildpack |

:bulb: Changes with SAP Java Buildpack 1.26.0 The former SAP Java Buildpack versions have used deprecated (Spring) Security libraries and had to be updated. As of version 1.26.0 SAP Java Buildpack uses the java-security library. Please consider these (migration) guides:

• MANDATORY: clean-up deprecated dependencies
• OPTIONAL: Leverage new APIs and features

2.1.2. Spring Boot web applications

Developers seeking OAuth2 token validation and access to token information for their Spring Boot applications can benefit from the spring-security library. This library streamlines the process of handling token validation for tokens issued by Xsuaa or Identity services and obtaining token details, such as principal and audiences from the security context.

Spring Boot Version Support

:bulb: New in 4.0.1: The Spring Boot 3 compatible starter provides a seamless migration path for applications that cannot immediately upgrade to Spring Boot 4.x. Both starters provide the same features and APIs.

Spring Boot 3.x Compatibility

If your application uses Spring Boot 3.x and you cannot immediately upgrade to Spring Boot 4.x:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
    <groupId>com.sap.cloud.security</groupId>
    <artifactId>resourceserver-security-spring-boot-3-starter</artifactId>
    <version>4.0.8</version>
</dependency>

See spring-security-3 README for complete documentation.

Migrating from spring-xsuaa

:warning: Deprecated: The spring-xsuaa module has been removed in version 4.0.1.

If you're using the deprecated spring-xsuaa module: - Migrate to spring-security (Spring Boot 4.x) or spring-security-3 (Spring Boot 3.x) - Follow the migration guide for step-by-step instructions

In the table below you'll find links to detailed information.

2.2. Token Flows for token retrievals

Java applications that require access tokens (JWT) from Xsuaa or Identity services can utilize the Token Flows API from the token-client library, to fetch JWT tokens for their clients (applications) or users.

Typical use cases: * technical user / system tokens for service to service communication * user token exchange for principal propagation in service to service communication

:bulb: New in 4.0.1: Token-client now uses Java 11 HttpClient by default. Spring-based implementations have been moved to token-client-spring. For custom HTTP client implementations (Apache HttpClient 4.x/5.x), see CUSTOM_HTTPCLIENT.md.

In the table below you'll find links to detailed information.

spring-security-hybrid-usage demonstrates usage in Spring Boot application | | token-client-spring | Spring-based implementations of OAuth2 token services for Spring Boot 4.x. Required if you use XsuaaOAuth2TokenService, SpringOAuth2TokenKeyService, or SpringOidcConfigurationService.