Protecting Secrets
At times, portions of a flow state may need to be secret or protected from the various operations, like status and log, which can be used to monitor and observe the state of a flow execution.
For example, some actions may require credentials or keys to authenticate or permit access.
These items should not be visible to some users, particularly when they are encoded (e.g. in Parameter constants) by the flow author.
There are two areas where these values may be stored or encoded: in Parameters
to actions, and within the state of the flow at run-time.
The service provides mechanisms for protecting information in both cases.
For Parameters
, a list with special property name __Private_Parameters
may be placed in the Parameters
object indicating which other Parameters
should be protected.
These values will be protected in two ways:
-
Users that lookup the flow in the service will not see the
Parameters
which are specified in the__Private_Parameters
list unless they have theflow_administrator
orflow_owner
role on the flow. -
When the state of a run of the flow is returned, values for these
Parameters
will not be returned in the status or log of the flow’s execution.
For simplicity, the values in the __Private_Parameters
list may include the "simple" name even when the parameter name is a Reference or Expression.
For example, if a parameter value has the form "SecretValue.$": "$.Path.To.Secret"
the value in the __Private_Parameters
list may be simply SecretValue
omitting the trailing .$
which identifies the parameter as a reference.
Similarly, for expression parameters, the trailing .=
may be omitted.
The __Private_Parameters
list may be applied at any nesting level of the Parameters.
Thus, in the following Parameters
definition:
{
"Parameters": {
"server_info": {
"URL": "https://example.com",
"user_name": "FlowUser",
"password": "my_password",
"__Private_Parameters": [
"password"
]
}
}
}
The password
property within the server_info
object would be omitted from output of any state of the flow retrieved by any user.
To protect the state of the flow’s run-time, any property which starts with the prefix _private
will be omitted from flow introspection.
Thus, if protected values need to be stored within the flow state, they could be stored in a property with a name like _private_secret_property
or in an object simply having the name _private
as that object, starting with the prefix will entirely be omitted from the output.
As an example, the following flow state would not be visible:
{
"_private": {
"user_name": "FlowUser",
"password": "my_password"
}
}
However, the properties MAY still be referenced as part of a reference path such as in an Action parameter.
Thus, the reference path $._private.password
could be used and the value my_password
would be used for the parameter.
In such a case, that parameter would also most likely need to appear in the __Private_Parameters
list to prevent the value from being shown when the state of the particular action is displayed to a user.
Thus, the state protection via _private
property names and the enumeration of protected parameters via __Private_Parameters
will often be used in tandem.