How To Use RBAC

This document is meant to give quick instructions for using RBAC with Fugue as an administrator and as a user. For a detailed walkthrough, see Using the RBAC Feature.

For Administrators

If you’re the Fugue administrator at your organization, you have access to the root user. The root user has access to all subjects and all actions, and may attach, detach, or download the policy on the Conductor. Before other users can use Fugue, the root user must write a policy that declares other users and then explicitly gives those users access in the form of rules, since access is implicitly denied except for root. As an administrator, you may wish to create a named user with all the permissions of root and only use root itself when necessary.

Creating and Applying Policies

Writing Rules in Ludwig

A policy is a Ludwig composition that is applied to the Conductor and governs how users interact with Fugue. This composition uses types from the Fugue.System.Policy library to form rules, which are the keystone of the Fugue RBAC system.

Each rule must have three items:

  • A principal
  • An action
  • A subject

An example of a rule is “Alice (principal) can run processes (action) in the web account (subject).”

Boilerplate Ludwig

Because a policy is a composition, it requires a composition keyword. You’ll also want to import the Fugue.System.Policy library. (Note: Fugue run will accept an RBAC policy composition or even a mixture of RBAC and standard library types, but it will have no effect.)


import Fugue.System.Policy as Policy
Defining Users and Accounts

When we say user, we mean an RBAC principal who is using Fugue (like root or alice). When we say account, we mean an RBAC subject defined in the Conductor’s account table, which corresponds to a cloud provider account (like web or prod).

To create a user, first declare them in the policy, like so:

alice: Policy.User {userId: "alice"}

You can declare an account in much the same way, using either the accountId itself, or an alias (you can locate the account alias in the “Name” column field in fugue account list).

With accountId:

web: Policy.Account {accountId: "web-1483061704854"}

With alias and accountName:

web: Policy.NamedAccount {accountName: "web"}

Make sure if you choose to use the account ID, you provide it exactly as it is known in the Conductor’s account table. This is not the provider account number, but the Account ID as assigned to the account when you registered it with fugue account add (see account). You can find it again with fugue account list.

Note: When issuing a fugue status command the appended Fugue IDs are not displayed. Use fugue status --verbose to view complete account name details including the appended Fugue IDs.

Defining a Rule with Principals, Subjects, and Actions

This binding creates the example rule we mentioned earlier, “Alice can run processes in the web account”:

aliceCanRunInWeb: Policy.Rule {
  principal: alice,
  subject: Policy.AccountType(web),
  action: Policy.AccountAction(Policy.AccountRunProcess)

Rules can also be written at the process level. For example, the following lines define the Process helloWorld (aliased “HelloWorld” in Fugue) and create the rule, “Alice can check status on the HelloWorld process”:

Policy.Process helloWorld: Policy.AliasedProcess {alias: "HelloWorld"}

aliceCanGetStatusHelloWorld: Policy.Rule {
  principal: alice,
  subject: Policy.ProcessType(helloWorld),
  action: Policy.ProcessAction(Policy.ProcessGetStatus)

There are many more examples of rules and rule-returning functions in Fugue.System.Policy.

Special Values

Ludwig has some special values that can make writing rules easier. For example, you can use the AllAccounts constructor shown below to write rules giving Bob read-only access to all accounts (after first declaring bob as a user, of course). The accountRules helper function returns a list of rules so you don’t have to write each one individually.

bob: Policy.User {userId: "bob"}

readOnlyAccountRules: Policy.accountRules {
  principals: [bob],
  accounts: [Policy.AllAccounts],
  actions: [

In addition to AllAccounts are several other special values, including:

For more information about writing rules, see Fugue.System.Policy.

Process vs. Account Privileges

As explained in “How It Works”, access for non-root users is implicitly denied and no actions can be taken unless explicitly expressed. Fugue’s RBAC configuration is built around defining rules rather than restrictions.

For example, the process aliceCanGetStatusHelloWorld defines a process-specific RBAC rule that enables alice to check on a process status. If this is the only rule applied to the user alice that is the only process she can perform actions for. Any other processes would require additional rules specifying the expanded permissions.

However, if you were to apply two rules for the user alice:

  • the first specifying the process rule aliceCanGetStatusHelloWorld, allowing the user alice to check on a process status,
  • and the second, an account rule aliceCanGetStatusInAccount providing alice with access to view status on an entire account

In this scenario the second rule is an expansion or superset of the previous rule, thus allowing alice to view the status of all processes within the specified account.

Applying the Policy

The policy won’t take effect until you attach it to the Conductor. You can do that with the fugue policy rbac-attach command:

fugue policy rbac-attach MyPolicy.lw

Enabling the User By Generating a Secret

Once the policy has been applied, you can enable your users by generating a secret, or access token, for each. The fugue policy generate-secret command does the trick:

fugue policy generate-secret alice

Updating a Policy

To update a policy, simply edit it and run the fugue policy rbac-attach command again:

fugue policy rbac-attach MyPolicy.lw

Detaching a Policy

Should you need to detach a policy for any reason, you can use the fugue policy rbac-detach command:

fugue policy rbac-detach

See also Remove Existing RBAC Policy With A Blank Policy.

Reattaching a Policy

To reattach a policy you attached previously simply use fugue policy rbac-attach --reattach.

If you reattach a policy you should see the following output.

$ fugue policy rbac-attach --reattach
Requesting the Conductor reattach the detached policy
[ DONE ] Policy has been reattached.

Note: In this scenario there is no reason to include the <policy_file> since these details are stored on the Conductor and will be reapplied once the --reattach flag is issued.

Switching Users

To issue commands as a different user, Fugue enables switching between users by issuing the fugue user set command.

For ease of switching users, it’s a best practice to keep each user in a separate profile.

To switch to a user under a different profile, use the fugue user set --profile <profile> <user> <secret> command. The following command switches the active user to the alice user in the alice profile:

$ fugue user set --profile alice alice 2UNtNQfL2YVnewpasswordnewpassword12345=

[ INFO ] This operation will overwrite profile 'alice' in /Users/main/credentials

[ WARN ] Are you sure you want to proceed? [y/N]: y

[ DONE ] The user has been set to 'alice'

Another option, instead of fugue user set, allows you to manually switch users by simply adding each user and secret to your credentials file and commenting out the inactive user lines with a hash symbol.


# secret = 2UNtNQfL2YVnewpasswordnewpassword12345=
# user = alice

user = root
secret = IyUYAVQX4fH278newpasswordnewpassword12345=

Note: To switch back to root or another previous user you will need to retain the user and secret information for that specific user.

In the event you lose your root credentials, refer to the Troubleshooting section on using Fugue’s reset secret command.

RBAC Delegation

In addition to the ability to switch users, RBAC also supports applying policy to enable users to perform actions as other users.

For example, if you have a CI/CD tool that you want to use to drive Fugue, but still need to maintain attribution of the users that committed the code or performed the job. The --do-as flag enables these permissions while tracking the attribution of commands.

The functionality is available as a global flag --do-as for any Fugue command. For example fugue --do-as <user> <command>. It is enabled by delegating permissions within a policy; for example bob having permissions to act as alice. In addition, delegation will be specified as part of the fugue history command any time the --do-as flag is used.

For example, if bob acts as alice:

Type    Started    Work             User     Done As     Last Job Id       Last Updated    Status     Description
------  ---------  --------------   ------   ---------   ----------------  --------------  ---------  --------------
Job     1:04pm     SYSTEM                                1510255486 (162)  2:24pm          SUCCEEDED  JobSucceeded
Job     1:03pm     RESUME                                1510250614 (1)    1:03pm          SUCCEEDED  JobSucceeded
Event   1:03pm     FUGUE RESUME     bob      alice                                         SUCCEEDED  EventReceived
Event   1:01pm     FUGUE SUSPEND    bob      alice                                         SUCCEEDED  EventReceived
Job     1:01pm     SYSTEM                                1510250509 (1)    1:01pm          HALTED     HaltedBySignal
Job     12:59pm    SYSTEM                                1510250464 (5)    1:01pm          SUCCEEDED  JobSucceeded
Job     12:58pm    RUN                                   1510250317 (1)    12:58pm         SUCCEEDED  JobSucceeded
Event   12:58pm    FUGUE RUN        alice    alice                                         SUCCEEDED  EventReceived

Once this policy is applied, both alice and bob will have their individual permissions, and bob will be able to use the --do-as flag to perform actions as alice, as specified in the policy.

To explore this functionality in greater detail, check out an example here.


When the Conductor is uninstalled, the RBAC policy is removed along with all users and their credentials. If you reinstall the Conductor with install, you’ll need to apply the policy again with policy rbac-attach, and root will have a new user secret.

For Users

If an administrator has given you a user name and a secret, they have written you into the policy attached to the Conductor. Your access to Fugue is governed by the rules in this policy, and because access is implicitly denied in the Fugue RBAC system, there must be an explicit rule for each action you’re permitted to take. Your administrator should make you aware of these actions.

Assuming a User ID

Once you have your user ID and user secret, issue the fugue user set <user_id> <user_secret> command like so:

fugue user set alice /Ddz3GV1gcroh2/fvMVkem4EXAMPLEXAMPLEEXAMPLE

Only one user may be active at a time. To change between users simply issue the fugue user set command.


Do not lose your root credentials. They cannot be replaced with the policy generate-secret command. If you have lost your root credentials, see the reset-secret command or contact