diff --git a/README.md b/README.md index 07420f4b1e..7c7ba6837b 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ As a result, you can concentrate on crafting self-sovereign identity solutions u * HTTP events notification * Cardano as a distributed ledger * Secrets management with Hashicorp vault -* Multi-tenancy (coming soon) +* Multi-tenancy ## Example use cases diff --git a/docs/docusaurus/index.md b/docs/docusaurus/index.md index db27f36df4..d9f8037f79 100644 --- a/docs/docusaurus/index.md +++ b/docs/docusaurus/index.md @@ -9,6 +9,7 @@ Whether you are new to [self-sovereign identity (SSI)](/docs/concepts/glossary#s Throughout all code examples in tutorials, the following conventions are in use: +* Issuer Keycloak is hosted at `http://localhost:9980/` * Issuer Agent is hosted at `http://localhost:8080/prism-agent/` * Holder Agent is hosted at `http://localhost:8090/prism-agent/` * Verifier Agent is hosted at `http://localhost:8100/prism-agent/` diff --git a/docs/docusaurus/multitenancy/tenant-migration.md b/docs/docusaurus/multitenancy/tenant-migration.md new file mode 100644 index 0000000000..38e21e18b4 --- /dev/null +++ b/docs/docusaurus/multitenancy/tenant-migration.md @@ -0,0 +1,175 @@ +# Migration from `apikey` to `JWT` authentication + +PRISM Agent authentication supports multiple authentication methods simultaneously, which means the user can seamlessly use any available credentials including `apikey` or `JWT` to access the wallet. +The agent's [UMA](/docs/concepts/glossary#uma) permission resource also exposes self-service permission endpoint, allowing users to manage the permissions for their wallets. +It allows users to transition from `apikey` to `JWT` authentication without admin intervention.intervention. + +## Roles + +In the migration process from `apikey` to `JWT`, there is only one role: + +1. Tenant + +## Prerequisites + +1. Keycloak up and running +2. Keycloak is configured the same as in [Tenant Onboarding Self-Service](./tenant-onboarding-self-service.md) +3. PRISM Agent up and running +4. PRISM Agent is configured the same as in [Tenant Onboarding Self-Service](./tenant-onboarding-self-service.md) +5. The user has access to the wallet using `apikey`. (See [Tenant Onboarding](./tenant-onboarding.md)) +6. The user has an account registered on Keycloak + +## Overview + +This tutorial outlines the steps to transition from `apikey` to `JWT` authentication. +Initially, users have wallet access through the `apikey` method. +To migrate to `JWT` authentication, users can create a new UMA permission for their wallet and grant permission to their Keycloak account. + +## Endpoints + +### Agent endpoints +| Endpoint | Description | Role | +|--------------------------------------------|--------------------------------------|--------| +| `GET /wallets` | List the wallets on PRISM Agent | Tenant | +| `POST /wallets` | Create a new wallet on PRISM Agent | Tenant | +| `POST /wallets/{walletId}/uma-permissions` | Create a uma-permission for a wallet | Tenant | +| `GET /did-registrar/dids` | List the DIDs inside the wallet | Tenant | + +### Keycloak endpoints +| Endpoint | Description | Role | +|------------------------------------------------------|-----------------------|--------| +| `POST /realms/{realm}/protocol/openid-connect/token` | Issue a new JWT token | Tenant | + +## Tenant interactions + +### 1. Check the existing wallets using `apikey` + +This tutorial assumes the tenant can access the wallet using `apikey`. +Before granting more permission to the wallet, the `walletId` must be identified. +To find the wallet, list them using `apikey`. + +```bash +curl -X 'GET' \ + 'http://localhost:8080/prism-agent/wallets' \ + -H 'accept: application/json' \ + -H "apikey: my-tenant-token" +``` + +Make sure to use the correct `apikey` from the pre-requisite. + +Response Example: + +```json +{ + "self": "/wallets", + "kind": "WalletPage", + "pageOf": "/wallets", + "contents": [ + { + "id": "99734c87-5c9d-4697-b5fd-dea4e9590ba7", + "name": "my-wallet", + "createdAt": "2023-01-01T00:00:00Z", + "updatedAt": "2023-01-01T00:00:00Z" + } + ] +} +``` + +### 2. Get the access token on keycloak + +Run this command to log in and get the access token + +```bash +curl -X 'POST' \ + 'http://localhost:9980/realms/my-realm/protocol/openid-connect/token' \ + -d "grant_type=password" \ + -d "client_id=admin-cli" \ + -d "username=alice" \ + -d "password=1234" +``` + +Make sure to use the correct username and password. +Special attention on the `client_id`; this should be the actual `client_id` of the frontend application that logs the user in. +For this tutorial, it is OK to use `admin-cli` + +Example token response (some fields omitted for readability) + +```json +{ + "access_token": "eyJhbGciOi...7ocDHofUDQ", + "refresh_token": "eyJhbGciOi...otsEEi4eQA", + ... +} +``` + +### 3. Extract the subject ID from JWT + +When creating a UMA permission, it is important to provide the subject ID to grant permission. +To get the subject ID of the tenant, one can inspect the JWT payload `sub` claim. + +Run this command to extract the `sub` claim of the token from previous step. + +```bash +echo 'eyJhbGciOi...7ocDHofUDQ' | cut --delimiter='.' --fields=2 | base64 --decode | jq -r '.sub' +``` + +Example result + +```log +4a5c6ac9-12f5-4d1e-b8f2-667525c083fd +``` + +### 4. Grant the user permission to the wallet + +UMA permission can be added to the current wallet, giving Keycloak users access. +To do this, invoke the `POST /wallets/{walletId}/uma-permissions` endpoint on the agent. + +```bash +curl -X 'POST' \ + 'http://localhost:8080/prism-agent/wallets/99734c87-5c9d-4697-b5fd-dea4e9590ba7/uma-permissions' \ + -v \ + -H 'accept: */*' \ + -H "apikey: my-tenant-token" \ + -H 'Content-Type: application/json' \ + -d '{ + "subject": "205e04b7-0158-41b0-89c3-f91c3a09f89b" + }' +``` + +Make sure to use the correct `subject` for the user and the correct `walletId` from the step earlier. + +The response should return the status `200 OK` in case of successful permission creation. + +### 5. Perform a simple action to verify access to PRISM Agent + +After successful UMA permission creation, the user should be able to use the `JWT` token to authenticate the wallet. +List the wallet using a new `Authorization` header. The listed wallets should contain the wallet with the same ID in step 1. + +```bash +curl -X 'GET' \ + 'http://localhost:8080/prism-agent/wallets' \ + -H 'accept: application/json' \ + -H 'Authorization: Bearer eyJhbGciOi...7ocDHofUDQ' +``` + +Make sure to use the correct `JWT` from step 2. + +Response Example: + +```json +{ + "self": "/wallets", + "kind": "WalletPage", + "pageOf": "/wallets", + "contents": [ + { + "id": "99734c87-5c9d-4697-b5fd-dea4e9590ba7", + "name": "my-wallet", + "createdAt": "2023-01-01T00:00:00Z", + "updatedAt": "2023-01-01T00:00:00Z" + } + ] +} +``` + +This response indicates that the user should be able to perform any wallet interaction with the `JWT` and `apikey` interchangeably. diff --git a/docs/docusaurus/multitenancy/tenant-onboarding-ext-iam.md b/docs/docusaurus/multitenancy/tenant-onboarding-ext-iam.md new file mode 100644 index 0000000000..37de8d0c96 --- /dev/null +++ b/docs/docusaurus/multitenancy/tenant-onboarding-ext-iam.md @@ -0,0 +1,317 @@ +# Tenant Onboarding with External IAM + +In the [Tenant Onboarding](./tenant-onboarding.md) tutorial, we explored the basic +The agent provides [IAM](/docs/concepts/glossary#iam) functionality out of the box. Although it is usable and straightforward, more featureful tools are available for handling identity and access management. +The agent can seamlessly connect with [Keycloak](/docs/concepts/glossary#keycloak-service) as an external IAM system, allowing the application built on top to utilize capabilities that come with Keycloak. + +The PRISM Agent leverages standard protocols like [OIDC](/docs/concepts/glossary#oidc) and [UMA](/docs/concepts/glossary#uma) for authentication and access management. +The user's identity gets established through the ID token, and wallet permissions are searchable using the [RPT (requesting party token)](/docs/concepts/glossary#rpt). + +## Roles + +In tenant management with external IAM, there are 2 roles: + +1. [Administrator](/docs/concepts/glossary#administrator) +2. [Tenant](/docs/concepts/glossary#tenant) + +## Prerequisites + +1. Keycloak up and running +2. Keycloak is configured as follows + 1. A realm called `my-realm` is created + 2. A client called `prism-agent` under `my-realm` with __authorization__ feature is created. (See [create client instruction](https://www.keycloak.org/docs/latest/authorization_services/index.html#_resource_server_create_client)) + 3. Make sure the `prism-agent` client has __direct access grants__ enabled to simplify login process for this tutorial +3. PRISM Agent up and running +4. PRISM Agent is configured with the following environment variables: + 1. `ADMIN_TOKEN=my-admin-token` + 2. `DEFAULT_WALLET_ENABLED=false` + 3. `KEYCLOAK_ENABLED=true` + 4. `KEYCLOAK_URL=http://localhost:9980` (replace with appropriate value) + 5. `KEYCLOAK_REALM=my-realm` + 6. `KEYCLOAK_CLIENT_ID=prism-agent` + 7. `KEYCLOAK_CLIENT_SECRET=` (replace with appropriate value) + 8. `KEYCLOAK_UMA_AUTO_UPGRADE_RPT=false` + +## Overview + +This tutorial illustrates the process of provisioning a wallet resource for the new tenant and creating a tenant in Keycloak. +The administrator can then create a UMA permission for the wallet, giving access to the tenant. + +When setting up UMA permissions on the agent, the wallet resource, along with the UMA policy and permission +are created on Keycloak according to a predefined convention. +For flexibility in defining custom policy and permission models, +administrators can manually create these UMA resources (resource, policy, permission) directly on Keycloak +using a set of UMA endpoints called [Protection API](/docs/concepts/glossary#protection-api) (see [Keycloak Protection API](https://www.keycloak.org/docs/latest/authorization_services/index.html#_service_protection_api)). +However, using Protection API to manage permissions is out of the scope of this tutorial. + +Once the registration is successful, the tenant can obtain an ID token from Keycloak using any available OIDC flow, +such as the direct access grants (username & password). This ID token typically contains user claims such as username and subject ID. +The tenant can use Keycloak's token endpoint to convert this token to an RPT (requesting party token), +another token containing permissions information. +The tenant can access the multi-tenant agent by providing the RPT in the `Authorization` header. + +## Endpoints + +### Agent endpoints +| Endpoint | Description | Role | +|--------------------------------------------|--------------------------------------|---------------| +| `GET /wallets` | List the wallets on PRISM Agent | Administrator | +| `POST /wallets` | Create a new wallet on PRISM Agent | Administrator | +| `POST /wallets/{walletId}/uma-permissions` | Create a uma-permission for a wallet | Administrator | +| `GET /did-registrar/dids` | List the DIDs inside the wallet | Tenant | + +### Keycloak endpoints +| Endpoint | Description | Role | +|------------------------------------------------------|-------------------------------|-----------------------| +| `POST /admin/realms/{realm}/users` | Create a new user on Keycloak | Administrator | +| `POST /realms/{realm}/protocol/openid-connect/token` | Issue a new JWT token | Administrator, Tenant | + +## Administrator interactions + +### 1. Check the existing wallets + +When running PRISM Agent using the configurations above, the Agent should start with an empty state. +Listing wallets on it should return empty results. + +```bash +curl -X 'GET' \ + 'http://localhost:8080/prism-agent/wallets' \ + -H 'accept: application/json' \ + -H 'x-admin-api-key: my-admin-token' +``` + +Response Example: + +```json +{ + "self": "/wallets", + "kind": "WalletPage", + "pageOf": "/wallets", + "contents": [] +} +``` + +### 2. Create a new wallet + +Create a wallet using a `POST /wallets` endpoint. +This wallet will be a container for the tenant's assets (DIDs, VCs, Connections, etc.). +Provide a wallet seed during the wallet creation or let the Agent generate one + + +```bash +curl -X 'POST' \ + 'http://localhost:8080/prism-agent/wallets' \ + -H 'accept: application/json' \ + -H 'x-admin-api-key: my-admin-token' \ + -H 'Content-Type: application/json' \ + -d '{ + "seed": "c9994785ce6d548134020f610b76102ca1075d3bb672a75ec8c9a27a7b8607e3b9b384e43b77bb08f8d5159651ae38b98573f7ecc79f2d7e1f1cc371ce60cf8a", + "name": "my-wallet" + }' +``` + +Response Example: + +```json +{ + "id": "99734c87-5c9d-4697-b5fd-dea4e9590ba7", + "name": "my-wallet", + "createdAt": "2023-01-01T00:00:00Z", + "updatedAt": "2023-01-01T00:00:00Z" +} +``` + +### 3. User registration on Keycloak + +There are multiple ways to complete this step. +The goal is to ensure the user has registered on Keycloak. +Keycloak offers great flexibility, allowing users to self-register, +For this tutorial, we will generate the user manually using Keycloak admin API for simplicity. + +The first step is to get an admin token from Keycloak using the username and password. +This token allows the admin to perform operations on Keycloak, such as creating a new user. +Running the provided command should return the admin access token. + +```bash +curl -X 'POST' \ + 'http://localhost:9980/realms/master/protocol/openid-connect/token' \ + -d "grant_type=password" \ + -d "client_id=admin-cli" \ + -d "username=$KEYCLOAK_ADMIN_USER" \ + -d "password=$KEYCLOAK_ADMIN_PASSWORD" +``` + +Make sure to replace the Keycloak variables with appropriate values. + +Example token response (some fields omitted for readability) + +```json +{ + "access_token": "eyJhbGciOi...7ocDHofUDQ", + "refresh_token": "eyJhbGciOi...otsEEi4eQA", + ... +} +``` + +After obtaining the `access_token` from Keycloak's admin, a new user can be created using this command: + +```bash +curl -X 'POST' \ + 'http://localhost:9980/admin/realms/my-realm/users' \ + -v \ + -H 'Authorization: Bearer eyJhbGciOi...7ocDHofUDQ' \ + -H 'Content-Type: application/json' \ + --data-raw "{ + \"username\": \"alice\", + \"firstName\": \"Alice\", + \"enabled\": true, + \"credentials\": [{\"value\": \"1234\", \"temporary\": false}] + }" +``` + +Make sure to use the correct `access_token` in the `Authorization` header from the previous command. + +Example response log + +```log +< HTTP/1.1 201 Created +< Referrer-Policy: no-referrer +< X-Frame-Options: SAMEORIGIN +< Strict-Transport-Security: max-age=31536000; includeSubDomains +< X-Content-Type-Options: nosniff +< X-XSS-Protection: 1; mode=block +< Location: http://localhost:9980/admin/realms/my-realm/users/205e04b7-0158-41b0-89c3-f91c3a09f89b +< content-length: 0 +``` + +The response should return status `201 Created` indicating the new user is registerd with username `alice` with a password `1234`. +The user ID can be observed from `Location` header of the response. This ID will be used for creating permission later in this tutorial. + +For in-depth user management, please consult the official Keycloaak administration documentation on [managing users section](https://www.keycloak.org/docs/latest/server_admin/index.html#assembly-managing-users_server_administration_guide). + +### 4. Grant the user permission to the wallet + +Once the user and wallet have been successfully created, the permissions can be created giving the user access to the wallet. +This can be done by invoking the `POST /wallets/{walletId}/uma-permissions` endpoint on the agent. + +```bash +curl -X 'POST' \ + 'http://localhost:8080/prism-agent/wallets/99734c87-5c9d-4697-b5fd-dea4e9590ba7/uma-permissions' \ + -v \ + -H 'accept: */*' \ + -H 'x-admin-api-key: my-admin-token' \ + -H 'Content-Type: application/json' \ + -d '{ + "subject": "205e04b7-0158-41b0-89c3-f91c3a09f89b" + }' +``` + +Make sure to use the correct `subject` for the user and the correct `walletId` from the step earlier. +The user ID can be observed from the response header from the previous step or in the __User__ menu in Keycloak Admin UI. + +The response should return status `200 OK` in case of successful permission creation. + +## Tenant interactions + +After the user is registered on Keycloak and the required permission is created by admin, +the tenant can log in and utilize the agent by using the token issued by Keycloak. + +### 1. Obtain access token from Keycloak + +The first step is to authenticate via Keycloak through any applicable authentication method. +Usually, the tenant will use some frontend application that follows the standard flow for logging in. +For simplicity, we use a flow for username and password in this tutorial. +The administrator has already set up the username and password for the tenant. +To get the access token, the tenant can call the Keycloak token endpoint directly with those credentials. + +Run the command to log in + +```bash +curl -X 'POST' \ + 'http://localhost:9980/realms/my-realm/protocol/openid-connect/token' \ + -d "grant_type=password" \ + -d "client_id=admin-cli" \ + -d "username=alice" \ + -d "password=1234" +``` + +Special attention on the `client_id`; this should be the actual `client_id` of the frontend application that logs the user in. +For this tutorial, it is OK to use `admin-cli`. + +Example token response (some fields omitted for readability) + +```json +{ + "access_token": "eyJhbGciOi...7ocDHofUDQ", + "refresh_token": "eyJhbGciOi...otsEEi4eQA", + ... +} +``` + +### 2. Request [RPT (requesting party token)](/docs/concepts/glossary#rpt) from access token + +After the access token is acquired, the next step is to get the RPT token, which holds information about the permissions. +It is possible to request the RPT by running this command: + +```bash +curl -X POST \ + 'http://localhost:9980/realms/my-realm/protocol/openid-connect/token' \ + -H "Authorization: Bearer eyJhbGciOi...7ocDHofUDQ" \ + -d "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \ + -d "audience=prism-agent" +``` + +Example token response (some fields omitted for readability) + +```json +{ + "access_token": "eyJhbGciOi...e7H6W8RUvA", + "refresh_token": "eyJhbGciOi...W1_y1AF_YY", + ... +} +``` + +After inspecting the response token, a new claim named `authorization` should appear in the JWT payload. + +Example RPT payload (some fields omitted for readability) + +```json +{ + ... + "authorization": { + "permissions": [ + { + "rsid": "99734c87-5c9d-4697-b5fd-dea4e9590ba7", + "rsname": "" + }, + ... + ] + }, + ... +} +``` + +### 3. Perform a simple action to verify access to PRISM Agent + +To prove that the tenant can access the wallet using RPT, +try listing the DIDs in the wallet using RPT in the `Authorization` header. + +```bash +curl --location --request GET 'http://localhost:8080/prism-agent/did-registrar/dids' \ + -H 'Authorization: Bearer eyJhbGciOi...e7H6W8RUvA' \ + -H 'Accept: application/json' +``` + +Make sure to replace the token with RPT from previous step. + +The result should show 200 status with an empty list. +This means that the wallet has been created and does not contain any DIDs. +All actions carried out by the tenant must be limited to this specific wallet. + +### A note on RPT + +In this tutorial, there is an additional step for the tenant to request the RPT from the access token. +This process aligns with the standard UMA interaction, where the handling of RPT typically occurs on the client side. +To simplify the experience, the agent has a feature allowing users to bypass this process. +By setting the variable `KEYCLOAK_UMA_AUTO_UPGRADE_RPT=true`, tenants can utilize the access token +obtained in step 1 directly in the `Authorization` header, eliminating the need for additional RPT request step. diff --git a/docs/docusaurus/multitenancy/tenant-onboarding-self-service.md b/docs/docusaurus/multitenancy/tenant-onboarding-self-service.md new file mode 100644 index 0000000000..9738d0035f --- /dev/null +++ b/docs/docusaurus/multitenancy/tenant-onboarding-self-service.md @@ -0,0 +1,168 @@ +# Tenant Onboarding Self-Service + +In the [Tenant Onboarding with External IAM](./tenant-onboarding-ext-iam.md) tutorial, +we learned how [Keycloak](/docs/concepts/glossary#keycloak-service) helps with user access and how it works together with the agent. +To set things up, the admin has to provision the required resources. +However, relying on the admin for onboarding operations can be restrictive for some use cases. +For example, some tenants might want to onboard on a self-service agent instance without admin intervention. + +By leveraging Keycloak for a self-service agent instance, +users can self-register or link to other [Identity Providers (IDPs)](/docs/concepts/glossary#idp) to register an account. +Once the account is registered, users can use it to set up their wallets. +This tutorial will investigate the steps to facilitate this scenario where [administrator](/docs/concepts/glossary#administrator) intervention is unnecessary. + +## Roles + +In self-service tenant management with external IAM, there is only one role: + +1. [Tenant](/docs/concepts/glossary#tenant) + +## Prerequisites + +1. Keycloak is up and running. +2. Keycloak is configured as follows + 1. A realm called `my-realm` is created + 2. A client called `prism-agent` under `my-realm` with __authorization__ feature is created. (See [create client instruction](https://www.keycloak.org/docs/latest/authorization_services/index.html#_resource_server_create_client)) + 3. Make sure the `prism-agent` client has __direct access grants__ enabled to simplify the login process for this tutorial. + 4. Make sure to [allow user self-registration](https://www.keycloak.org/docs/latest/server_admin/index.html#con-user-registration_server_administration_guide). +3. PRISM Agent up and running +4. PRISM Agent is configured with the following environment variables: + 1. `ADMIN_TOKEN=my-admin-token` + 2. `DEFAULT_WALLET_ENABLED=false` + 3. `KEYCLOAK_ENABLED=true` + 4. `KEYCLOAK_URL=http://localhost:9980` (replace with appropriate value) + 5. `KEYCLOAK_REALM=my-realm` + 6. `KEYCLOAK_CLIENT_ID=prism-agent` + 7. `KEYCLOAK_CLIENT_SECRET=` (replace with appropriate value) + 8. `KEYCLOAK_UMA_AUTO_UPGRADE_RPT=true` + +## Overview + +This tutorial demonstrate the process of user self-registration on Keycloak. +Then, the users can log in to Keycloak to obtain a token. +When the agent uses this token for the wallet creation, the agent recognizes it belongs to a tenant and automatically associates the tenant's permission with the created wallet. + +## Endpoints + +### Agent endpoints +| Endpoint | Description | Role | +|---------------------------|------------------------------------|--------| +| `GET /wallets` | List the wallets on PRISM Agent | Tenant | +| `POST /wallets` | Create a new wallet on PRISM Agent | Tenant | +| `GET /did-registrar/dids` | List the DIDs inside the wallet | Tenant | + +### Keycloak endpoints +| Endpoint | Description | Role | +|------------------------------------------------------|-----------------------|--------| +| `POST /realms/{realm}/protocol/openid-connect/token` | Issue a new JWT token | Tenant | + +## Tenant interactions + +### 1. Self-register account on Keycloak + +Start by registering a new account on Keycloak, accessible through its login page. +Usually, this should be available at `http://localhost:9980/realms/my-realm/account/`. + +For detailed instructions on how to register a new user, +please refer to [registering a new user](https://www.keycloak.org/docs/latest/server_admin/index.html#proc-registering-new-user_server_administration_guide) section on the official documentation. + +### 2. Obtain access token from Keycloak + +Once a new account is registered, Keycloak should recognize it, allowing the user to log in and obtain the access token. + +Run this command to log in and get the access token. + +```bash +curl -X 'POST' \ + 'http://localhost:9980/realms/my-realm/protocol/openid-connect/token' \ + -d "grant_type=password" \ + -d "client_id=admin-cli" \ + -d "username=alice" \ + -d "password=1234" +``` + +Make sure to use the correct username and password. +Special attention on the `client_id`; this should be the actual `client_id` of the frontend application that logs the user in. +For this tutorial, it is OK to use `admin-cli`. + +Example token response (some fields omitted for readability) + +```json +{ + "access_token": "eyJhbGciOi...7ocDHofUDQ", + "refresh_token": "eyJhbGciOi...otsEEi4eQA", + ... +} +``` + +### 3. Check the existing wallets + +Right after the account is registered, no permission should be associated with it. +Listing wallets on it should return empty results. + +```bash +curl -X 'GET' \ + 'http://localhost:8080/prism-agent/wallets' \ + -H 'Authorization: Bearer eyJhbGciOi...7ocDHofUDQ' \ + -H 'Accept: application/json' +``` + +Use the correct `access_token` in the previous command's Authorization header. + +Response Example: + +```json +{ + "self": "/wallets", + "kind": "WalletPage", + "pageOf": "/wallets", + "contents": [] +} +``` + +### 4. Create a new wallet + +Create a wallet using a `POST /wallets` endpoint. +This wallet will be a container for the tenant's assets (DIDs, VCs, Connections, etc.). +The Agent can provide or randomly generate the wallet seed during wallet creation. + +If the user already has the wallet associated, the wallet creation will fail as multiple wallets per tenant are not yet allowed. + +```bash +curl -X 'POST' \ + 'http://localhost:8080/prism-agent/wallets' \ + -H 'Authorization: Bearer eyJhbGciOi...7ocDHofUDQ' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -d '{ + "seed": "c9994785ce6d548134020f610b76102ca1075d3bb672a75ec8c9a27a7b8607e3b9b384e43b77bb08f8d5159651ae38b98573f7ecc79f2d7e1f1cc371ce60cf8a", + "name": "my-wallet" + }' +``` + +Response Example: + +```json +{ + "id": "99734c87-5c9d-4697-b5fd-dea4e9590ba7", + "name": "my-wallet", + "createdAt": "2023-01-01T00:00:00Z", + "updatedAt": "2023-01-01T00:00:00Z" +} +``` + +In this step, the agent creates both wallet resource and UMA permission on Keycloak, assigning the new wallet to the user who created it. + +### 5. Perform a simple action to verify access to PRISM Agent + +Without further operation, the wallet should be available for the tenant. +To prove that the tenant can access the wallet, list the DIDs using RPT in the `Authorization` header. + +```bash +curl --location --request GET 'http://localhost:8080/prism-agent/did-registrar/dids' \ + -H 'Authorization: Bearer eyJhbGciOi...7ocDHofUDQ' \ + -H 'Accept: application/json' +``` + +The wallet was successfully created, but it currently does not contain any DIDs - indicated by an empty list and a 200 status. +The tenant should only perform interactions within the scope of this wallet. diff --git a/docs/docusaurus/multitenancy/tenant-onboarding.md b/docs/docusaurus/multitenancy/tenant-onboarding.md index f1695560b1..0c085cdf43 100644 --- a/docs/docusaurus/multitenancy/tenant-onboarding.md +++ b/docs/docusaurus/multitenancy/tenant-onboarding.md @@ -9,8 +9,8 @@ while tenants are users who engage in standard SSI interactions with the PRISM A In tenant management, there are 2 roles: -1. System administrator -2. Tenant +1. [Administrator](/docs/concepts/glossary#administrator) +2. [Tenant](/docs/concepts/glossary#tenant) ## Prerequisites diff --git a/docs/docusaurus/sidebars.js b/docs/docusaurus/sidebars.js index 388eadb21b..670e4e26c4 100644 --- a/docs/docusaurus/sidebars.js +++ b/docs/docusaurus/sidebars.js @@ -91,7 +91,10 @@ const sidebars = { type: 'category', label: 'Multi-Tenancy', items: [ - 'multitenancy/tenant-onboarding' + 'multitenancy/tenant-onboarding', + 'multitenancy/tenant-onboarding-ext-iam', + 'multitenancy/tenant-onboarding-self-service', + 'multitenancy/tenant-migration', ] } ]