Changes

Page history
Updated QSGs authored by Dzmitry Malkevich (EPAM)'s avatar Dzmitry Malkevich (EPAM)
Hide whitespace changes
Inline Side-by-side
OSDU-baremetal-QSG.md 0 → 100755
View page @ 78975e53
# OSDU baremetal QSG
## Purpose of the document
The document goals are:
1. to show differences between GoogleCloud and baremetal environments,
2. to help configure a Postman environment to do initial testing.
This document is not intended to introduce you to all OSDU services. For full OSDU documentation please use [the link](https://osduforum.org/getting-started/osdu-documentation/).
This document extends [OSDU API Quick start guide](https://community.opengroup.org/osdu/documentation/-/wikis/OSDU-API-Quick-start-guide) to baremetal deployment.
## Configuring a Postman environment
OSDU uses the Postman tool to do majority of API testing. Here are the pre-requisites and the steps you need to perform to configure Postman environment.
### Pre-requisites
OSDU deployed on baremetal with [examples](https://community.opengroup.org/osdu/platform/deployment-and-operations/infra-gcp-provisioning/-/tree/release/0.20/examples/simple_osdu_onprem) (for release **M17/v0.20**) or newer ones.
In order to manage users you should have login and password of user with Keycloak administrator permissions (set during deployment).
### Prepare Postman environment file for the OSDU installation
Unlike GC deployment baremetal currently doesn't offer option to download ready-to-use Postman environment file. But you could easily create it yourself.
1. Download [OSDU_R3_GCP_Reference.postman_environment.json](https://community.opengroup.org/osdu/platform/pre-shipping/-/blob/main/R3-M17/GCP-M17/OSDU_R3_GCP_Reference.postman_environment.json)
2. Open it in any text editor and simply replace all ocurrences of `reference.gcp.gnrg-osdu.projects.epam.com` with domain name of your baremetal deployment.
### User management
In baremetal deployment users are managed in two places:
1. Keycloak - user accounts/passwords/secrets etc
2. Entitlements service - user permissions in OSDU API
This guide will cover only creation of new user accounts and obtaning tokens. Managing of user permission in Entitlements is covered in [this](https://community.opengroup.org/osdu/documentation/-/wikis/Releases/R3.0/GCP/GCP-Operation/User-Mng/User-Management) guide and main article.
#### Managing users in Keycloak
Default username for Keycloak is `user`, password is one you set during deployment.
Keycloak administration console is accessible via URL `https://keycloak.your_domain/admin`.
After login as administrator you will have access to Master and OSDU realms. You need to switch to `OSDU` (or partition name you specified during deployment) realm:
![osdu realm](./uploads/baremetal-qsg-img/kk-osdu.png)
You will need to create client and users.
##### Creating client
CLick `Clients` in the left navigation pane. You will see list of existing client and service accounts:
![keycloak clients](./uploads/baremetal-qsg-img/kk-clients-list.png)
We need to create new client whos `ID` and `Secret` will be used later by users to generate tokens.
Press `Create client` button.
Enter client ID (for example `demo_client`) and press `Next`
![step 1](./uploads/baremetal-qsg-img/kk-create-client-1.png)
On next step enable `Client authentication`, `Authorization`, uncheck `Standard flow` and press `Save`:
![step 2](./uploads/baremetal-qsg-img/kk-create-client-2.png)
On client details page disable `Front channel logout`, `Backchannel logout session required` and `Save`:
![step 3](./uploads/baremetal-qsg-img/kk-create-client-3.png)
Switch to `Credentials` tab. Here you could get `Client secret` (press `eye` button next) or force its re-generation:
![step 4](./uploads/baremetal-qsg-img/kk-create-client-4.png)
Now you have `ClientID` and `Client Secret` required to generate tokens to access OSDU API.
##### Creating user
CLick `Users` in the left navigation pane. You will see list of existing users:
![users](./uploads/baremetal-qsg-img/kk-users-list.png)
Press `Add user` button.
Enter user email into username and email fileds, optionally switch `Email verified` to `On` and press `Create`
![step 1](./uploads/baremetal-qsg-img/kk-create-user-1.png)
Click `Credentials` and `Set password`, enter password. If you want to enforce user to chnage password in next login leave `Temporary` enabled and `Save`:
![step 2](./uploads/baremetal-qsg-img/kk-create-user-2.png)
Press `Save password` in next window.
User could set new password by accessing Keycloak account page at [https://keycloak.your_domain/realms/osdu/account/](https://keycloak.your_domain/realms/osdu/account/)
Now you have both client and user created and you could proceed with token creation and API access.
##### Getting refresh token
Refer to [Postman authentication guide](https://community.opengroup.org/osdu/platform/pre-shipping/-/blob/main/R3-M16/GCP-M16/Postman_Authentication_Guide_REF_env.md).
In Postman Environments page open environmet matches your installation and set following values with data from previous steps: `CLIENT_ID`, `CLIENT_SECRET` and save:
![postman env](./uploads/baremetal-qsg-img/kk-postman-env-1.png)
Open [Quick start](https://community.opengroup.org/osdu/documentation/-/wikis/uploads/3c9820ad7dfe9ed873755c53500afe4e/OSDU_Quick_start.postman_collection.json) or other Postman collection and go to the Authorization tab:
![auth tab](./uploads/baremetal-qsg-img/kk-postman-auth-1.png)
Set `Type=OAuth 2.0` and scoll down to `Configure New Token` and press `Edit token configuration`.
Set `Token Name`, `Grant Type=Password Credentials`, `Access Token URL={{Token_Fetch_URL}}`, `Client ID={{CLIENT_ID}}`, `Client Secret{{CLIENT_SECRET}}`, `Username` - email of user added in Keycloak, `Password` - password for this user.
![auth](./uploads/baremetal-qsg-img/kk-postman-auth-2.png)
Press `Get New Access Token`.
In `Manage access tokens` window scroll down to `refresh_token` section, select this value and copy it. Than paste in your Postman environent:
![env](./uploads/baremetal-qsg-img/kk-postman-auth-4.png)
Save the environment.
Now you could use `Refresh Token` requests from Postman collection to get new access tokens.
### Grant permissions for users
An OSDU admin (datafier@*data_partition_id*.*domain* or `datafier@osdu.group` in baremetal) grants Entitlements permissions for users who send requests using Postman. These users should be added into the following Entitlements groups:
- `users`
- `users.datalake.viewers` or `users.datalake.admins` (if you going to make changes in data)
The instruction for granting permissions is available [here](https://community.opengroup.org/osdu/documentation/-/wikis/Releases/R3.0/GCP/GCP-Operation/User-Mng/User-Management).
In order to authenticate using datafier account you should follow these steps:
In Postman create new `POST` request and set `{{Token_Fetch_URL}}` as URL, in `Body` section select `x-www-form-urlencoded` and set following parameters:
```text
grant_type=client_credentials
client_id=datafier
scope=openid
data-partition-id={{data-partition-id}}
client_secret=datafier_secret_value
```
![datafier](./uploads/baremetal-qsg-img/kk-datafier-auth.png)
Press `Send`. You should get set of tokens for `datafier` user. Then you could proceed with grating permissions for users.