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

composition

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.

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: [
    Policy.AccountStatusProcess,
    Policy.AccountHistoryProcess
  ]
}

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

  • allAccountTableActions, which allows the user to execute the account commands;
  • allRBACActions, which allows the user to execute the policy commands;
  • allAccountActions, which gives the user full read/write access to the Conductor process table and effectively makes them a superuser;
  • AllUsers, which is a global principal affecting all users;
  • and AllSubjects, a global subject that allows the user access to all accounts, RBAC metadata, and the Conductor’s account table.

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.

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.

[default-93512345-us-east-1]

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

Uninstalling

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.

Warning

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 support@fugue.co.