Using the RBAC Feature

Overview

This example shows you how to manage a simple composition as another user with Fugue’s RBAC feature.

Prerequisites

You’ll need to have the Fugue CLI set up and the Conductor installed before you can run this example. If you haven’t done so yet, it just takes a few quick steps.

You’ll also need to be running a Team Conductor, not a Basic Conductor, since the Team Conductor offers the full RBAC feature.

What We’ll Do In This Example

We’ll cover how to write Ludwig to make an RBAC policy creating users and rules governing those users. We’ll also discuss how to apply the policy, switch users, and run and kill a composition as another user.

What We’ll Have When We’re Done

We’ll be using the HelloWorld.lw composition from Hello World, Part 2: Fugue Basics, so we’ll create the same infrastructure: a Virtual Private Cloud (VPC) in AWS, complete with tags.

How Long It Will Take

About 25 minutes.

Download

You can download the source code for this example from Github:

Save these files to the directory in which you ran fugue init during the Quick Setup.

Get editor plug-ins here.

Let’s Go!

Writing the Policy Composition

First, we need to write the RBAC policy composition. A policy consists of rules that permit users to execute specific Fugue commands on specific accounts.

We’ll start it as we would any other composition – with the composition keyword. We’ll also import the Fugue.System.Policy library.

composition

import Fugue.System.Policy as .

Declaring the Account

This top-level binding tells the Conductor that the account ID we gave it should be known as the default account in this policy.

# Add your default account ID below. You can find this ID by executing
# `fugue account list`.
default: Account(accountId: "fugue-1234567890123")

Action required! We’ll need to find your default account ID in Fugue and replace the ID in the composition. You can do this by executing the following command in the Fugue CLI:

Note: In this example, we are using the default account ID, but you also have the option to use an alias in place of the account ID, e.g. default: Account(accountId: “fugue”). In addition, you can locate the account alias is the “Name” column field in fugue account list.

fugue account list

You’ll see output like this:

Fugue Managed Accounts for main-user/xxxxxxxxxxxx - Wed Jan 25 2017 2:45pm

Name             Account Id           Provider    Provider Id    Credential
---------------  -------------------  ----------  -------------  -----------------------------------------------------------
fugue (default)  fugue-1484673325056  aws         xxxxxxxxxxxx   arn:aws:iam::xxxxxxxxxxxx:role/fugue-FugueIam-1JK290D38FNYT

Find your fugue (default) account – the account in which the Conductor is running – and copy the account ID. In this example, our account ID is fugue-1484673325056.

In your downloaded copy of the composition, paste that account ID next to accountId: to replace fugue-1234567890123. (Don’t forget to keep the double quotes!)

Declaring a User

Now, we need to create a user by declaring it in the policy. We’ll create a user called alice in a top-level binding.

alice: User {userId: "alice"}

Declaring a Rule

A rule is the keystone type of the Fugue RBAC system. Rules are made up of principals, actions, and subjects. A principal is an entity that can be authorized to perform an operation, like a user. An action is an operation a principal can perform, like a Fugue command. A subject is the target of the action, like an account.

Access for non-root users is implicitly denied; in other words, a user cannot take an action unless it is explicitly written in a rule inside an attached policy.

This function returns three rules. We’ll give the binding an illustrative name, aliceLimitedAccessDefault, so we know what the rules do at a glance.

The principals field takes a list of principals – in this case, just the user alice. This will apply to all three rules.

The accounts field takes a list of accounts – in this case, just the default account. This will apply to all three rules.

The actions field takes a list of actions – in this case, we’re declaring a rule allowing alice to run compositions, a rule allowing her to kill processes, and a rule allowing her to check status, but no other actions.

aliceLimitedAccessDefault: accountRules {
          principals: [alice],
          accounts: [default],
          actions:[AccountRunProcess,
                   AccountKillProcess,
                   AccountStatusProcess]}

Applying the Policy

Now that we’ve written our policy, we need to apply it by attaching it to the Conductor. The Conductor will create the new user, and then we’ll enable the user by generating a secret.

We can apply the policy by running this command:

fugue policy rbac-attach Policy.lw

We’ll see output like this:

Compiling Ludwig file Policy.lw ...
[ OK ] Successfully compiled. No errors.

Uploading policy to S3 ...
[ OK ] Successfully uploaded.

Requesting the Conductor set new policy ...
[ DONE ] Policy uploaded and applied.

This means that the Conductor has successfully compiled the policy composition, uploaded it to S3, and applied the policy. That also means that now there’s a shiny new user, alice.

Note: If you see an error about exceeding the max user limit, make sure you’re running a Team Conductor, not a Basic Conductor, and reach out to support@fugue.co.

We can prove alice exists by executing the fugue policy list-users command:

fugue policy list-users

The CLI will output a table like this one:

Fugue User list for main-user/xxxxxxxxxxxx - Wed Jan 25 2017 3:28pm

User Id    Enabled    Created      Updated
---------  ---------  -----------  -----------
alice      no         3:26pm       3:26pm
root       yes        Dec 29 2016  Dec 29 2016

[ HELP ] To enable a user, run "fugue policy generate-secret <user_id>".

There’s alice, and another user – root. The root user is enabled by default, and it’s the one you’re using right now. The root user has access to all actions and all subjects.

Enabling The New User

