java-tokenclient-usage

SAP BTP Java Security Client Library with XSUAA sample application

This Java backend application uses the token-client module to request access tokens from XSUAA service via the ClientCredentialsTokenFlow.

Important: This sample demonstrates backward compatibility with Apache HttpClient 4 using deprecated constructors. This approach is supported in version 4.x but will be removed in version 5.0.0.

About This Sample

This sample showcases how existing applications using Apache HttpClient 4 can continue to work with version 4.0.1+ of the library through deprecated constructors. It serves two purposes:

1. Testing: Validates that the backward compatibility layer works correctly
2. Migration Example: Shows customers how to temporarily maintain their existing Apache HttpClient 4 integration

⚠️ Deprecation Notice

The approach used in this sample relies on deprecated constructors that will be removed in version 5.0.0:

• DefaultOAuth2TokenService(CloseableHttpClient)
• DefaultOAuth2TokenKeyService(CloseableHttpClient)
• DefaultOidcConfigurationService(CloseableHttpClient)
• ApacheHttpClient4Executor class

📖 Migration Guidance

For production applications, we recommend migrating to one of these approaches:

Option 1: Use Default Java 11 HttpClient (Recommended)

// No custom HTTP client needed - works out of the box
DefaultOAuth2TokenService tokenService = new DefaultOAuth2TokenService();

Option 2: Use ApacheHttpClient4Executor (Temporary - demonstrates HttpRequestExecutor pattern)

// This shows the HttpRequestExecutor pattern the library uses internally
CloseableHttpClient apacheClient = HttpClients.createDefault();
SecurityHttpClient client = new CustomHttpClientAdapter(
    new ApacheHttpClient4Executor(apacheClient),
    apacheClient::close
);
DefaultOAuth2TokenService tokenService = new DefaultOAuth2TokenService(client);

Option 3: Custom HttpRequestExecutor (Future-Proof) See the Apache HttpClient Migration Guide for implementing custom HTTP clients with any library.

Code Highlights

The HelloTokenClientServlet.java demonstrates:

1. Custom Apache HttpClient 4 configuration with connection pooling
2. Using the deprecated constructor with @SuppressWarnings("deprecation")
3. Proper resource cleanup in the destroy() method
4. Inline migration comments showing alternative approaches

There is no authentication done, i.e. the resulting tokens are not related to a user accessing the application. Instead, the access token is issued for the bound service instance on behalf of the application itself.

Build and Deploy

1. Run maven to compile and package the sample application:

mvn clean package

2. The following steps deploy the application using either Cloud Foundry or Kyma/Kubernetes.

Deployment on Cloud Foundry

Create the XSUAA service instance

Use the cf CLI to create an XSUAA service instance based on the authentication settings in xs-security.json.

cf create-service xsuaa application xsuaa-token-client -c xs-security.json

Configure the manifest

The vars contain hosts and paths that need to be adapted.

Deploy the application

Deploy the application using the cf CLI.

cf push --vars-file ../vars.yml

⚠️ This will expect 1 GB of free memory quota.

Deployment on Kubernetes

Build and tag docker image and push to repository

Execute the following docker commands to build and push the docker image to a repository. Replace <repository>/<image> with your repository and image name.

docker build -t <repository>/<image> .
docker push <repository>/<image>

Configure the deployment.yml

In deployment.yml replace the placeholder <YOUR IMAGE TAG> with the image tag created in the previous step.

⚠️ If you are using a private repository, you also need to provide the image pull secret in the deployment.yml.

Deploy the application

Deploy the application using kubectl.

kubectl apply -f k8s/deployment.yml

3. Access the application

The sample application provides a single HTTP endpoint:

• /hello-token-client - accessible without authentication

access Cloud Foundry deployment

You can access the application at:

https://java-tokenclient-usage-<<ID>>.<<LANDSCAPE_APPS_DOMAIN>>/hello-token-client

access Kubernetes deployment

You can access the application at:

https://java-tokenclient-api.<<K8S DOMAIN>>/java-tokenclient-usage/hello-token-client \

You should see something like this:

Access-Token: eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8v...
Access-Token-Payload: {"jti":"abcdefghijklmnopqrstuvwxyz123456","ext_attr":{"enhancer":"XSUAA","subaccountid":"...
Expired-At: 2024-10-17T04:31:46.397Z

4. Cleanup

If you no longer need the sample application, you can free up resources using the cf CLI or the Kubernetes CLI.

Cleanup commands for Cloud Foundry

cf delete -f java-tokenclient-usage
cf delete-service -f xsuaa-token-client

Cleanup command for Kubernetes

 kubectl delete -f k8s/deployment.yml