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.
Before you can use the SAP Cloud Security Services Integration libraries, you must fulfil the following requirements:
❗ For Java 8 and 11 please use 2.x release of this library.
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:
OAuth2 resource servers (as the one in step 4) require libraries for validating access tokens.
Key features:
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:
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.
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 |
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:
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 |
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:
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 |
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.3</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
Please refer to each library's Troubleshooting section
Link to troubleshooting section |
---|
spring-security |
spring-xsuaa |
java-security |
token-client |
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
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 https://github.com/SAP/cloud-security-services-integration-library/issues/1279#issuecomment-1735542987
We welcome contributions to this project. Please see the CONTRIBUTING.md file for more details on how to contribute.
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:
Unfortunately, we can NOT offer consulting via support channels.
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.