As you can see, alice is not enabled yet, and the CLI has helpfully informed us how to enable a user: We need to generate a secret, or access token, to authenticate the user. So, let’s get to it:

fugue policy generate-secret alice

The CLI returns the generated user secret and a success message.

[ fugue policy ] Requesting the Conductor generate a secret for: alice ...

User Credential Details:

   User ID: alice
   User Secret: /Ddz3GV1gcroh2/fvMVkem4EXAMPLEXAMPLEEXAMPLE

[ DONE ] Secret successfully generated.

Copy this information somewhere safe! (Hint: credstash works great for this.) Your user secret should be...well, secret.

Backing Up Root Credentials

This part is pretty important. If you open credentials, which is created when you ran fugue install, you’ll see a section that looks like this:

[default-xxxxxxxxxx-us-east-1]
user = root
secret = gIowKW6AnAM4fgBqEXAMPLEEXAMPLEEXAMPLEEXAMPLE=

These are your root credentials.

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.

Now would be an excellent time to back up your root creds somewhere safe. We’re going to need them again later when we switch back to root.

If you run fugue policy list-users again, you’ll see that alice is enabled.

Fugue User list for main-user/xxxxxxxxxxxx - Wed Jan 25 2017 11:00pm

User Id    Enabled    Created      Updated
---------  ---------  -----------  -----------
alice      yes        3:26pm       3:35pm
root       yes        Dec 29 2016  Dec 29 2016

Switching to the New User

To switch to the alice user, we’ll use the user set <user_id> <user_secret> command:

fugue user set alice /Ddz3GV1gcroh2/fvMVkem4EXAMPLEXAMPLEEXAMPLE

Only one user can be active at a time, so you’ll see a warning about overwriting your root credentials, and the CLI will prompt you for confirmation.

[ INFO ] This operation will overwrite profile 'default' in /Users/main-user/credentials

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

Go ahead and hit yif you already backed up your root credentials somewhere!

The CLI will overwrite the existing file and create a new credentials file.

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

If you open the new credentials, you’ll see that the alice user ID and secret are there instead of root. We’ve officially switched users!

Running a Composition

Now that we’re using Fugue as alice, we’re going to run the HelloWorld.lw composition. This simple composition creates a VPC and tags in your AWS account.

fugue run HelloWorld.lw -a HelloWorld

The CLI will return output like this:

[ fugue run ] Running HelloWorld.lw

Run Details:
    Account: default
    Alias: HelloWorld

Compiling Ludwig file /Users/main-user/HelloWorld.lw
[ OK ] Successfully compiled. No errors.


Uploading compiled Ludwig composition to S3...
[ OK ] Successfully uploaded.

Requesting the Conductor to create and run process based on composition ...
[ DONE ] Process created and running.


State    Updated    Created    Account              FID                                   Alias       Last Message
-------  ---------  ---------  -------------------  ------------------------------------  ----------  --------------
Running  9:53pm     9:53pm     fugue-1484673325056  8fb42b6f-1f39-4be6-b9b6-15daf571913d  HelloWorld

[ HELP ] Run the 'fugue status' command to view details and status for all Fugue processes.

As you can see, alice ran the composition in the default account. This action is permitted via the aliceLimitedAccessDefault rule.

So, what happens if alice tries to execute a prohibited command? Let’s try suspending the composition:

fugue suspend -y HelloWorld

Sorry, Alice! The CLI returns an error, as it should.

[ fugue suspend ] Suspending process with Alias: HelloWorld

Requesting the Conductor to suspend process ...
[ ERROR ] Signal Error. 401 - 'Unauthorized': Command 'HALT' is not allowed for Principal 'alice' on Account 'fugue-1484673325056' based on stored Policy.

Let’s switch users again to show how the actions are restored when root is set as the user.

Switching Back to Root

Grab those root credentials you saved and issue a user set command:

fugue user set root gIowKW6AnAM4fgBqEXAMPLEEXAMPLEEXAMPLEEXAMPLE

Now that you’re using Fugue as root again, you can issue that suspend command:

fugue suspend -y HelloWorld

And the CLI successfully suspends our composition.

[ fugue suspend ] Suspending process with Alias: HelloWorld

Requesting the Conductor to suspend process ...
[ DONE ] Process with Alias: HelloWorld is being suspended.

[ HELP ] Run the 'fugue status' command to view details and status of this process suspension.

Ta-dah! You can see that although Fugue prohibited alice from suspending the composition, Fugue permitted the root user to do it, in accordance with the policy set on the Conductor.

Killing the Fugue Process

It’s time to wrap up this walkthrough, so let’s terminate our process with kill:

fugue kill -y HelloWorld

You’ll see output like this:

[ fugue kill ] Killing suspended process with Alias: HelloWorld

Requesting the Conductor to kill suspended composition with Alias: HelloWorld...
[ Done ] The conductor is killing the process with Alias: HelloWorld

You’re all done! You’ve written and applied an RBAC policy, enabled a new user, switched users, and demonstrated how Fugue prohibits or permits actions based on the policy set on the Conductor. Congratulations!

Next Steps

Now that you’re done with this walkthrough, you might want to check out the Adding Users (RBAC) page for more details about RBAC and Fugue. Or, you can read up on the Fugue.System.Policy module in the Fugue Standard Library and try writing your own rules – just remember to switch to root and run rbac-attach again to update the policy. And as always, reach out to support@fugue.co with any questions.