Roles

Roles#

Many services map different sets of actions to different platform or service roles. In some cases, you may want to combine multiple roles’ actions to meet your custom use case. With a custom role, you can select the actions required for your use case, making it easier to grant the right access level to a particular service rather than assigning multiple roles to accomplish the same task. The SDK provides functionality for interacting with roles on the watsonx.data integration platform.

This includes operations such as:

  • Creating custom roles

  • Listing roles

  • Updating custom roles

  • Deleting custom roles

Creating custom roles#

Any number of actions for a single service can be mapped to the new role, but there must be at least one service-defined action to successfully create the new role.

In the UI, you can add a new custom role by going to Manage -> Access (IAM) -> Manage access -> Create. You can set the Name, Id, Description, Service, and Actions for your custom role.

Screenshot of the Role creation in the UI Screenshot of the Role creation form in the UI

To create a new custom role using the SDK, call the Platform.create_role() method with the name, display_name, service_name, and actions parameters. You can also provide an optional description parameter. The name parameter must start with a capital letter, be no longer than 30 characters, and must not contain spaces. For more information about roles and actions, see IAM roles and actions.

>>> new_role = platform.create_role(
...     name='MyNewRole',
...     service_name='iam-groups',
...     display_name='New Role',
...     actions=['iam-groups.groups.update']
... )
>>> new_role
Role(display_name='New Role', role_type='custom_role', actions=['iam-groups.groups.update'])

Note

This method may raise a requests.exceptions.HTTPError with status code 409 if a role with the same name or display_name, or an identical set of actions, already exists.

Listing roles#

To retrieve system, service, and custom roles, use the Platform.roles property.

>>> platform.roles
[..., Role(display_name='New Role', role_type='custom_role', actions=['iam-groups.groups.update'])...]
You can filter roles by using the Platform.roles.get_all() method on the Platform.roles property and providing any of the following arguments:

  • role_id: The role ID.

  • service_name: The name of the IAM-enabled service.

  • source_service_name: The name of the source IAM-enabled service.

  • policy_type: The type of policy.

  • service_group_id: The ID of the service group.

>>> platform.roles.get_all(role_type='custom_role')
[...Role(display_name='New Role', role_type='custom_role', actions=['iam-groups.groups.update'])]

Updating custom roles#

In the UI, you can update a custom role by clicking the three dots next to it and then selecting Edit.

Screenshot of the Role update button in the UI

To update a role using the SDK, first retrieve it by using the Platform.roles property. Next, make in-memory changes to the object and pass it to the Platform.update_role() method.

>>> new_role.display_name='updated display name'
>>> new_role.description='updated description'
>>> new_role.actions=['iam-groups.groups.create']
>>> platform.update_role(new_role)
<Response [200]>
>>> updated_role = platform.roles.get(role_id=new_role.id)
>>> updated_role
Role(display_name='updated display name', role_type='custom_role', actions=['iam-groups.groups.create'])

Note

You can modify display_name, description, or the actions mapped to the role. The name, account_id, and service_name cannot be changed.

Note

This method may raise a requests.exceptions.HTTPError with status code 409 if a role with either the same display_name or an identical set of actions already exists.

Deleting custom roles#

In the UI, you can delete a custom role by clicking the three dots next to it and then selecting Delete.

Screenshot of the Role deletion button in the UI

To delete a role using the SDK, first retrieve it by using the Platform.roles property. Then, pass the object to the Platform.delete_role() method.

>>> platform.delete_role(updated_role)
<Response [204]>
Section Contents