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>"
}
}
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.