lingwei.kong/hawkbit
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

Fix and extend permissions related doc (#2762)

Browse Source 
Signed-off-by: Avgustin Marinov <Avgustin.Marinov@bosch.com>
This commit is contained in:
Avgustin Marinov
2025-10-20 08:47:34 +03:00
committed by GitHub
parent b10955f3eb
commit f2ddbcc230
1 changed files with 91 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
docs/authorization.md
View File

@@ -1,4 +1,5 @@
# Authorization # Authorization
Authorization is handled separately for _Direct Device Integration (DDI) API_ and _Device Management Federation (DMF) Authorization is handled separately for _Direct Device Integration (DDI) API_ and _Device Management Federation (DMF)
API_ (where successful authentication includes full authorization) and _Management API_ and _UI_ which is based on API_ (where successful authentication includes full authorization) and _Management API_ and _UI_ which is based on
Spring Spring
@@ -31,13 +32,14 @@ secured.
--- ---
## Management API and UI ## Management API
### Multiple Users ### Multiple Users
hawkBit optionally supports configuring multiple static users through the application properties. In this case, the user hawkBit optionally supports configuring multiple static users through the application properties. In this case, the user
and password Spring security properties are ignored. and password Spring security properties are ignored.
An example configuration is given below. An example configuration is given below.
```properties ```properties
hawkbit.security.user.admin.password={noop}admin hawkbit.security.user.admin.password={noop}admin
hawkbit.security.user.admin.firstname=Test hawkbit.security.user.admin.firstname=Test
@@ -51,6 +53,7 @@ hawkbit.security.user.test.lastname=Tester
hawkbit.security.user.test.email=test@tester.com hawkbit.security.user.test.email=test@tester.com
hawkbit.security.user.test.permissions=READ_TARGET,UPDATE_TARGET,CREATE_TARGET,DELETE_TARGET hawkbit.security.user.test.permissions=READ_TARGET,UPDATE_TARGET,CREATE_TARGET,DELETE_TARGET
``` ```
A permissions value of `ALL` will provide that user with all possible permissions. Passwords need to be specified with A permissions value of `ALL` will provide that user with all possible permissions. Passwords need to be specified with
the used password encoder in brackets. In this example, `noop` is used as the plaintext encoder. For production use, it the used password encoder in brackets. In this example, `noop` is used as the plaintext encoder. For production use, it
is recommended to use a hash function designed for passwords such as *bcrypt*. See is recommended to use a hash function designed for passwords such as *bcrypt*. See
@@ -62,51 +65,116 @@ information on password encoders in Spring Security.
hawkbit supports authentication providers which use the OpenID Connect standard, an authentication layer built on top of hawkbit supports authentication providers which use the OpenID Connect standard, an authentication layer built on top of
the OAuth 2.0 protocol. the OAuth 2.0 protocol.
An example configuration is given below. An example configuration is given below.
```properties ```properties
spring.security.oauth2.client.registration.oidc.client-id=clientID spring.security.oauth2.client.registration.oidc.client-id=clientID
spring.security.oauth2.client.provider.oidc.issuer-uri=https://oidc-provider/issuer-uri spring.security.oauth2.client.provider.oidc.issuer-uri=https://oidc-provider/issuer-uri
spring.security.oauth2.client.provider.oidc.jwk-set-uri=https://oidc-provider/jwk-set-uri spring.security.oauth2.client.provider.oidc.jwk-set-uri=https://oidc-provider/jwk-set-uri
``` ```
Note: at the moment only DEFAULT tenant is supported. By default the resource_access/<client id>/roles claim is mapped Note: at the moment only DEFAULT tenant is supported. By default the resource_access/<client id>/roles claim is mapped
to hawkBit permissions. to hawkBit permissions.
### Delivered Permissions ### Permissions
- READ_/UPDATE_/CREATE_/DELETE_TARGET for: #### Basics
hawkBit uses fine-grained permissions to restrict scopes to the managed entities. The main concept in permissions are:
1. Permission group - a management API usually has a `permission group` correspondent to the managed entity type. For
instance Target Management's `permission group` is `TARGET` while Software Module Management's is `SOFTWARE_MODULE`.
2. Permission action (CRUD and special) - `CREATE`, `READ`, `UPDATE`, `DELETE` as well `HANDLE` and `APROVE` for
Rollouts Management. The permissions are the formed with `<action>_<group>` pattern - e.g. `CREATE_TARGET`,
`READ_SOFTWARE_MODULE`
3. Permission scope - permissions could be scoped further with RSQL filter scopes. I.e. one could restrict
`CREATE_TARGET` permissions with a scope, e.g. `type.id==[permissions.md](permissions.md)1`. Then, the final
authority that will be granted to user will be `<permission>/<scope>`, e.g. `CREATE_TRAGET/type.id==1`. If the
permission is not scoped the authority will be just `<permission>`, e.g. `CREATE_TRAGET`. By default, scope support
is disabled!
### Permission groups list
- READ/UPDATE/CREATE/DELETE_TARGET for:
- Target types
- READ/UPDATE/CREATE/DELETE_TARGET for:
- Target entities including metadata (that includes also the installed and assigned distribution sets) - Target entities including metadata (that includes also the installed and assigned distribution sets)
- Target tags - Target tags
- Target actions - Target actions
- Target registration rules - Target registration rules
- Bulk operations - Bulk operations
- Target filters - Target filters
- READ/UPDATE/CREATE/DELETE_SOFTWARE_MODULE for:
- READ_/UPDATE_/CREATE_/DELETE_REPOSITORY for: - Software Module types
- Distribution sets - READ/UPDATE/CREATE/DELETE_SOFTWARE_MODULE for:
- Software Modules - Software Modules
- Artifacts - Artifacts
- READ/UPDATE/CREATE/DELETE_DISTRIBUTION_SET_TYPE for
- Distribution Set types
- READ/UPDATE/CREATE/DELETE_DISTRIBUTION_SET for:
- Distribution sets
- DS tags - DS tags
- DOWNLOAD_REPOSITORY_ARTIFACT - DOWNLOAD_REPOSITORY_ARTIFACT
- Permission to download artifacts of a software module (Note: READ_REPOSITORY allows only to read the metadata). - Permission to download artifacts of a software module (Note: READ_REPOSITORY allows only to read the metadata).
- READ_TARGET_SECURITY_TOKEN - READ_TARGET_SECURITY_TOKEN
- Permission to read the target security token. The security token is security concerned and should be protected. - Permission to read the target security token. The security token is security concerned and should be protected.
- READ/UPDATE/CREATE/DELETE_TENANT_CONFIGURATION/TENANT_CONFIGURATION
- READ_TENANT_CONFIGURATION/TENANT_CONFIGURATION
- Permission to read/administrate the tenant settings. - Permission to read/administrate the tenant settings.
- READ/UPDATE/CREATE/DELETE/HANDLE/APPROVE_ROLLOUT for:
- READ_/UPDATE_/CREATE_/DELETE_/HANDLE_/APPROVE_ROLLOUT for: - Managing rollouts and provision targets through a rollout
- Managing rollouts and provision targets through a rollout.
### Permission Matrix for example uses cases that need more than one permission ### Permission Matrix for example uses cases that need more than one permission
| Use Case | Needed permissions | | Use Case | Needed permissions |
|----------------------------------------------------------------------------|----------------------------------------------------------------------------| |----------------------------------------------------------------------------|----------------------------------------------------------------------------------|
| Search _targets_ by installed or assigned _distribution set_ | READ_REPOSITORY, READ_TARGET | | Search _targets_ by installed or assigned _distribution set_ | READ_DISTRIBUTION_SET, READ_TARGET |
| Assign _DS_ to a _target_ | READ_REPOSITORY, UPDATE_TARGET | | Assign _DS_ to a _target_ | READ_DISTRIBUTION_SET, UPDATE_TARGET |
| Assign DS to target through a _Rollout_, i.e. _Rollout_ creation and start | READ_REPOSITORY, READ_TARGET, READ_ROLLOUT, CREATE_ROLLOUT, HANDLE_ROLLOUT | | Assign DS to target through a _Rollout_, i.e. _Rollout_ creation and start | READ_DISTRIBUTION_SET, READ_TARGET, READ_ROLLOUT, CREATE_ROLLOUT, HANDLE_ROLLOUT |
| Read _Rollout_ status including its _deployment groups_ | READ_REPOSITORY, READ_ROLLOUT | | Read _Rollout_ status including its _deployment groups_ | READ_DISTRIBUTION_SET, READ_ROLLOUT |
| Checks _targets_ inside _Rollout deployment group_ | READ_REPOSITORY, READ_TARGET, READ_ROLLOUT | | Checks _targets_ inside _Rollout deployment group_ | READ_DISTRIBUTION_SET, READ_TARGET, READ_ROLLOUT |
#### Coarse Access Control
All sensitive operation of the management APIs are protected with permission checks. The permission checks are done with
Spring Security's `@PreAuthorize` annotation, mostly using a `hasPermission` which allows handling more complex the user
authorities. The permission evaluation is handled by a custom `PermissionEvaluator` registered
by [org.eclipse.hawkbit.repository.RepositoryConfiguration](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-repository/hawkbit-repository-core/src/main/java/org/eclipse/hawkbit/repository/RepositoryConfiguration.java).
These `@PreAuthorize` annotations ensures that only the users with required permissions will be able to call the
management methods.
#### Fine-grained Access Control - Access Controller
Further there is a concept of `Access Controller` which could provide further restrictions on the managed entities. If
the user have access to a management method, i.e. has the required permissions, his access to the entities could be
restricted by registered `Access Controller` for the management service. The `Access Controller` is a typed Spring
component which
implements [org.eclipse.hawkbit.acm.access.AccessController](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-repository/hawkbit-repository-jpa/src/main/java/org/eclipse/hawkbit/repository/jpa/acm/AccessController.java)
interface.
Out of the box hawkBit provides `Access Controller` implementations for:
* Target Management - `target`
* Target Type Management - `target-type`
* Software Module Management - `software-module`
* Software Module Type Management - `software-module-type`
* Distribution Set Management - `distribution-set`
* Distribution Set Type Management - `distribution-set-type`
* Action Management - `action`
By default, hawkbit doesn't support scopes. To enable scopes a Spring property `hawkbit.acm.access-controller.enabled`
shall be set to `true`. E.g. add in `application.properties`:
```properties
hawkbit.acm.access-controller.enabled=true
```
By default, if you have enabled scopes, all supported Access Controllers will be registered. If you want to disable it
for a specific service, you could set a property `hawkbit.acm.access-controller.<service>.enabled` to `false`. E.g. to
disable it for Target Management:
```properties
hawkbit.acm.access-controller.target.enabled=false
```
--- ---
@@ -114,4 +182,4 @@ to hawkBit permissions.
The provided _RabbitMQ_ [vhost and user](https://www.rabbitmq.com/access-control.html) should be provided with the The provided _RabbitMQ_ [vhost and user](https://www.rabbitmq.com/access-control.html) should be provided with the
necessary permissions to send messages to hawkBit through the exchange and receive messages from it through the necessary permissions to send messages to hawkBit through the exchange and receive messages from it through the
specified queue. specified queue.