MODUSERSKC-4 Document process of user creation
- Natalia Zaitseva
- Craig McNally
- Yauhen Vavilkin
MODUSERSKC-4 - Getting issue details... STATUS
In this guide, we will learn how to create a user, search for capabilities/capability-sets according to the relevant folio permissions, and create roles with the necessary capabilities and assign them to the user. Please note that these operations will eventually all be possible via the Folio UI.
Please note that these operations will eventually all be possible via the Folio UI.
Preparations
This guide uses the command line, cURL utility, and jq (a lightweight and flexible command-line JSON processor).
For convenience, save the base URL of your environment as a variable. For instance, if you're working with a local environment, you'll use:
baseUrl="http://gateway" adminUsername="folio" adminPassword="folio" tenant="diku"
Disclaimer: Please replace variables with your actual data. The data you use should be according to your current environment setup.
Getting Access Token
curl -c - -L -X POST "${baseUrl}/authn/login-with-expiry" \
-H "x-okapi-tenant: ${tenant}" \
-H 'Content-Type: application/json' \
-d '{
"username": "'"${adminUsername}"'",
"password": "'"${adminPassword}"'"
}' | grep folioAccessToken
Once you've got your access token, save it as a variable.
token="access_token_from_cookies_here"
Remember, all the operations hence should employ this variable with token.
Creating a User
To create call perform the following request:
curl -L -X POST "${baseUrl}/users-keycloak/users" \
-H "x-okapi-tenant: ${tenant}" \
-H "x-okapi-token: ${token}" \
-H 'Content-Type: application/json' \
-d '{
"username": "johndoe",
"type": "staff",
"personal": {
"firstName": "John",
"lastName": "Doe",
"email": "johndoe@foo.bar"
}
}' | jq .
Save user ID.
Create user password
Once you have created a user, you can assign a password to it using the username. Here's a command example on how you can do this:
curl -L -X POST "${baseUrl}/authn/credentials" \
-H "x-okapi-tenant: ${tenant}" \
-H "x-okapi-token: ${token}" \
-H 'Content-Type: application/json' \
-d '{
"username": "johndoe",
"password": "secret_password"
}'
Note: Make sure to store your username and password, as they will be used for the user to log in to the system.
Capabilities
Understanding Capabilities
Before we proceed with searching and assigning capabilities, it's important to understand what capabilities are.
There are two concepts: capability and capability-set. A capability is like an atomic permission. It is the smallest indivisible unit of power that can be assigned.
On the other hand, a capability-set is a collection of multiple capabilities, which simplifies the management of capabilities. Capabilities and capability-sets can be assigned to a role and then assigned to a user. They can also be assigned directly to a user. It's also crucial to understand that these capabilities and capability-sets are created and managed by the system itself.
Unlike permission-sets in Folio, a capability-set cannot contain other capability-sets. It can only contain capabilities.
Searching capabilities/capability-sets
To search for capability-sets, use the following request:
curl -X GET "${baseUrl}/capability-sets" \
-H "x-okapi-tenant: ${tenant}" \
-H "x-okapi-token: ${token}" | jq .
Let's say we want to find all capability-sets related to Inventory. We can achieve it using this request:
curl -X GET "${baseUrl}/capability-sets?query=resource==Inventory" \
-H "x-okapi-tenant: ${tenant}" \
-H "x-okapi-token: ${token}" | jq .
Capability-sets response under the spoiler:
Note: The example above illustrates how you can utilize the query parameter in the request for searching records, a prevalent approach in Folio. Refine your search by adjusting the query parameter to match your specific needs.
To search capabilities, use the following request:
curl -X GET "${baseUrl}/capabilities?query=permission==accounts.cancel.post" \
-H "x-okapi-tenant: ${tenant}" \
-H "x-okapi-token: ${token}" | jq .
Response example under the spoiler:
Note: A capability has a permissions field that corresponds to the permissionName in Folio permissions. This information can be helpful when searching for the required permissions.
Example of Searching for a Capability Corresponding to a Permission
In Folio, the description parameter is consistent across permissions and capabilities. For instance, if you're searching for a capability-set corresponding to a Folio UI permission, you can utilize the description parameter in your search criteria. This can provide a clearer navigation and management of permissions and their associated capabilities.
Let's imagine we have a UI permission with the displayName 'Inventory: All permissions'. We first find this permission in mod-permissions and then link it to a capability-set using the description parameter. To find permission by using the displayName, you can do the following search:
curl -X GET "${baseUrl}/perms/permissions?query=displayName=Inventory: All permissions" \
-H "x-okapi-tenant: ${tenant}" \
-H "x-okapi-token: ${token}" | jq .
Now, having the permission's description, we can find the corresponding capability-set:
curl -X GET "${baseUrl}/capability-sets?query=description==*Some subperms to support enabling*" \
-H "x-okapi-tenant: ${tenant}" \
-H "x-okapi-token: ${token}" | jq .
Creating Roles and Assigning Capabilities
After the user is created, and the required capability-set and capability have been found, we can proceed to the creation of a role and assignment to the user.
Note: Capabilities can be assigned both directly to a user and through a role.
Create a role:
curl -X POST "${baseUrl}/roles" \
-H "x-okapi-tenant: ${tenant}" \
-H "x-okapi-token: ${token}" \
-H 'Content-Type: application/json' \
-d '{
"name": "role-name",
"description": "role description"
}' | jq .
To associate role with capability-sets, use the following command:
curl -X POST "${baseUrl}/roles/capability-sets" \
-H "x-okapi-tenant: ${tenant}" \
-H "x-okapi-token: ${token}" \
-H 'Content-Type: application/json' \
-d '{
"roleId": "f4351668-8216-43de-b82d-c0aca05153b0",
"capabilitySetIds": [
"e54e1b37-6f11-422e-b7ed-70339f3d4dff"
]
}' | jq .
To assign the newly created role to the user, use the following command:
curl -X POST "${baseUrl}/roles/users" \
-H "x-okapi-tenant: ${tenant}" \
-H "x-okapi-token: ${token}" \
-H 'Content-Type: application/json' \
-d '{
"userId": "13480b8b-dba5-4980-86d7-5314996a418b",
"roleIds": [
"f4351668-8216-43de-b82d-c0aca05153b0"
]
}' | jq .
Assigning Roles to a User
Once the role has been created and associated with the required capability-set (or just capability), we can proceed to assign this role to the user.
To assign the newly created role to the user, use the following command:
curl -X POST "${baseUrl}/roles/users" \
-H "x-okapi-tenant: ${tenant}" \
-H "x-okapi-token: ${token}" \
-H 'Content-Type: application/json' \
-d '{
"userId": "13480b8b-dba5-4980-86d7-5314996a418b",
"roleIds": [
"f4351668-8216-43de-b82d-c0aca05153b0"
]
}' | jq .
Note: Ensure to use the appropriate IDs for the user, role, and capabilities that correspond to your specific environment when executing these commands. Correct IDs are crucial for the proper assignment of permissions.
Assigning Capabilities Directly to User
It's possible to assign capability-sets or capabilities directly to a user, bypassing the role. Here is the corresponding request for this operation.
Associate user with capabilities:
curl -X POST "${baseUrl}/users/capabilities" \
-H "x-okapi-tenant: ${tenant}" \
-H "x-okapi-token: ${token}" \
-H 'Content-Type: application/json' \
-d '{
"userId": "61893f40-4739-49fc-bf07-daeff3021f90",
"capabilityIds": [
"8d2da27c-1d56-48b6-958d-2bfae6d79dc8",
"d5221b22-386f-4c7f-b3b6-5897f94044a0"
]
}' | jq .
Associate user with capability-sets:
curl -X POST "${baseUrl}/users/capability-sets" \
-H "x-okapi-tenant: ${tenant}" \
-H "x-okapi-token: ${token}" \
-H 'Content-Type: application/json' \
-d '{
"userId": "9b663ae9-9483-4fab-966b-58955bc31893",
"capabilitySetIds": [
"c11e07f4-8bb0-45d1-a396-aaa72ae3121b",
"d928eab1-1d3a-4d67-949e-a0305ced5b6a"
]
}' | jq .
Useful Links and Additional Information
There is an API endpoint available for creating multiple roles at once:
POST /roles/batch.How to create a Shadow User in a member tenant can be found here