diff --git a/documentation/docs/atala-prism/prism-cloud-agent/authentication.md b/documentation/docs/atala-prism/prism-cloud-agent/authentication.md index faeff50a0..4b4ef7898 100644 --- a/documentation/docs/atala-prism/prism-cloud-agent/authentication.md +++ b/documentation/docs/atala-prism/prism-cloud-agent/authentication.md @@ -114,13 +114,24 @@ The PRISM Cloud Agent utilizes the following Keycloak features: the [ADR](https://staging-docs.atalaprism.io/adrs/adr/20230527-use-keycloak-and-jwt-tokens-for-authentication-and-authorisation-to-facilitate-multitenancy-in-cloud-agent/) - Authentication with JWT Token using [token exchange](https://www.keycloak.org/docs/latest/securing_apps/index.html#_token-exchange) +- Authorization with `roles` claim supporting both Keycloak [RealmRole](https://www.keycloak.org/docs/latest/server_admin/#proc-creating-realm-roles_server_administration_guide) and [ClientRole](https://www.keycloak.org/docs/latest/server_admin/#con-client-roles_server_administration_guide) - Authorization with JWT Token and RPT according to [authorization services](https://www.keycloak.org/docs/latest/authorization_services/index.html#authorization-services) based on [UMA 2.0 specification](https://docs.kantarainitiative.org/uma/wg/rec-oauth-uma-grant-2.0.html#:~:text=This%20specification%20defines%20a%20means,a%20resource%20owner%20authorizes%20access.) and [ADR](https://staging-docs.atalaprism.io/adrs/adr/20230926-use-keycloak-authorisation-service-for-managing-wallet-permissions/) -When the JWT Token authentication is enabled, it includes protection for all multi-tenant endpoints of the Cloud Agent. +When the JWT Token authentication is enabled, it includes protection for all multi-tenant and administrative endpoints of the Cloud Agent. +Two mechanisms get utilized in JWT authorization: + +1. __Role-based authorization__ + It implements this [ADR](https://staging-docs.atalaprism.io/adrs/adr/20240103-use-jwt-claims-for-agent-admin-auth/), which can authorize both the administrator and tenant role. + Each role is allowed to operate on different parts of the Agent + Administrators are permitted to oversee the wallet management, while tenants are allowed to utilize the wallet and engage in SSI interactions. + +2. __UMA resource permission__ + When the role is tenant, the Agent must know which wallet the tenant can access. +The UMA permission model is employed to configure the tenant's permissions for the wallet. ### Sequence Diagrams @@ -171,6 +182,21 @@ sequenceDiagram Agent-->>User: 11. Returns Result ``` +### Role-based authorization + +The Agent has a simple mechanism for role-based authorization. +It expects the JWT to include a `roles` claim in the payload, identifying the role such as `admin` or `tenant`. +The user must belong to one of these roles but not both. If unspecified, the Agent infers the `tenant` role. +The location of the `roles` claim is also configurable, allowing flexible IAM configuration. +As a result, the Agent can support both Keycloak `RealmRoles` and `ClientRoles` based on the configuration. +Using the environment variable, set the path as: `KEYCLOAK_ROLES_CLAIM_PATH`. + +If Keycloak `RealmrRole` is used, follow this [instruction](https://www.keycloak.org/docs/latest/server_admin/#proc-creating-realm-roles_server_administration_guide) on Keycloak +and the `KEYCLOAK_ROLES_CLAIM_PATH` should be set to `realm_access.roles`. + +If Keycloak `ClientRole` is used, follow this [instruction](https://www.keycloak.org/docs/latest/server_admin/#con-client-roles_server_administration_guide) on Keycloak +and the `KEYCLOAK_ROLES_CLAIM_PATH` should be set to `resource_access..roles`. + ### UMA permission configuration The current authorization logic is built on the UMA specification, configuring permissions as user A controls resource W. In this model, user A is a registered user in Keycloak, and wallet W is a resource registered in Keycloak. diff --git a/documentation/docs/atala-prism/prism-cloud-agent/environment-variables.md b/documentation/docs/atala-prism/prism-cloud-agent/environment-variables.md index 422b59f13..c326c04cf 100644 --- a/documentation/docs/atala-prism/prism-cloud-agent/environment-variables.md +++ b/documentation/docs/atala-prism/prism-cloud-agent/environment-variables.md @@ -2,62 +2,62 @@ The following enviroment variables can be used to configure Prism Agent: -| Variable Name | Description | Type | Default | -|--------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|---------------------------| -| POLLUX_DB_HOST | Hostname of the server where Pollux database is running on. | String | localhost | -| POLLUX_DB_PORT | Port of the Pollux database. | Int | 5432 | -| POLLUX_DB_NAME | Database name where Pollux db will store data. | String | pollux | -| POLLUX_DB_USER | Pollux database username for login. | String | postgres | -| POLLUX_DB_PASSWORD | Pollux database password for login. | String | postgres | -| ISSUE_BG_JOB_RECORDS_LIMIT | Maximum number of records issue credentials job will try to process at the same time. | Int | 25 | -| ISSUE_BG_JOB_RECURRENCE_DELAY | Interval at which issue credentials job will try to process records. | String | 2 seconds | -| ISSUE_BG_JOB_PROCESSING_PARALLELISM | Maximum amount of parallel issue credential job processings. | Int | 5 | -| PRESENTATION_BG_JOB_RECORDS_LIMIT | Maximum number of records present proof job will try to process at the same time. | Int | 25 | -| PRESENTATION_BG_JOB_RECURRENCE_DELAY | Interval at which present proof job will try to process records. | String | 2 seconds | -| PRESENTATION_BG_JOB_PROCESSING_PARALLELISM | Maximum amount of parallel present proof job processings. | Int | 5 | -| CONNECT_DB_HOST | Hostname of the server where connection flow database is running on. | String | localhost | -| CONNECT_DB_PORT | Port of the connection flow database. | String | 5432 | -| CONNECT_DB_NAME | Database name where connection flow db will store data. | String | connect | -| CONNECT_DB_USER | Connection flow database username for login. | String | postgres | -| CONNECT_DB_PASSWORD | Connection flow database password for login. | String | postgres | -| CONNECT_BG_JOB_RECORDS_LIMIT | Maximum number of records connect job will try to process at the same time. | Int | 25 | -| CONNECT_BG_JOB_RECURRENCE_DELAY | Interval at which connect job will try to process records. | String | 2 seconds | -| CONNECT_BG_JOB_PROCESSING_PARALLELISM | Maximum amount of parallel connect job processings. | Int | 5 | -| CONNECT_INVITATION_EXPIRY | Time leeway when accepting the connection invitation, the inviter should only accept responses if they are received within the specified time limit before expiry. | String | 300 seconds | -| AGENT_HTTP_PORT | Port on which prism agent runs. | Int | 8085 | -| DIDCOMM_SERVICE_URL | URL of the DIDcomm server that also runs for this agent. | String | http://localhost:8090 | -| AGENT_DB_HOST | Hostname of the server where prism agent database is running on. | String | localhost | -| AGENT_DB_PORT | Port of the prism agent database. | Int | 5432 | -| AGENT_DB_NAME | Database name where agent db will store data. | String | agent | -| AGENT_DB_USER | Agent database username for login. | String | postgres | -| AGENT_DB_PASSWORD | Agent database password for login. | String | postgres | -| CREDENTIAL_VERIFY_SIGNATURE | Whether or not to verify a credential signature. | Boolean | true | -| CREDENTIAL_VERIFY_DATES | Whether or not to verify credential dates (expiration). | Boolean | false | -| CREDENTIAL_LEEWAY | Time leeway when verifying credential dates, if time difference is less than a leeway, it will still verify. | String | 0 seconds | -| PRESENTATION_VERIFY_SIGNATURE | Whether or not to verify a signed challenge used during credential presentation. | Boolean | true | -| PRESENTATION_VERIFY_DATES | Whether or not to verify challenge dates during presentation. | Boolean | false | -| PRESENTATION_VERIFY_HOLDER_BINDING | Description missing (please provide). | Boolean | false | -| PRESENTATION_LEEWAY | Time leeway when verifying challenge dates. | String | 0 seconds | -| SECRET_STORAGE_BACKEND | Secret storage for keys and credentials. If vault is used, the vault server must be running, otherwise a database can be used for development purposes only. | Enum(vault, postgres) | vault | -| VAULT_ADDR | URL of the vault service for prism agent to use for secret management. | String | http://localhost:8200 | -| VAULT_TOKEN | Vault service auth token. | String | root | -| ADMIN_TOKEN | Admin token for the admin API key authentication method. | String | admin | -| API_KEY_SALT | Salt used to hash the API key. | String | JLXTS4J2qkMOgfO8 | -| API_KEY_ENABLED | Whether or not to enable API key authentication. | Boolean | true | -| API_KEY_AUTHENTICATE_AS_DEFAULT_USER | Whether or not to authenticate all API keys as the default user. | Boolean | false | -| API_KEY_AUTO_PROVISIONING | Whether or not to enable auto-provisioning for API keys and register the owner of the api-key automatically. | Boolean | true | -| WEBHOOK_PARALLELISM | Maximum number of events that will be retrieved in a single iteration, from the event queue by the webhook publisher. | Int | Null | -| GLOBAL_WEBHOOK_URL | The global webhook endpoint URL where the notifications will be sent. | String | Null | -| GLOBAL_WEBHOOK_API_KEY | The optional API key (bearer token) to use as the Authorization header for global wallet webhook. | String | Null | -| DEFAULT_WALLET_ENABLED | Whether or not to initialize the default wallet. | String | true | -| DEFAULT_WALLET_SEED | The BIP32 wallet seed to be used for default wallet represented by a hexadecimal string. | String | Null | -| DEFAULT_WALLET_WEBHOOK_URL | The default wallet webhook endpoint URL where the notifications will be sent. | String | Null | -| DEFAULT_WALLET_WEBHOOK_API_KEY | The optional API key (bearer token) to use as the Authorization header for default wallet webhook. | String | Null | -| DEFAULT_WALLET_AUTH_API_KEY | The authentication API key to be used for default entity that uses default wallet. | String | default | -| KEYCLOAK_ENABLED | Whether or not to enable Keycloak authentication and authorisation. | Boolean | false | -| KEYCLOAK_URL | The Keycloak server URL. | String | http://localhost:9980 | -| KEYCLOAK_REALM | The Keycloak realm name. | String | `atala-demo` | -| KEYCLOAK_CLIENT_ID | The Keycloak client ID. | String | `prism-agent` | -| KEYCLOAK_CLIENT_SECRET | The Keycloak client secret. | String | `prism-agent-demo-secret` | -| KEYCLOAK_UMA_AUTO_UPGRADE_RPT | Whether or not to enable automatic upgrade of RPT tokens. If disabled, `accessToken` must be RPT and include the permission claims. | Boolean | true | - +| Variable Name | Description | Type | Default | +|--------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|----------------------------------------------| +| POLLUX_DB_HOST | Hostname of the server where Pollux database is running on. | String | localhost | +| POLLUX_DB_PORT | Port of the Pollux database. | Int | 5432 | +| POLLUX_DB_NAME | Database name where Pollux db will store data. | String | pollux | +| POLLUX_DB_USER | Pollux database username for login. | String | postgres | +| POLLUX_DB_PASSWORD | Pollux database password for login. | String | postgres | +| ISSUE_BG_JOB_RECORDS_LIMIT | Maximum number of records issue credentials job will try to process at the same time. | Int | 25 | +| ISSUE_BG_JOB_RECURRENCE_DELAY | Interval at which issue credentials job will try to process records. | String | 2 seconds | +| ISSUE_BG_JOB_PROCESSING_PARALLELISM | Maximum amount of parallel issue credential job processings. | Int | 5 | +| PRESENTATION_BG_JOB_RECORDS_LIMIT | Maximum number of records present proof job will try to process at the same time. | Int | 25 | +| PRESENTATION_BG_JOB_RECURRENCE_DELAY | Interval at which present proof job will try to process records. | String | 2 seconds | +| PRESENTATION_BG_JOB_PROCESSING_PARALLELISM | Maximum amount of parallel present proof job processings. | Int | 5 | +| CONNECT_DB_HOST | Hostname of the server where connection flow database is running on. | String | localhost | +| CONNECT_DB_PORT | Port of the connection flow database. | String | 5432 | +| CONNECT_DB_NAME | Database name where connection flow db will store data. | String | connect | +| CONNECT_DB_USER | Connection flow database username for login. | String | postgres | +| CONNECT_DB_PASSWORD | Connection flow database password for login. | String | postgres | +| CONNECT_BG_JOB_RECORDS_LIMIT | Maximum number of records connect job will try to process at the same time. | Int | 25 | +| CONNECT_BG_JOB_RECURRENCE_DELAY | Interval at which connect job will try to process records. | String | 2 seconds | +| CONNECT_BG_JOB_PROCESSING_PARALLELISM | Maximum amount of parallel connect job processings. | Int | 5 | +| CONNECT_INVITATION_EXPIRY | Time leeway when accepting the connection invitation, the inviter should only accept responses if they are received within the specified time limit before expiry. | String | 300 seconds | +| AGENT_HTTP_PORT | Port on which prism agent runs. | Int | 8085 | +| DIDCOMM_SERVICE_URL | URL of the DIDcomm server that also runs for this agent. | String | http://localhost:8090 | +| AGENT_DB_HOST | Hostname of the server where prism agent database is running on. | String | localhost | +| AGENT_DB_PORT | Port of the prism agent database. | Int | 5432 | +| AGENT_DB_NAME | Database name where agent db will store data. | String | agent | +| AGENT_DB_USER | Agent database username for login. | String | postgres | +| AGENT_DB_PASSWORD | Agent database password for login. | String | postgres | +| CREDENTIAL_VERIFY_SIGNATURE | Whether or not to verify a credential signature. | Boolean | true | +| CREDENTIAL_VERIFY_DATES | Whether or not to verify credential dates (expiration). | Boolean | false | +| CREDENTIAL_LEEWAY | Time leeway when verifying credential dates, if time difference is less than a leeway, it will still verify. | String | 0 seconds | +| PRESENTATION_VERIFY_SIGNATURE | Whether or not to verify a signed challenge used during credential presentation. | Boolean | true | +| PRESENTATION_VERIFY_DATES | Whether or not to verify challenge dates during presentation. | Boolean | false | +| PRESENTATION_VERIFY_HOLDER_BINDING | Description missing (please provide). | Boolean | false | +| PRESENTATION_LEEWAY | Time leeway when verifying challenge dates. | String | 0 seconds | +| SECRET_STORAGE_BACKEND | Secret storage for keys and credentials. If vault is used, the vault server must be running, otherwise a database can be used for development purposes only. | Enum(vault, postgres) | vault | +| VAULT_ADDR | URL of the vault service for prism agent to use for secret management. | String | http://localhost:8200 | +| VAULT_TOKEN | Vault service auth token. | String | root | +| ADMIN_TOKEN | Admin token for the admin API key authentication method. | String | admin | +| API_KEY_SALT | Salt used to hash the API key. | String | JLXTS4J2qkMOgfO8 | +| API_KEY_ENABLED | Whether or not to enable API key authentication. | Boolean | true | +| API_KEY_AUTHENTICATE_AS_DEFAULT_USER | Whether or not to authenticate all API keys as the default user. | Boolean | false | +| API_KEY_AUTO_PROVISIONING | Whether or not to enable auto-provisioning for API keys and register the owner of the api-key automatically. | Boolean | true | +| WEBHOOK_PARALLELISM | Maximum number of events that will be retrieved in a single iteration, from the event queue by the webhook publisher. | Int | Null | +| GLOBAL_WEBHOOK_URL | The global webhook endpoint URL where the notifications will be sent. | String | Null | +| GLOBAL_WEBHOOK_API_KEY | The optional API key (bearer token) to use as the Authorization header for global wallet webhook. | String | Null | +| DEFAULT_WALLET_ENABLED | Whether or not to initialize the default wallet. | String | true | +| DEFAULT_WALLET_SEED | The BIP32 wallet seed to be used for default wallet represented by a hexadecimal string. | String | Null | +| DEFAULT_WALLET_WEBHOOK_URL | The default wallet webhook endpoint URL where the notifications will be sent. | String | Null | +| DEFAULT_WALLET_WEBHOOK_API_KEY | The optional API key (bearer token) to use as the Authorization header for default wallet webhook. | String | Null | +| DEFAULT_WALLET_AUTH_API_KEY | The authentication API key to be used for default entity that uses default wallet. | String | default | +| KEYCLOAK_ENABLED | Whether or not to enable Keycloak authentication and authorisation. | Boolean | false | +| KEYCLOAK_URL | The Keycloak server URL. | String | http://localhost:9980 | +| KEYCLOAK_REALM | The Keycloak realm name. | String | `atala-demo` | +| KEYCLOAK_CLIENT_ID | The Keycloak client ID. | String | `prism-agent` | +| KEYCLOAK_CLIENT_SECRET | The Keycloak client secret. | String | `prism-agent-demo-secret` | +| KEYCLOAK_UMA_AUTO_UPGRADE_RPT | Whether or not to enable automatic upgrade of RPT tokens. If disabled, `accessToken` must be RPT and include the permission claims. | Boolean | true | +| KEYKLOAK_ROLES_CLAIM_PATH | The json path to the `roles` claim in the JWT payload . Used for role-based authorization (e.g. admin or tenant). | String | `resource_access..roles` |