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.

Table of Contents

1. Prerequisites
2. Usage
   • 2.1 Token Validation
     • 2.1.1 Jakarta EE web applications
     • 2.1.2 Spring Boot applications
   • 2.2 Token Flows
   • 2.3 Testing utilities
3. Installation
4. Troubleshooting
5. Common Pitfalls
6. Contributing
7. How to get support
8. 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 3.0.0 or later, Spring Security 6.0.0 or later if using the Spring integration

❗ 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.

Library	Usage Examples
java-security	java-security-xsuaa-usage demonstrates java-security usage with Xsuaa service java-security-identity-usage demonstrates java-security usage with Identity service sap-java-builpack-api-usage demonstrates java-security usage with SAP Java Buildpack

💡 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.

❗ For backward compatibility there is spring-xsuaa library available that supports only Xsuaa service integration, but with the next major release it will be removed.

• If you're already using spring-xsuaa in your project you should plan the time to migrate to the spring-security, see migration guide.
• If you're just setting up your project you should use spring-security library.

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

Library	Usage Examples
spring-security	spring-security-hybrid-usage demonstrates usage of xsuaa and Identity service token validation
spring-xsuaa	spring-security-basic-auth demonstrates how a user can access Rest API via basic authentication (user/password) spring-xsuaa-usage demonstrates xsuaa only setup

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

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

Library	Usage Examples
token-client	java-tokenclient-usage demonstrates usage of token client library in Jakarta EE application spring-security-xsuaa-usage demonstrates usage in Spring Boot application

2.3 Testing utilities

For authentication/authorization flow testing purposes there is java-security-test library at your disposal that can be used for unit and integration tests to test the Xsuaa or Identity service client functionality in the application. It provides a JwtGenerator to generate custom JWT tokens that work together with a pre-configured WireMock web server that stubs outgoing calls to the Identity or Xsuaa service, e.g to fetch the JWKS used to check the validity of the token signature. With this library you can test end to end all your secured endpoints or app logic that is dependant on information from the tokens.

Key features:

• Generates and signs tokens with user provided attributes
• Provides a pre-configured local authorization server that mocks communication with the BTP security services to validate self-generated tokens
• For Jakarta EE application sets up a local application server that is pre-configured with a security filter matching self-generated tokens. It can be configured to serve the servlets you want to test with mocked authorization

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

Library	Usage Examples
java-security-test	Integration test code snippet for Spring application Integration test code snippet for Jakarta EE web.xml based servlets Integration test code snippet for Jakarta EE annotation based servlets

Installation

The SAP Cloud Security Services Integration is published to maven central: https://search.maven.org/search?q=com.sap.cloud.security and is available as a Maven dependency. Add the following BOM to your dependency management in your pom.xml:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.sap.cloud.security</groupId>
            <artifactId>java-bom</artifactId>
            <version>3.5.6</version>
            <scope>import</scope>
            <type>pom</type>
        </dependency>
    </dependencies>
</dependencyManagement>

along with libraries that you intend to use e.g. java-security

<dependencies>
    <dependency>
        <groupId>com.sap.cloud.security</groupId>
        <artifactId>java-security</artifactId>
    </dependency>
</dependencies>

💡 Please refer to the Maven Dependencies section in the README.md of the library you intend to use for detailed information on which dependencies need to be added to the pom.xml.

If you intend to extend this library you can clone this repository and install this project with mvn as follows:

git clone https://github.com/SAP/cloud-security-services-integration-library
cd cloud-security-services-integration-library
mvn clean install

Troubleshooting

Please refer to each library's Troubleshooting section

Link to troubleshooting section
spring-security
spring-xsuaa
java-security
token-client

Common Pitfalls

java.lang.NoSuchMethodError and java.lang.ClassNotFoundException errors

Most common reason for these errors are out of sync client library versions. All the modules of the Security Client libraries should be always in the same version. This can be verified by executing mvn dependency:tree command.

The easiest way to manage the module versions and keep them in sync is to use the BOM

The usage of the Security Client Libraries BOM is demonstrated also in the spring-security-hybrid-usage sample

reference-instance plan not supported

The reference-instance plan is not an original plan of the Xsuaa service, therefore it is not supported by the Security Client Libraries out of the box. For a workaround please refer to the #1279 (comment)

Contributing

We welcome contributions to this project. Please see the CONTRIBUTING.md file for more details on how to contribute.

How to get support

Support is no longer provided via the Issues feature in this Github repository.

Please use SAP official support channels to get support under component BC-CP-CF-SEC-LIB or Security Client Libraries.

Before opening support tickets, please check the Troubleshooting and Common Pitfalls sections first in addition to the READMEs of the modules that you are using from this repository.

Make sure to include the following mandatory information to get a response:

• List of module(s) of this library used by your application (java-security, spring-security, spring-xsuaa etc...) and version of this library installed in your application.
  Alternative: maven dependency tree
• Auth service set-up of your application (XSUAA, IAS, XSUAA+IAS, IAS+AMS, etc.)
• For exceptions: Stack trace that includes the executed code locations of this library that lead to the exception
• For unexpected 401 / 403 response codes: relevant log output of this library with active DEBUG flag (see module READMEs for a guide how to enable it)
• Steps you have tried to fix the problem
• Reason why you believe a bug in this library is causing your problem

Unfortunately, we can NOT offer consulting via support channels.

License

Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available in the REUSE tool.