hawkbit/docs/authorization.md

Authorization

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 Spring security authorities.

However, keep in mind that hawkBit does not offer an off the shelf authentication provider to leverage these permissions and the underlying multi user/tenant capabilities of hawkBit but it supports authentication providers offering an OpenID Connect interface. Check out Spring security documentation for further information. In hawkBit SecurityAutoConfiguration is a good starting point for integration.

The default implementation is single user/tenant with basic authentication and the logged-in user is provided with all permissions. Additionally, the application properties may be configured for multiple static users; see Multiple Users for details.

---

DDI API

An authenticated target is permitted to:

• retrieve commands from the server
• provide feedback to the the server
• download artifacts that are assigned to it

A target might be permitted to download artifacts without authentication (if enabled, see above). Only the download can be permitted to disable the authentication. This can be used in scenarios where the artifacts itself are e.g. signed and secured.

---

Management API

Multiple Users

hawkBit optionally supports configuring multiple static users through the application properties. In this case, the user and password Spring security properties are ignored. An example configuration is given below.

hawkbit.security.user.admin.password={noop}admin
hawkbit.security.user.admin.firstname=Test
hawkbit.security.user.admin.lastname=Admin
hawkbit.security.user.admin.email=admin@test.de
hawkbit.security.user.admin.permissions=ALL

hawkbit.security.user.test.password={noop}test
hawkbit.security.user.test.firstname=Test
hawkbit.security.user.test.lastname=Tester
hawkbit.security.user.test.email=test@tester.com
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 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 this blog post for more information on password encoders in Spring Security.

OpenID Connect

HawkBit supports authentication providers which use the OpenID Connect standard, an authentication layer built on top of the OAuth 2.0 protocol. OIDC integration can be enabled on UI and in server:

• Hawkbit UI — redirects users to an OIDC provider for authentication
• Hawkbit Management Server — validates JWT bearer tokens on Management API requests

Hawkbit UI

Enable OIDC login for the UI and register the provider using standard Spring Boot OAuth2 client properties:

# Enable hawkBit OIDC UI login
hawkbit.server.security.oauth2.client.enabled=true

# Register the provider (replace "myidp" with any name)
spring.security.oauth2.client.provider.myidp.issuer-uri=https://idp.example.com/
spring.security.oauth2.client.registration.myidp.client-id=my-client-id
spring.security.oauth2.client.registration.myidp.client-secret=my-client-secret
spring.security.oauth2.client.registration.myidp.scope=openid,email,profile
spring.security.oauth2.client.registration.myidp.provider=myidp

Some providers (e.g. Auth0) require additional parameters in the authorization request. Use additional-query-string-params to pass them:

# Add extra parameters to the OAuth2 authorization request
hawkbit.server.security.oauth2.client.additional-query-string-params.audience=https://my-api-audience

Spring Security automatically sets the redirect_uri for the authorization code callback. It constructs the value as:

{baseUrl}/login/oauth2/code/myidp

This URL must be registered as an allowed redirect URI in your identity provider (IdP).

Hawkbit Management Server

Enable JWT bearer token validation for the Management REST API:

# Enable hawkBit default JWT resource server
hawkbit.server.security.oauth2.resourceserver.enabled=true
    
# JWK issuer URI for token signature verification
spring.security.oauth2.resourceserver.jwt.issuer-uri=https://idp.example.com/

hawkBit maps JWT claims to the username, tenant, and permissions of the authenticated user. The claim paths are configurable and support dot-notation for nested claims (e.g. resource_access.my-client.roles):

# Claim path for the hawkBit username (default: preferred_username)
hawkbit.server.security.oauth2.resourceserver.jwt.claim.username=preferred_username

# Claim path for hawkBit roles/permissions (default: roles)
hawkbit.server.security.oauth2.resourceserver.jwt.claim.roles=roles

# Claim path for the hawkBit tenant (default: DEFAULT)
hawkbit.server.security.oauth2.resourceserver.jwt.claim.tenant=tenant

To allow HTTP Basic authentication alongside OAuth2:

hawkbit.server.security.allow-http-basic-on-o-auth-enabled=true

Swagger UI

To enable OAuth2 authorization from Swagger UI, configure the authorization and token endpoints:

springdoc.oauth-flow.authorizationUrl=https://idp.example.com/oauth2/authorize
springdoc.oauth-flow.tokenUrl=https://idp.example.com/oauth2/token

Swagger UI automatically sets the redirect_uri when initiating the authorization flow. It constructs the value as:

{window.location.origin}{base-path}/swagger-ui/oauth2-redirect.html

This URL must be registered as an allowed redirect URI in your identity provider (IdP) configuration.

Permissions

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 tags
  • Target actions
  • Target registration rules
  • Bulk operations
  • Target filters
• READ/UPDATE/CREATE/DELETE_SOFTWARE_MODULE for:
  • Software Module types
• READ/UPDATE/CREATE/DELETE_SOFTWARE_MODULE for:
  • Software Modules
  • Artifacts
• READ/UPDATE/CREATE/DELETE_DISTRIBUTION_SET_TYPE for
  • Distribution Set types
• READ/UPDATE/CREATE/DELETE_DISTRIBUTION_SET for:
  • Distribution sets
  • DS tags
• DOWNLOAD_REPOSITORY_ARTIFACT
  • Permission to download artifacts of a software module (Note: READ_REPOSITORY allows only to read the metadata).
• READ_TARGET_SECURITY_TOKEN
  • 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
  • Permission to read/administrate the tenant settings.
• READ/UPDATE/CREATE/DELETE/HANDLE/APPROVE_ROLLOUT for:
  • Managing rollouts and provision targets through a rollout

Permission Matrix for example uses cases that need more than one permission

Use Case	Needed permissions
Search targets by installed or assigned distribution set	READ_DISTRIBUTION_SET, READ_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_DISTRIBUTION_SET, READ_TARGET, READ_ROLLOUT, CREATE_ROLLOUT, HANDLE_ROLLOUT
Read Rollout status including its deployment groups	READ_DISTRIBUTION_SET, 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.

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 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:

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:

hawkbit.acm.access-controller.target.enabled=false

---

Device Management Federation API

The provided RabbitMQ vhost and user should be provided with the necessary permissions to send messages to hawkBit through the exchange and receive messages from it through the specified queue.