How to manage member user permissions (provider account) through the 3scale API?

Solution Unverified - Updated

Environment

  • Red Hat 3scale API Management
    • SaaS
    • 2.X On-premises

Issue

  • We want to automate creation of users for the provider account via API. The creation itself is easily made but we want to configure access rights as well. Setting the User to Member is documented, but setting the detailed access rights is not documented. How can this be achieved with the 3scale Account Management API?
  • Is it possible to get the information about member permissions via API?

Resolution

SaaS

The following endpoints are available for managing member user permissions ({id} is the member user ID):

  • User Permissions Read GET /admin/api/users/{id}/permissions.xml
  • User Permissions Update PUT /admin/api/users/{id}/permissions.xml

Note: The feature is available in SaaS since December 12th, 2018. See Red Hat 3scale API Management SaaS Release Notes for updates on this and other features.

Request

The User Permissions Update accepts the following parameters:

  • access_token – should be a Read & Write Access Token with Account Management API scope. Only users with full admin permissions are allowed to update other users' permissions, so the access token should belong to an full admin.
  • allowed_sections – the list of the allowed admin sections. The possible values are:
    • portal – Developer Portal
    • finance – Billing
    • settings – Settings
    • partners – Developer Accounts -- Applications
    • monitoring – Analytics
    • plans – Integration & Application Plans
  • allowed_service_ids – the list of the allowed service IDs.

The parameters allowed_sections and allowed_service_ids need to be passed in the body encoded as query string array. Multiple values can be passed in one request.

For example, to enable Billing and Analytics sections for services with IDs 123 and 567, for the admin member user with id 890 the corresponding curl command will be:

curl -v -X PUT "https://<ADMIN_PORTAL_URL>/admin/api/users/890/permissions.xml" -d 'access_token=<ACCESS_TOKEN>&allowed_sections%5B%5D=finance&allowed_sections%5B%5D=monitoring&allowed_service_ids%5B%5D=123&allowed_service_ids%5B%5D=567'

where %5B%5D is the URL-encoded [] representing the array.

All sections and service IDs that need to be enabled should be included in the request. The sections or services that are missing in the request will be disabled (in case they were enabled previously).

The invalid allowed_sections and the non-existing allowed_service_ids will be filtered out.

To disable all sections, set allowed_sections to an empty array: allowed_sections%5B%5D=%5B%5D.
To disable all services, set allowed_service_ids to an empty array: allowed_service_ids%5B%5D=%5B%5D.

To enable all services (All current and future APIs), do not provide any value for allowed_service_ids: allowed_service_ids%5B%5D.

If only allowed_service_ids is provided in the request, the allowed sections remain unchanged. Just as if only allowed_sections is provided in the request, the allowed service IDs remain unchanged.

From the UI, if you want to include several allowed_sections use the green "+" to add more fields:

User permission update
User permission update

Response

The response has the following format (corresponds to the example curl command provided in the Request description):

<permissions>
  <user_id>890</user_id>
  <role>member</role>
  <allowed_sections>
    <allowed_section>monitoring</allowed_section>
    <allowed_section>finance</allowed_section>
  </allowed_sections>
  <allowed_service_ids>
    <allowed_service_id>123</allowed_service_id>
    <allowed_service_id>567</allowed_service_id>
  </allowed_service_ids>
</permissions>

A user with no available sections and no available services would be shown as follows:

<permissions>
  <user_id>890</user_id>
  <role>member</role>
  <allowed_sections/>
  <allowed_service_ids/>
</permissions>

The admin users have unlimited access to all sections and all services (All current and future APIs), the admin user's permissions cannot be updated. The response to the User Permissions Read endpoint for an admin user would be as follows:

<permissions>
  <user_id>70</user_id>
  <role>admin</role>
  <allowed_sections>
    <allowed_section>portal</allowed_section>
    <allowed_section>finance</allowed_section>
    <allowed_section>settings</allowed_section>
    <allowed_section>partners</allowed_section>
    <allowed_section>monitoring</allowed_section>
    <allowed_section>plans</allowed_section>
  </allowed_sections>
</permissions>

Note that if all services (All current and future APIs) are enabled, the field allowed_service_ids does not appear in the response.

On-premises – all versions from 2.1 to 2.4 inclusive

The functionality to update the member permissions is available through the Account Management API, however it is not documented.

The API endpoint that needs to be used for setting member user permissions is User Update (provider account).

The access permissions need to be passed in the body encoded as query string array, the parameter for the portal sections is member_permission_ids, and the parameter for the services is member_permission_service_ids.

Possible values for the member_permission_ids are:

  • portal – Developer Portal
  • finance – Billing
  • settings – Settings
  • partners – Developer Accounts -- Applications
  • monitoring – Analytics
  • plans – Integration & Application Plans

The values for the member_permission_service_ids parameter must be the service IDs.

So, for example, for enabling Billing, and Analytics for services with IDs 123 and 567, for the provider user with id 890 the corresponding curl command will be:

curl -v -X PUT "https://<ADMIN_PORTAL_URL>/admin/api/users/890.xml" -d 'access_token=<ACCESS_TOKEN>&member_permission_ids%5B%5D=finance&member_permission_ids%5B%5D=monitoring&member_permission_service_ids%5B%5D=123&member_permission_service_ids%5B%5D=567'

%5B%5D stands for [] – this is the array representation.

Note: All the settings that need to be enabled should be included in the request. The settings that are missing in the request will be disabled (in case they were enabled previously).

Currently it is not possible to get the information about member permissions through the 3scale Account Management API. A Request for Feature Enhancement (RFE) has been raised for adding this feature, in can be tracked in the following JIRA issue: Content from issues.jboss.org is not included.THREESCALE-484.

SBR
Product(s)
Category
Tags

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.