xsuaa and Approuter – The great story of twins


There are things known and things unknown and in between are the doors.

-Jim Morrison (Singer)

When we are working on BTP, most probably one of the initial service we lay our hands on is the XSUAA service as all security on BTP is controlled by and revolves around xsuaa. Approuter is a Node.js front end proxy application from SAP. It is available on npm and if you go through the npm documentation, you will soon realize the amount of work approuter does. It is simply amazing. One of the major aspect of approuter is it inherently integrates with xsuaa service and takes care of security for micro service based applications. Without approuter, building this on own will be a very tedious task. So xsuaa and Approuter is the perfect recipe for easily building secure applications on BTP. In this, i will share some of my thoughts and experiences of working with these twins.

To go to details, xsuaa is the OAuth server implementation from SAP. To use xsuaa, create a service instance and create a service key to get the credentials. Very simple right and how many times we did this step 🙂 Note three important things from the service key

 "clientid": "sb-my-app!t97041" "clientsecret": "8B5jpXXXXXXXa9na+bVTh4C8k=" "url": "https://5271f3betrial.authentication.us10.hana.ondemand.com"

you can do a basic test of your XSUAA server. Just access the xsuaa url in the browser and after logging in you will be getting a page below

Now add /config?action=who&details=true to the end of url to see your login details

Now let us dig little deep and see the high level flow of steps that happens internally between Approuter and xsuaa:

STEP1: Approuter sends authorization code request to xsuaa

Approuter initiates an authorization code grant OAuth flow and send GET request to xsuaa authorize endpoint (/oauth/authorize/) below.

GET https://5271f3betrial.authentication.us10.hana.ondemand.com/oauth/authorize?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&response_type=code e.g. https://5271f3betrial.authentication.us10.hana.ondemand.com/oauth/authorize?client_id=sb-my-app!t97041&redirect_uri=http://localhost:9000/oauth/callback&response_type=code

STEP2: xsuaa redirects user to IDP for login

xsuaa will in turn redirect user to identity provider for authentication. By default BTP trial accounts have SAP IDP as the identity provider.

STEP3: xsuaa send authorization code back to Approuter

In response you will receive the authorization code. you can get the code using browser inspector tools as below.

STEP4: Approuter exchange authorization code for JWT token

Approuter sends a post request to xsuaa token endpoint (/oauth/token) to exchange the authorization code for a JWT token. You can simulate it using postman.

POST https://5271f3betrial.authentication.us10.hana.ondemand.com/oauth/token Headers
Accept: application/json
Content-Type: application/x-www-form-urlencoded client_id=sb-my-app!t97041
client_secret=8B5jpaGXXXXXXX9na+bVTh4C8k=
redirect_uri=http://localhost:9000/oauth/callback
code=<Code from step3>
grant_type=authorization_code

In response, you will get access token from xsuaa

STEP5: Approuter calls backend microservices

The JWT token received in step 4 will have the the roles and scopes that are assigned to the user. Approuter passes this JWT to the backend microservice api calls. Microservice APIs validate the JWT and does the scope checks.

BTP xsuaa service and Approuter are kind of twins. One can not exist alone or at least will not have much meaning with out the other. Working with xsuaa with out using Approuter is very tedious. Working with Approuter without xsuaa service has no meaning.

Some things i am thinking will follow next are about xsuaa multitenancy, how xsuaa works together with other BTP services. Also below are few interesting reads as well on this topic.

Demystifying XSUAA in SAP Cloud Foundry by Jeffrey Groneberg

How To Update XSUAA Service Instance to Accept Multiple Redirect URIs by Radu Constantin Simen

Please feel free to let me know your feedback if i errored out some where in my thought or understanding. Please do share your comments.