Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sap-samples/btp-user-management-microservice

Sample CAP microservice to manage business applications' users and their respective authorizations.
https://github.com/sap-samples/btp-user-management-microservice

authentication authorization btp cloud-application-programming-model cloud-foundry security xsuaa

Last synced: about 2 months ago
JSON representation

Sample CAP microservice to manage business applications' users and their respective authorizations.

Host: GitHub
URL: https://github.com/sap-samples/btp-user-management-microservice
Owner: SAP-samples
License: apache-2.0
Created: 2022-09-14T18:27:21.000Z (over 2 years ago)
Default Branch: main
Last Pushed: 2023-08-22T21:08:49.000Z (over 1 year ago)
Last Synced: 2023-08-23T01:10:02.515Z (over 1 year ago)
Topics: authentication, authorization, btp, cloud-application-programming-model, cloud-foundry, security, xsuaa
Language: JavaScript
Size: 312 KB
Stars: 9
Watchers: 7
Forks: 3
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# SAP BTP User Management Microservice
[![License: Apache2](https://img.shields.io/badge/License-Apache2-green.svg)](https://opensource.org/licenses/Apache-2.0)
[![REUSE status](https://api.reuse.software/badge/github.com/SAP-samples/btp-user-management-microservice)](https://api.reuse.software/info/github.com/SAP-samples/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
![BTP User Management Microservice Architecture](https://i.imgur.com/iaa5IXO.png "BTP User Management Microservice")

## 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
1. Access your **SAP Business Application Studio** full-stack cloud development **Dev Space**
2. Open a new terminal (if not yet opened): **Terminal** > **New Terminal**
3. 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
```
4. 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
1. Login to **Cloud Foundry**:
```
cd user-mngr && cf login
```
2. Create the **Destination** service:
```
cf create-service destination lite dest-svc
```
3. Create the **XSUAA** service (**application plan**):
```
cf create-service xsuaa application xsuaa-svc -c xs-security.json
```
4. Create the **XSUAA** service (**apiaccess plan**):
```
cf create-service xsuaa apiaccess xsuaa-api
```
5. 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
1. Temporarily rename the **.env** file to **default.env**:
```
mv .env default.env
```
2. On the **left-hand pane** of BAS click on the **Cloud Foundry** icon (small lightbulb)
3. Expand the **Services** node
4. Right-click the **dest-svc (destination)** item
5. Select **Bind a service to a locally run application**
6. From the **directories list** select the **user-mngr** directory and click **OK**
7. Repeat steps 4 to 6 for the **xsuaa-svc (xsuaa)** item
8. Go back to the **Explorer**, open the **recently created .env** file and adjust its contents to become a JSON object like demonstrated below:

VCAP_SERVICES JSON object

9. 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.
10. Rename the **default.env** file back to **.env**
```
mv default.env .env
```

### Install Project Dependencies
1. 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.
2. Install **service dependencies**:
```
npm install
```
3. Install **UI dependencies**:
```
cd app/user-mngr && npm install && cd ../..
```

### Create the Destination to the XSUAA API
1. Display the **XSUAA (apiaaccess plan) service key**:
```
cf service-key xsuaa-api xsuaa-api-sk
```
2. Take note (**copy**) the following **service key properties**:
- apiurl
- clientid
- clientsecret
- url
3. Open the **BTP cockpit** and access **your subaccount** (same subaccount used to start the **BAS Dev Space**)
4. On the **left-hand pane** expand the **Connectivity** node
5. Click on **Destinations**
6. Click on **New Destination**
7. Fill-in the **required information** like demonstrated below:

XSUAA API destination

8. Click **Save**

### Assign the Application's Role Collections to Your User
1. Open the **BTP cockpit** and access **your subaccount** (same subaccount used to start the **BAS Dev Space**)
2. On the **left-hand pane** expand the **Security** node and click on **Users**
3. 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.
4. In the **user's details** at the right, click on **Assign Role Collection**
5. Find the role collections starting with **GenericApp**
6. Check both **role collections**
7. Click on **Assign Role Collection**

### Test Application Locally
1. **Start** the application in BAS:
```
cds watch
```
2. **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.
3. Click on the **User** link
4. When prompted to **Sign in** type **john** as the **Username** and click **Sign in**
5. You should see the **information from your user** in JSON format like demonstrated below:

User information

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

### Deploy Application to Cloud Foundry
1. From the **Explorer** open the **mta.yaml** file
2. 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**
3. From the **Explorer** open the **app/user-mngr/webapp/manifest.json** file and do the same search & replace procedure as in the previous step
4. In the **Explorer** right-click on the **mta.yaml** file and select **Build MTA Project**
5. When the build process finishes, an **mta_archives** directory will appear in the **Explorer**
6. Expand the **mta_archives** directory
7. Right-click the **user-mngr_1.0.0.mtar** and select **Deploy MTA Archive**

### Test the Application in Cloud Foundry
1. 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).
2. Click on the **usermngr** link
3. The **Fiori Elements UI** of the service will open in a new tab
4. 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**](https://blogs.sap.com/2022/09/22/build-a-user-management-microservice-in-btp-with-cap).

## Known Issues
No known issues.

## How to obtain support
[Create an issue](https://github.com/SAP-samples//issues) in this repository if you find a bug or have questions about the content.

For additional support, [ask a question in SAP Community](https://answers.sap.com/questions/ask.html).

## 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](https://developercertificate.org/).

## License
Copyright (c) 2022 SAP SE or an SAP affiliate company. All rights reserved. This project is licensed under the Apache Software License, version 2.0 except as noted otherwise in the [LICENSE](LICENSE) file.