Technical Articles

ARJUN TOSHNIWAL

December 13, 2021 6 minute read

Demystifying Approuter , XSUAA and IDP in BTP CF Environment

This blog is continuation of the previous blog , wherein we had provided an introduction to an Approuter and XSUAA components in BTP .

Refer : https://blogs.sap.com/2021/12/11/approuter-and-xsuaa/

Here we will study in depth how a request to the application deployed in BTP CF environment gets served to the user , and also what roles are played by Approuter , XSUAA and IDP while serving the response .

The basic flow can be summarised from the below flow diagram :

Step1: Request to an Approuter

A browser sends a request to an application(as approuter serves as an entry point for all the application deployed in BTP ,thus a request to an application triggers a request to the approuter).

An approuter will consider this as an initial unauthenticated request since there is no session-id included in the request (basically a cookie called JSESSIONID will be absent from the initial request). This unauthenticated request is forwarded to the Authorisation Server (XSUAA) . This redirection to the XSUAA server is a client side redirect , meaning that the approuter will return a tiny html page containing details about url of authorisation server , page for which the request was sent etc etc

This index.html returned by the approuter looks likes this:

<html>
   <head>
      <linkrel="shortcut icon"href="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"/>
      <script>
         document.cookie = "fragmentAfterLogin=" + encodeURIComponent(location.hash) + ";path=/";
         document.cookie = "locationAfterLogin=" + encodeURIComponent(location.href.split('#')[0].split(location.host)[1]) + ";path=/";
         document.cookie = "signature=<signature>;path=/";
         location = "<xsuaa_url>/oauth/authorize?response_type=code&client_id=<xsuaa_clientid>&redirect_uri=<app_url>/login/callback"
      </script>
   </head>
</html>

This index,html page contains information about:

xsuaa server
A path or a file to which it should redirect to after login
An internal reference to the page (followed by ‘#’)

Example :
URL : <app_url>/home.html#demo
fragmentAfterLogin = /demo
locationAfterLogin = /home.html
location = <xsuaa_url>/oauth/authorize?response_type=code&client_id=<xsuaa_clientid>&redirect_uri=<app_url>/login/callback

Note:
The location redirect attribute present in the script tag of index.html page, triggers a client side redirect to the xsuaa server where URL for the xsuaa i.e the authorisation server is taken from the environment variable configuration present in the approuter.

Thus the initial request response can be summarised as:
Request : <approuter_url>
HTTP Response Code : 302
Redirection : <xsuaa_url>/oauth/authorize?response_type=code&client_id=<xsuaa_clientid>&redirect_uri=<route_of_application>/login/callback

Step2: Request to Authorisation Server

The browser will execute the script tag of the returned html page and hence will trigger a request to xsuaa (authorisation server) . This request does not contain a JWT token hence , the xsuaa server will redirect the request to xsuaa login url.

Request : <xsuaa_url>/oauth/authorize?response_type=code&client_id=<xsuaa_clientid>&redirect_uri=<route_of_application>/login/callback
HTTP Response Code : 302
Location Response Header : /login

Step3 : Request to Authorisation Server Login page

Since its an unauthenticated request , a login request to authorisation server(xsuaa) will trigger a client side redirect to the IDP (here it is SAP IDP)

The url of the redirection will be obtained from the tiny html page returned by xsuaa server which looks like this:

Note:

If we inspect this html page, it can been in the html code it contains the script for client side redirect hence it would get automatically redirected to sap idp.

Request : <xsuaa_url>/login
HTTP Status Code : 200
The redirection url is :
https://accounts.sap.com/oauth2/authorize?client_id=<client_id>&response_type=code&redirect_uri=<xsuaa_url>/login/callback/<origin_key>&state=<state>&scope=openid&nonce=<nonce>

for trial accounts origin key is sap.default and can be found from:

Note:

This redirection url is dependent upon the trust configuration done between xsuaa server (authorisation server) and the idp (here it is sap idp):

Step 4 : SAML request to SAP IDP

Thus once the authorisation server has validated the clientid , it will trigger a request for SAML SSO.

Request :https://accounts.sap.com/oauth2/authorize?client_id=<client_id>&response_type=code&redirect_uri=<xsuaa_url>/login/callback/<origin_key>&state=<state>&scope=openid&nonce=<nonce>
HTTP Status Code : 302
Location Response Header :https://accounts.sap.com/saml2/idp/sso?sp=<sp_name>&RelayState=client_id=<client_id>&response_type=code&redirect_uri=<xsuaa_url>/login/callback/<origin_key>&state=<state>&scope=openid&nonce=<nonce>

where sp_name for trial account in Europe Frankfurt region is : uaa-cf-eu10

Step5 : SAML SSO

A SAML SSO request , returns a login form wherein the resource owner (user) will enter his credentials and submit it to the IDP(here it is Gigya).Once the authentication is successful the IDP would return back the saml bearer assertion token to the xsuaa server.

Note:

Gigya is an identity management platform (acquired by SAP in 2017).

Request :https://accounts.sap.com/saml2/idp/sso?sp=<sp_name>&RelayState=client_id=<client_id>&response_type=code&redirect_uri=<xsuaa_url>/login/callback/<origin_key>&state=<state_id>&scope=openid&nonce=<nonce>
HTTP Status Code :200
Response :https://fidm.<region>.gigya.com/saml/v2.0/<code>/idp/sso

Thus it can be summarised as,”the service provider (xsuaa server) will redirect the request to identity provider to do authentication on its behalf”.

Also there are literally lot of request redirection that takes place before the login page is displayed to the user.

Step6 : IDP and SAML Assertion

The IDP validates the users and returns the SAML Assertion token, containing information about the ACS also known as Assertion Consumer Service endpoint where the identity provider will redirect to with its authentication response

For Trial Account it was :

https://accounts.sap.com/saml2/idp/acs

This SAML assertion is then passed to the XSUAA server (actually its an ACS endpoint on XSUAA server) which will then process the saml assertions and generate an authorisation code.

Generically speaking , ACS is an endpoint on the service provider to which IDP will redirect to with SAML Response(also know as SAML Assertions). This SAML response is then processed by the ACS which redirects the user back to the endpoint set in the relaystate of the IDP)

