Performing Actions as Different Users

By default, the actions executed by a run of a flow are authenticated as the user who initiated the run. In some cases, flow authors may want to switch users during execution, allowing the flow to provide limited and controlled access to resources where the calling user does not have permissions.

Flow authors can use the RunAs field to define such changes in authentication.

RunAs Definition

RunAs is a property of an Action state and cannot be used on other state types. It declares the user whose credentials should be used for that Action.

RunAs may be specified as "User" (the default), "Flow", or as the name of a user-defined role.

When "RunAs": "User" is used or RunAs is unspecified, the Action will be run using credentials belonging to the user who started the run.

When "RunAs": "Flow" is used, the Action will run using credentials belonging to the flow itself. Every flow's identity matches its id, so the "Flow ID" field shown in the Globus CLI or app.globus.org can be used to set permissions for the flow.

When RunAs is any string other than "User" or "Flow", it is the name of a credential, and the user who starts the run must pass tokens to Globus Flows which match that RunAs value as part of the flow input. For example, a flow author may specify "RunAs": "AdminUser", and users who run that flow will be required to pass tokens in their input under the name "AdminUser". The tokens provided by the runner will be used for such an Action state, and the exact convention for passing these credentials is described below.

Providing Role-Specific Tokens

When RunAs specifies a role name, corresponding tokens must be generated and provided to the flow at run-time. The necessary information to generate any Globus Auth token is the name of the scope to which the token should be generated. So that generated tokens are as specific as possible, the flows service creates a separate scope for each role which appears as part of a RunAs property. These scope strings are present in the flow description under the property globus_auth_scopes_by_RunAs. This will be a JSON object with the property names matching the roles named in RunAs and the values being the Globus Auth scope string. For example, if roles named Admin and Curator were present in the flow definition, the flow description would contain an object like:

{
  "Admin": "<Globus Auth Scope String for Admin>",
  "Curator": "Globus Auth Scope String for Curator>"
}

When invoking the flow (e.g. via globus flows start) the flow input would be required to contain the access tokens for each of the roles in a similar JSON object called _tokens as follows:

{
  "_tokens": {
    "Admin": "<Globus Auth access token for Admin>",
    "Curator": "Globus Auth access token for Curator>"
  }
}

Note

If the author of a flow provides an input_schema for their flow, the schema should specify that the _tokens property should be present with this structure. Otherwise, the Flows service will reject the input prior to running the flow.

Generating the required tokens is beyond the scope of this document. Doing so requires that developers build on top of the Globus Auth API.

Look Up the Flow Identity

The most common usage for RunAs is "RunAs": "Flow", to allow specific steps in a flow to execute as the Flow itself. This lets administrators assign permissions to the flow and use the flow as a controlled method of access.

Adding permissions for a flow requires use of the flow's identity. Depending on the application, you may need the identity ID, the identity username, or a principal URN containing the identity ID.

A flow's ID matches its identity ID, so the identity ID is "${FLOW_ID}".

The username for a flow is always a clients.auth.globus.org username of the form "${FLOW_ID}@clients.auth.globus.org".

The principal URN for a flow is therefore always of the form "urn:globus:auth:identity:${FLOW_ID}".

The Flows API provides these values, allowing users to easily retrieve them. For example, this globus CLI command gets all three values in a JSON array for the flow with ID 72e219c4-cad5-410f-b99f-4767fb12b61c:

$ globus flows show 72e219c4-cad5-410f-b99f-4767fb12b61c --jq '[id,globus_auth_username,principal_urn]'
[
  "72e219c4-cad5-410f-b99f-4767fb12b61c",
  "72e219c4-cad5-410f-b99f-4767fb12b61c@clients.auth.globus.org",
  "urn:globus:auth:identity:72e219c4-cad5-410f-b99f-4767fb12b61c"
]