Skip to content

Integration libraries and samples for authenticating users and clients bound to XSUAA authentication and authorization service or Identity authentication service.

License

Notifications You must be signed in to change notification settings

clnative/cloud-security-services-integration-library

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

REUSE status Maven Build main Fosstars security rating CodeQL

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
  3. Installation
  4. Troubleshooting
  5. Contributing
  6. 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.

OAuth 2.0 Authorization code flow

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:

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.

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.2.0</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

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.

About

Integration libraries and samples for authenticating users and clients bound to XSUAA authentication and authorization service or Identity authentication service.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Java 99.3%
  • Other 0.7%