Testing REST APIs in XSA Applications Without UI Layer

REST APIs are extremely useful for accessing and modifying data within XSA Multi-Target Applications. When it comes to checking whether the API you’ve designed is working properly or not, things becomes a little difficult if you are not familiar with web security protocols. In this blog, I am going to briefly describe OAuth 2.0, the security protocol used by XSA for user authentication and authorization (UAA), and cover details on how you can make HTTP requests to different modules within an XSA application.

The steps described in this blog are needed only if the XSA application has user authentication configured in the application router. If not, you can simply send an HTTP request from any source and you should be allowed access without any authorization checks. Also, if you are only dealing with HTTP GET requests, you can use any browser to test the API. When you open the URL for the API, you should be redirected to the UAA service which logs you in and takes care of authorization on its own afterwards.

OAuth 2.0

OAuth2 is the security protocol used by XSA. It allows scope-based access to resources as opposed to basic authentication which allows access to all resources for all users. In scope-based authorization, you must have certain scopes granted to you for you to access certain resources. OAuth2 is an industry standard for authorization. For more detailed information, you can visit this link.

Let’s start with understanding the three major roles involved in OAuth2: user, external client, and the (XSA) application which contains the authentication server and protected resources. A user is a person trying to access resources relevant to them from the application using an external client. The external client is registered on the application’s authentication server so that it can request access to those resources. The authentication server handles incoming requests from external clients and responds with appropriate authorization grants and access tokens. These tokens are then used by the external clients to access the protected resources.

Four major grant types are used to request an access token, namely Authorization Code, Implicit, Password, and Client Credentials. The one most relevant to this blog is Client Credentials which only involves the external client and the application. How it works is that you send a request to the authentication server with client credentials (client id and client secret), which you receive when you register your client with the server, and requested scopes. The server responds back with an access token which includes the requested scopes. The client can then use this access token to request resources from the application. The diagram below outlines the Client Credentials workflow.

Postman

Postman is a tool that you can use to test HTTP communication. It allows you to store session variables, cookies, and authorization information from your HTTP requests and use them in subsequent requests – pretty similar to how a web browser works.

I am going to demonstrate how to use Postman to connect to an XSA application and send HTTP requests to REST APIs contained in that application. First, you need to obtain a valid access token from the UAA service in the XSA application. Open the Postman desktop app and create a new basic request. You should see an empty request page like the one in the image below.

Under authorization, change TYPE to Oauth 2.0. In the panel that shows up to the right, click on Get New Access Token. This should open the GET NEW ACCESS TOKEN form. Change Grant Type to Client Credentials. The updated form should look like the following.

You need to fill out all information required in this form to obtain a valid access token. For token name, you can put anything you wish. To get the rest of the information (client id, etc.), open the command prompt from Windows and log in to XSA using xs login. Make sure you are in the development space. Execute xs env <app> where <app> is the name of the application router module. This should output all environment variables for services and applications bound to the application router. The one we are interested in is the instance of the xsuaa service which is responsible for user authorization. The output for this should look similar to the image shown below.

The Client ID and Client Secret should be included in the environment variables. Copy and paste these into the Postman form. For Access Token URL, use the URL included in the environment variables and append “/oauth/token” to the end of it. Scope is optional, if you provide none, you would be assigned uaa.resource by default. Click Request Token. Postman should then show you the access token it receives (as a base64 string) along with the scopes granted as shown below. Click Use Token before closing the dialog.

Congratulations! You have successfully obtained the access token which you can now use to access resources from the XSA application!! Keep in mind that when you are accessing resources using this method, you should use the direct URLs for those resources as opposed to the URL of the application router which redirects you to the requested resource. Also, the access token expires after a certain time period, so you would need to request a new token from time to time.

To demonstrate how you would use the access token in a subsequent request, I am going to send a POST request to a Python module within my XSA application.  In Postman, change the request type to POST. Enter the request URL to be https://core-py.hanapm.local.com:30033/addProduct. Make sure the Access Token in filled in. The request should look as follows at this point.

Under the Body tab, choose raw from the radio buttons. Select JSON (application/json) from the dropdown list that appears.

Copy and paste the following text.

{

    "productID": "22335142",

    "category": "Notebooks",

    "price": "45.22"

}

You are now ready to send the request. Click the blue Send button in the top right. The response should be as follows.

Python

You can also obtain an access token programmatically and send HTTP requests accordingly. I am going to demonstrate this using Python3. The following code snippet shows how to obtain an access token using the OAuth2 Client Credentials workflow. First, you create a client using your Client ID, followed by a client session using the OAuth2Session object. Eventually, you can call the fetch_token function on your session object to obtain the access token. Just a note that I have turned SSL verification off (verify=False) since I am using local self-signed certificates for my XSA application.

from oauthlib.oauth2 import BackendApplicationClient

from requests_oauthlib import OAuth2Session

CLIENT_ID = '' #your client id goes here

CLIENT_SECRET = '' #your client secret goes here

TOKEN_URL = 'https://uaa-server.hanapm.local.com:30033/uaa-security/oauth/token' #this would be different for you

client = BackendApplicationClient(client_id=CLIENT_ID)

oauth = OAuth2Session(client=client)

token = oauth.fetch_token(token_url=TOKEN_URL, client_id=CLIENT_ID, client_secret=CLIENT_SECRET, verify=False)

That’s it! It’s really that simple!! For an example of how you can use the access token in subsequent requests, I am going to send the same POST request from the Postman section above but using Python this time. The code would be as follows.

import requests

import json

access_token = #your access token goes here

URL = 'https://core-py.hanapm.local.com:30033/addProduct'

headers = {'Authorization': 'Bearer %s' % access_token,

           'Content-Type': 'application/json'}

body = json.dumps({'productID': '88997785',

                   'category': 'Notebooks',

                   'price': '88.98'})

r = requests.post(url, headers=headers, data=body, verify=False)

The response should be (‘88997785’, ‘Notebooks’, 88.98, ‘Product 88997785 inserted successfully’)!

CURL

The last tool I am going to talk about is CURL, which you can use from a terminal or command prompt to send HTTP requests. If you are using CURL just for testing APIs, you do not need to worry about obtaining the OAuth2 access token yourself. You can request that token directly from the XS command line interface using the xs oauth-token command. This should return a valid access token with all the scopes you need. You can use this token in the header of your subsequent CURL requests to access resources in your XSA application. The image below demonstrates how this works within the command prompt.

The body.txt and headers.txt files should look as follows.

Closing

Hopefully this blog has helped you better understand how to work with user authorization in XSA applications. If you still have any questions with regards to obtaining an access token and using it, feel free to comment below!