SAP BTP User Management Microservice

Description

This sample code aims to help SAP developers (customers or partners) to develop secure applications on SAP Business Technology Platform using the Authorization and Trust Management Service (XSUAA) APIs from Cloud Foundry. The code is developed using the SAP Cloud Application Programming Model (CAP) NodeJS framework and implements a microservice to manage business applications' users and their respective authorizations with a simple SAP Fiori Elements UI for testing.

IMPORTANT NOTE: please be aware that the code in this repository is targeted to experienced CAP developers and is provided as is, serving exclusively as a reference for further developments

Solution Architecture

Requirements

SAP Business Technology Platform subaccount (productive or trial) with Cloud Foundry environment enabled
SAP Business Application Studio entitlement / subscription (Full Stack Cloud Application Dev Space)
SAP Workzone Standard (formerly SAP Launchpad Service) entitlement / subscription

Download and Installation

Clone the Project Repo

Access your SAP Business Application Studio full-stack cloud development Dev Space
Open a new terminal (if not yet opened): Terminal > New Terminal
From the default projects folder, create the project directory:

NOTE: if you have not set the projects folder to become your current workspace in BAS your terminal might end-up in the user folder. So, do cd projects before executing the command below.

mkdir user-mngr

Clone this repo into the recently created directory:

git clone https://github.com/SAP-samples/btp-user-management-microservice.git user-mngr

Create the Required Service Instances

cd user-mngr && cf login

Create the Destination service:

cf create-service destination lite dest-svc

Create the XSUAA service (application plan):

cf create-service xsuaa application xsuaa-svc -c xs-security.json

Create the XSUAA service (apiaccess plan):

cf create-service xsuaa apiaccess xsuaa-api

Create the XSUAA service (apiaccess plan) service key:

cf create-service-key xsuaa-api xsuaa-api-sk

Bind Destination and XSUAA (application) Services to the CAP Project

Temporarily rename the .env file to default.env:

mv .env default.env

On the left-hand pane of BAS click on the Cloud Foundry icon (small lightbulb)
Expand the Services node
Right-click the dest-svc (destination) item
Select Bind a service to a locally run application
From the directories list select the user-mngr directory and click OK
Repeat steps 4 to 6 for the xsuaa-svc (xsuaa) item
Go back to the Explorer, open the recently created .env file and adjust its contents to become a JSON object like demonstrated below:

Rename the .env file to default-env.json:

mv .env default-env.json

HINT: you can open the recently renamed file (default-env.json) and format the JSON content with ALT+Shift+F for better visualization.

Rename the default.env file back to .env

mv default.env .env

Install Project Dependencies

Setup npm registry:

npm config set registry https://registry.npmjs.org/

NOTE: this is important to avoid issues when running npm clean-install in the MTA build process.

Install service dependencies:

npm install

Install UI dependencies:

cd app/user-mngr && npm install && cd ../..

Create the Destination to the XSUAA API

Display the XSUAA (apiaaccess plan) service key:

cf service-key xsuaa-api xsuaa-api-sk

Take note (copy) the following service key properties:

apiurl
clientid
clientsecret
url

Open the BTP cockpit and access your subaccount (same subaccount used to start the BAS Dev Space)
On the left-hand pane expand the Connectivity node
Click on Destinations
Click on New Destination
Fill-in the required information like demonstrated below:

Click Save

Assign the Application's Role Collections to Your User

Open the BTP cockpit and access your subaccount (same subaccount used to start the BAS Dev Space)
On the left-hand pane expand the Security node and click on Users
In the users list on the right, click on your user

HINT: if the users list is to long and you find it difficult to locate your user, you can use the search box at the top.

In the user's details at the right, click on Assign Role Collection
Find the role collections starting with GenericApp
Check both role collections
Click on Assign Role Collection

Test Application Locally

Start the application in BAS:

cds watch

CTRL+Click the http://localhost:4004 link in the terminal to open the service home page in a new tab

NOTE: you must allow pop-ups for your BAS URL in your browser in order to get the new tab to be properly opened.

Click on the User link
When prompted to Sign in type john as the Username and click Sign in
You should see the information from your user in JSON format like demonstrated below:

Click on the other two links (IdP and Authorization) to check whether they are working fine as well
In the Terminal press CTRL+C to terminate the service

Deploy Application to Cloud Foundry

From the Explorer open the mta.yaml file
Search for the [your BTP subdomain] string and replace it with the subdomain of your BTP subaccont

HINT: you can find the subdomain name in the Overview page of your subaccount in the BTP cockpit

From the Explorer open the app/user-mngr/webapp/manifest.json file and do the same search & replace procedure as in the previous step
In the Explorer right-click on the mta.yaml file and select Build MTA Project
When the build process finishes, an mta_archives directory will appear in the Explorer
Expand the mta_archives directory
Right-click the user-mngr_1.0.0.mtar and select Deploy MTA Archive

Test the Application in Cloud Foundry

On the left-hand pane of your BTP cockpit, click on HTML5 applications

NOTE: the applications will be listed only if you have at least SAP Workzone Standard (formerly SAP Launchpad Service) enabled in your subaccount (please, see the Requirements section).

Click on the usermngr link
The Fiori Elements UI of the service will open in a new tab
You can use this UI to fully test the microservice: create, update and/or delete users of your application (users who have the GenericApp role collections assigned)

FINAL NOTE: having the application deployed to the HTML5 apps repository you can optionally add it to a SAP Workzone Standard site.

Code Details

You can find a detailed explanaton about the code of this project in this blog post.

Known Issues

No known issues.

How to obtain support

Create an issue in this repository if you find a bug or have questions about the content.

For additional support, ask a question in SAP Community.

Contributing

If you wish to contribute code, offer fixes or improvements, please send a pull request. Due to legal reasons, contributors will be asked to accept a DCO when they create the first pull request to this project. This happens in an automated fashion during the submission process. SAP uses the standard DCO text of the Linux Foundation.

SAP-samples/btp-user-management-microservice