Note:

Identity providers authenticate principals and return identity information in the form of SAML Assertions.

Request : https://accounts.sap.com/saml2/idp/acs
HTTP Status Code :200
Response:  <xsuaa_url>/login/callback/<origin_key>?code=<code>&state=<state>

Step 7: Redirection to XSUAA

This access token with state information is then passed to the XSUAA server to generate the authorisation code

Request :<xsuaa_url>/login/callback/<origin_key>?code=<code>&state=<state>
HTTP Status Code : 302
Response :<xsuaa_url>/oauth/authorize?response_type=code&client_id=<client_id>&redirect_uri=<app_url>/login/callback

Step 8: Authorisation Code Generation

In this step xsuaa server generates the authorisation code and sends it back to the client

Request : <xsuaa_url>/oauth/authorize?response_type=code&client_id=<xsuaa_clientid>&redirect_uri=<route_of_application>/login/callback
HTTP Status Code : 302
Response :https://<app_url>/login/callback?code=<authorisation_code>

Step 9: JWT Token creation at Approuter

The approuter takes this authorisation code and asks for the JWT from the XSUAA server. Thus XSUAA server validates the authorisation code and generate a JWT token which is then stored by the approuter to serve all the future http request calls.The approuter then triggers a http request to a resource/webapplication along with this JWT token , which gets validated by the resource server before returning the response back to the User-Agent(Browser)

Note:

This validation is possible due the service binding done to the application with xsuaa server ,which contains the verification key in the environment variable.

FAQs:

How to obtain sap idp(identity provider) metadata?https://<tenant_name>.accounts.ondemand.com/saml2/metadata

How to obtain sap sp(service provider) metadata?

SAML metadata endpoint of the UAA server differs depending upon trial or enterprise version:-

Trial Account:
https://<tenant_name>.authentication.<region>.hana.ondemand.com/saml/metadata

For Enterprise:
https://<accountid>.authentication.hana.ondemand.com/oauth/token?grant_type=client_credentials

I hope you enjoyed this blog , wherein we learnt in great detail how a request to the applications deployed in BTP gets served to the user securely.

3 Comments

You must be Logged on to comment or reply to a post.

Vladimír Balko

December 13, 2021 at 9:46 pm

Thank you for nice explanation about that authorization process.

Would you mind to describe how to debug or troubleshoot that process? Tools, actions, best practices how to find whats wrong when I get 401 or some other error because I dont have active session?

Pramod Kumar

February 27, 2022 at 10:40 pm

Nice blog, that helped me to understand fundamentals that how the app call authenticated!!

Thanks,

Pramod

Jorg Thuijls

April 17, 2022 at 5:22 am

Very interesting, thanks for the write up

Technical Articles

Demystifying Approuter , XSUAA and IDP in BTP CF Environment

Step1: Request to an Approuter

Step2: Request to Authorisation Server

Step3 : Request to Authorisation Server Login page

Step 4 : SAML request to SAP IDP

Step5 : SAML SSO

Step6 : IDP and SAML Assertion

Step 7: Redirection to XSUAA

Step 8: Authorisation Code Generation

Step 9: JWT Token creation at Approuter

Assigned Tags