Compare capabilities

Helper method to compare capabilities across two groups (of capabilities) to find which are missing from the first.

Note

Capabilities that are no longer in use by the API will be ignored. These have names prefixed with Legacy and all inherit from the base class LegacyCapability. If you want to check for these, you must do so manually.

Tip

If you just want to check against your existing capabilities, you may use the helper method client.iam.verify_capabilities instead.

Parameters:

existing_capabilities (ComparableCapability) – List of existing capabilities.
desired_capabilities (ComparableCapability) – List of wanted capabilities to check against existing.
project (str | None) – If a ProjectCapability or ProjectCapabilityList is passed, we need to know which CDF project to pull capabilities from (existing might be from several). If project is not passed, and ProjectCapabilityList is used, it will be inferred from the AsyncCogniteClient used to call retrieve it via token/inspect.

Returns:

A flattened list of the missing capabilities, meaning they each have exactly 1 action, 1 scope, 1 id etc.

Return type:

list[Capability]

Examples

Ensure that a user’s groups grant access to read- and write for assets in all scope, and events write, scoped to a specific dataset with id=123:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.capabilities import AssetsAcl, EventsAcl
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> my_groups = client.iam.groups.list(all=False)
>>> to_check = [
...     AssetsAcl(
...         actions=[AssetsAcl.Action.Read, AssetsAcl.Action.Write],
...         scope=AssetsAcl.Scope.All(),
...     ),
...     EventsAcl(
...         actions=[EventsAcl.Action.Write],
...         scope=EventsAcl.Scope.DataSet([123]),
...     ),
... ]
>>> missing = client.iam.compare_capabilities(
...     existing_capabilities=my_groups, desired_capabilities=to_check
... )
>>> if missing:
...     pass  # do something

Capabilities can also be passed as dictionaries:

>>> to_check = [
...     {"assetsAcl": {"actions": ["READ", "WRITE"], "scope": {"all": {}}}},
...     {"eventsAcl": {"actions": ["WRITE"], "scope": {"datasetScope": {"ids": [123]}}}},
... ]
>>> missing = client.iam.compare_capabilities(
...     existing_capabilities=my_groups, desired_capabilities=to_check
... )

You may also load capabilities from a dict-representation directly into ACLs (access-control list) by using Capability.load. This will also ensure that the capabilities are valid.

>>> from cognite.client.data_classes.capabilities import Capability
>>> acls = [Capability.load(cap) for cap in to_check]