Bosch IoT Rollouts

ACL - HTTP API

Table of contents:

As we already covered, Sign & Encrypt defines specific permission for the different signing and encryption-related actions, such as creating and modifying ACL rules.

By default, only the initial admin can use the ACL API.

Find more information on what access rights are needed for which operation at S&E Access Control Lists.

The ACL API allows you to orchestrate the access control list e.g. to add users who are allowed to create device configurations, to view the audit log etc.

Get all configured ACL rule entries

This call will return all ACL rule entries - device configuration, ACL and audit log-related.

  1. Open the endpoint GET /api/v1/acl.

  2. Click Try it out.

  3. Fill in the tenant header in the X-SE-TENANT field.

  4. Click Execute.

  5. A successful response with 200 code will return all configured ACL rule entries.
    The role from IdM/OAuth2 client id is listed as the "id" of "subject", under "resource" you find the information about a specific resource, and as "action" you will find the granted permissions for this resource.

Get all available subjects part of your current token

This call will return all IdM roles, contained in your OAuth token.

  1. Open the endpoint GET /api/v1/acl/subjects.

  2. Click Try it out.

  3. Fill in the tenant header in the X-SE-TENANT field.

  4. Click Execute.

  5. A successful response with 200 code will return all available subjects of your current login token.
    From the response you can copy the exact IdM role and, for example, use it when creating a device configuration.

Get all device config-related ACL rule entries

This call will return all DeviceConfig-related ACL rules, to which the current logged in user has access to.

  1. Open the endpoint GET /api/v1/acl/subjects/rules.

  2. Click Try it out.

  3. Fill in the tenant header in the X-SE-TENANT field.

  4. Click Execute.

  5. A successful response with 200 code will return all configured ACL rule entries.

Create an ACL rule for a device configuration

Allows you to specify a set of rules e.g. who is able to use a specific DeviceConfig, and who can just view it.

  1. Open the endpoint POST /api/v1/acl/deviceconfigs/{configId}/actions/{action}.

  2. Click Try it out.

  3. Fill in the configId.

  4. As action select the appropriate permissions that you need e.g. VIEW, EDIT, CREATE, APPROVE, USE.

  5. Fill in the tenant header in the X-SE-TENANT field.

  6. Fill in the Request body with:

    1. the IdM role or the Client ID as "id",

      You can copy the Client ID of your OAuth2 client or the IdM role from the response of an GET /api/v1/acl/subjects call.

    2. "GROUP" (when authenticating with an IdM role) or "CLIENT" (when authenticating with an OAuth2 client) as "type".

  7. Click Execute.

  8. A successful response with 201 code will mean that you successfully created the rule.

Create an ACL rule for global resource operations

Allows you to specify a set of global rules - for all device configurations

  1. Open the endpoint POST /api/v1/acl/resources/{resourceType}/actions/{action}.

  2. Click Try it out.

  3. As resourceType choose DEVICE_CONFIG, ACL or AUDIT_LOG depending on the resource that you want this rule to affect.

  4. As action select the appropriate permissions that you need e.g. VIEW, EDIT, CREATE, APPROVE, USE.

  5. Fill in the tenant header in the X-SE-TENANT field.

  6. Fill in the Request body with:

    1. the IdM role or the Client ID as "id",

      You can copy the Client ID of your OAuth2 client or the IdM role from the response of an GET /api/v1/acl/subjects call.

    2. "GROUP" (when authenticating with an IdM role) or "CLIENT" (when authenticating with an OAuth2 client) as "type".

  7. Click Execute.

  8. A successful response with 201 code will mean that you successfully created the rule.

Delete ACL rules

You have four DELETE endpoints at your disposal for different use cases.

  1. Depending whether you want to delete one, all or a filtered number of ACL rules open one of the following endpoints:

    • DELETE/api/v1/acl/deviceconfigs/{configId}- to delete all ACL rules for a specific device configuration.

    • DELETE/api/v1/acl/deviceconfigs/{configId}/subjects/{subject} - to delete all ACL rules for a device configuration, that matches a specific subject.

    • DELETE/api/v1/acl/deviceconfigs/{configId}/subjects/{subject}/actions/{action} - to delete a specific ACL rule.

    • DELETE/api/v1/acl/resources/{resourceType}/subjects/{subject}/actions/{action} - to delete a resource-type scoped ACL rule.

  2. Click Try it out.

  3. Fill in the respective input fields, which depending on the endpoint may be:

    • configId - the id of the device configuration.

    • subject - the subject, part of the ACL rule. Must follow the format: type: name.

    • action - the permissions that you want to delete e.g. VIEW, EDIT, CREATE, APPROVE, USE.

    • resourceType - the type of resource addressed by the ACL rule e.g. DEVICE_CONFIG, ACL, AUDIT_LOG.

  4. Fill in the tenant header in the X-SE-TENANT field.

  5. Click Execute.

  6. A successful response with 200 code will mean that you successfully deleted the rule(s).