Purpose of the document
The document goals are:
- to show differences between GoogleCloud and baremetal environments,
- 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.
This document extends 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 (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.
- Download OSDU_R3_baremetal.postman_environment.json
- Open it in any text editor and simply replace all ocurrences of
baremetal.fqdnwith domain name of your baremetal deployment.
User management
In baremetal deployment users are managed in two places:
- Keycloak - user accounts/passwords/secrets etc
- 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 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:
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:
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
On next step enable Client authentication, Authorization, uncheck Standard flow and press Save:
On client details page disable Front channel logout, Backchannel logout session required and Save:
Switch to Credentials tab. Here you could get Client secret (press eye button next) or force its re-generation:
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:
Press Add user button.
Enter user email into username and email fileds, optionally switch Email verified to On and press Create
Click Credentials and Set password, enter password. If you want to enforce user to chnage password in next login leave Temporary enabled and Save:
Press Save password in next window.
User could set new password by accessing Keycloak account page at 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.
In Postman Environments page open environmet matches your installation and set following values with data from previous steps: CLIENT_ID, CLIENT_SECRET and save:
Open Quick start or other Postman collection and go to the Authorization tab:
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.
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:
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.viewersorusers.datalake.admins(if you going to make changes in data)
The instruction for granting permissions is available here.
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:
grant_type=client_credentials
client_id=datafier
scope=openid
data-partition-id={{data-partition-id}}
client_secret=datafier_secret_value
Press Send. You should get set of tokens for datafier user. Then you could proceed with grating permissions for users.