IMS Permissions and Scopes
Each IMS permission is made up of a series of verbs describing the level of permissions, and a path describing the resource over which permissions has been granted.
The available verbs are:
Some example paths would be:
org/my-organization-idfor access over an organization.
prj/my-project-id/image_manager/image_metadatafor access to the image metadata in the IMS Image Manager service for a given project.
The path is split into path parts separated by the
An example of a full IMS permission would be
giving read and write access to an organization.
The permissions reqiured for a given API call should be documented within the relevant IMS service API documentation.
Verbs support the
[*] wildcard providing a shorthand equivalent to
* wildcard can be applied at the end of a path to match the given root
upto that point. Any path parts beyond the wildcard will be considered a match.
+ wildcard can be included in the place of a path part to match anything
The IMS wildcards allow permissions to be granted across groups of projects or groups of services. Read more in the OAuth Scopes guide as to how wildcards can be used.
Some examples including wildcards:
[*]:prj/my-project-id/*for full access to a given project.
[*]:prj/+/image_manager/image_metadatafor access to all image metadata in the IMS Image Manager for all projects.
[*]:prj/+/image_manager/*for full all access to the IMS Image Manager for all projects.
OAuth Clients are created with a set of permissions that restrict the access a
given OAuth Client can request. Typically, OAuth Clients created for a given
organization will be restricting to only requesting access for projects with the
organization. For example, an organization containing three projects
(project-one, project-two, project-three) could have an OAuth Client created
with the following permission set:
[*]:prj/project-one/* [*]:prj/project-two/*. Applications using this OAuth Client will only be to
access these two projects, and not project-three nor projects in another
In addition to the permissions specified at creation time, you also specify
OAuth Scopes when exchanging Refresh Tokens or generating Authorization Codes.
For IMS Platform Auth these OAuth Scopes match our IMS permissions. Most
commonly you would specify
[*]:* as the Scopes for your authorization requests
and token exchanges. Returned tokens will then contain all permissions available
to the user that are subsets of OAuth Client permissions (which were specified
at the time of client creation).
You may wish to have different Scopes for security or separation of concerns.
For example, specifying a scope of
[*]:prj/my-project-id/* during token
exchange limits the calling application to that project, and it couldn’t
mistakenly tamper with other projects (regardless of the OAuth Client’s
permission set at time of creation).
Furthering this example, an OAuth Client that specifies
[*]:prj/my-project-id/image_manager/image_metadata will only be able to access
the image metadata from the IMS Image Manager service for a single project.
This is very safe as the application cannot accidentally perform actions outside
the target scope, but it is not flexible. Compare this permission to
former will allow the application to access image metadata for every project the
user has access to, the latter will allow the application access to everything
within a project that the user has access to. Choosing the right Scopes for an
application is a balancing act between safety/security and flexibility.
The OIDC specification places restrictions on what Scopes are supported. As
such, there are three supported Scopes for OIDC:
openid is required. It switches the server into OIDC mode and ensures that an
ID Token is returned.
offline_access is optional. It tells the service to generate a Refresh Token,
in the same way specifying
generate_access_token=true in any exchange does.
The two approaches work together, specifying either or both will generate a
ims.improbable.io/permissions is optional. It tells the service to include the
user's permissions directly in the ID Token. You should check the documentation
of the API you are trying to call to decide whether to specify this scope or