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 Java 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
Prerequisites
Before you can use the SAP Cloud Security Services Integration libraries, you must fulfil the following requirements:
- Knowledge of Java programming and (Optional) Spring Boot framework.
- Access to an SAP BTP account and the XSUAA or Identity service.
- Familiarity with OAuth 2.0 and JWT (JSON Web Tokens).
- Java 17
- Maven 3.9.0 or later
- (Optional) Spring Boot 3.0.0 or later, Spring Security 6.0.0 or later if using the Spring integration
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:
- A user accesses the web application using a browser or mobile device which begins a new server session.
- 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.
- An access token is retrieved from the OAuth2 server in exchange for the authorization code.
- 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. Java EE / Spring Security)
2.1.1. Java EE web applications
Developers who need OAuth2 token validation and token access in their Java 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 |
java-security library. Please consider these (migration) guides:
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.
- 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 Java 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 Java 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 Java EE web.xml based servlets Integration test code snippet for Java 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.0.1</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>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 installTroubleshooting
Please refer to each library's Troubleshooting section
| Link to troubleshooting section |
|---|
| spring-security |
| spring-xsuaa |
| java-security |
| token-client |
Contributing
We welcome contributions to this project. Please see the CONTRIBUTING.md file for more details on how to contribute.
How to get support
Open a Github issue.
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.