Skip to main content

IMS Permissions and Scopes

IMS Permissions

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:

  • (r)ead
  • (w)rite
  • (g)rant

Some example paths would be:

  • org/my-organization-id for access over an organization.
  • prj/my-project-id/image_manager/image_metadata for 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 / character.

An example of a full IMS permission would be [r,w]:org/my-organization-id, 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.

Wildcard Permissions

Verbs support the [*] wildcard providing a shorthand equivalent to [r,w,g].

The * 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.

The + wildcard can be included in the place of a path part to match anything in place.

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_metadata for 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 Scopes

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 organization.

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 [*]:prj/+/image_manager/image_metadata and [*]:prj/my-project-id/*. The 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.

OIDC Scopes

The OIDC specification places restrictions on what Scopes are supported. As such, there are three supported Scopes for OIDC: openid, offline_access, and ims.improbable.io/permissions.

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 Refresh Token.

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 not.