Working with roles

Modified: 22 Nov 2017 17:39 UTC

Roles are lists of users and policies. Roles describe which users are allowed access according to the policies. To allow access to a resource, you associate, or tag, a resource with a role.

The role name administrator is reserved to allow unrestricted access to resources. See The Administrator Role

All of the CLI commands involving roles are subcommands of the sdc-role command.

$ sdc-role help
SmartDC Account Roles

Usage:
    sdc-role [OPTIONS] COMMAND [ARGS...]
    sdc-role help COMMAND

Options:
    -h, -?, --help         Print help and exit.
    --version              Print version and exit.
    -d, --debug            enable debug/verbose mode (default: disabled)
    -a ARG, --account=ARG  account name. Environment: SDC_ACCOUNT=ARG
    -A ARG, --user=ARG     account sub-user login. Environment: SDC_USER=ARG
    -u ARG, --url=ARG      url for SmartDataCenter API. Environment: SDC_URL=ARG
    -k ARG, --keyId=ARG    your ssh key fingerprint. Environment: SDC_KEY_ID=ARG

Commands:
    help (?)        Help on a specific sub-command.
    list            List your Account Roles.
    get             Get an account Role by id.
    create          Creates a new Role for your account.
    update          Updates an account role.
    delete          Removes an account role.

Member lists and default roles

A role has two member lists:

The members list contains all the users who can assume the role. Users in this list must explicitly assume the role.

The default members list contains all the users who assume the role automatically. Users in this list do not need to assume the role explicitly. User in the default members list must also be in the members list.

Here's an example. The contractor role looks like this. The resource ~~/stor/access.log is tagged with this role.

$ sdc-role get 559d4252-d75c-4189-bf08-f30c73a703a6
{
  "name": "contractor",
  "id": "559d4252-d75c-4189-bf08-f30c73a703a6",
  "members": [
    "bob",
    "jill",
    "maria"
  ],
  "default_members": [
    "maria",
    "jill"
  ],
  "policies": [
    "read"
  ]
}

Maria is in the default members list. She can get access.log without specifying the role.

$ mget -q --user=maria \
          --keyId=61:62:35:66:e6:e0:91:6a:fc:dc:d2:1b:90:52:51:04 \
          ~~/stor/access.log | head -2
127.0.0.1 - - [11/Feb/2014:13:31:11 -0500] "GET / HTTP/1.1" 200 2158
127.0.0.1 - - [11/Feb/2014:13:31:18 -0500] "GET /search?q=linux HTTP/1.1" 200 2580

Bob is not in the default members list. If he does not specify a role, he cannot read access.log.

$ mget -q --user=bob \
          --keyId=10:d0:59:ef:4f:71:3b:8b:4b:6a:05:d2:57:24:28:27 \
          ~~/stor/access.log | head -2
mget: NoMatchingRoleTagError: None of your active roles are present on the resource.

But if he explicitly assumes the role, he can get access.log.

$ mget -q --role=contractor \
          --user=bob --keyId=10:d0:59:ef:4f:71:3b:8b:4b:6a:05:d2:57:24:28:27 \
          ~~/stor/access.log | head -2
127.0.0.1 - - [11/Feb/2014:13:31:11 -0500] "GET / HTTP/1.1" 200 2158
127.0.0.1 - - [11/Feb/2014:13:31:18 -0500] "GET /search?q=linux HTTP/1.1" 200 2580

It's important to keep the relationship between members and default members in mind when updating either of these lists.

Creating roles

Use sdc-role create to create a role. You must provide a name to create a role.

$ sdc-role create --name=support
{
  "name": "support",
  "id": "027344ad-8d2e-c767-e81f-b211966bca10",
  "members": [],
  "default_members": [],
  "policies": []
}

Getting information about roles

Use sdc-role list to list all the roles in your account.

$ sdc-role list
[
  {
    "name": "contractor",
    "id": "559d4252-d75c-4189-bf08-f30c73a703a6",
    "members": [
      "jill",
      "maria"
    ],
    "default_members": [
      "maria"
    ],
    "policies": [
      "read",
      "list"
    ]
  },
. . .
]

If you've installed json, you can use this for a quick list of all your roles' names and ids.

$  sdc-role list  | json -a name id
contractor 559d4252-d75c-4189-bf08-f30c73a703a6
manager 38474359-29f9-cf8a-d496-bd06bbda66cf
public-read 94d0d2fc-eeda-4729-d6db-bbd683e249be
support f7b263dc-e22f-e3eb-f40f-84f05de0a76f
ops d314eddf-1397-6a38-a83b-e67614ee095c

Changing role information

Use sdc-role update to change a role's name, members, default members, and policies.

$ sdc-role update 559d4252-d75c-4189-bf08-f30c73a703a6 --policies=read
{
  "name": "contractor",
  "id": "559d4252-d75c-4189-bf08-f30c73a703a6",
  "members": [
    "jill",
    "maria"
  ],
  "default_members": [
    "maria"
  ],
  "policies": [
    "read"
  ]
}

Note that updating a field replaces all the values with the ones you specify in the update command. This has some subtle ramifications when you update members or default members.

To add a member, make sure that you include all of the existing members in the update command.

To add a default member, make sure that you include all of the existing default members and that the members list includes all of the existing members and the new members.

To delete all of the default members use '[]' like this:

$ sdc-role update 559d4252-d75c-4189-bf08-f30c73a703a6 --default-members='[]'
{
  "name": "contractor",
  "id": "559d4252-d75c-4189-bf08-f30c73a703a6",
  "members": [
    "jill",
    "maria"
  ],
  "default_members": [],
  "policies": [
    "read"
  ]
}

Deleting roles

Use sdc-role delete to delete a role.

$ sdc-role delete 027344ad-8d2e-c767-e81f-b211966bca10

The administrator role

The role named administrator is a special role similar to sudo in Unix systems. Any user that assumes the role can do anything that the account owner can do.

As in UNIX, it is recommended that you avoid authenticating as the account owner, and instead create a user with administrator access and assume the administrator role with that user for any further operations that need privileged access.

Note: You cannot attach policies to the administrator role since all requests to your account will be authorized. The Triton portal currently does not support the creation of the administrator role. This can only be done via the API, as shown in the example below. Please email support@joyent.com or contact support through your normal support channel if you require assistance.

Example

Follow the instructions below to create a user and administrator role.

Step 1: Create the administrator role

Enter the following CloudAPI command in a terminal environment with the CloudAPI CLI tools installed:

sdc-role create --name=administrator

This will return the following, with a unique id which we will need later:

{
  "name": "administrator",
  "id": "027344ad-8d2e-c767-e81f-b211966bca10",
  "members": [],
  "default_members": [],
  "policies": []
}
Step 2: Create the Subuser

Enter the following command, replacing the username, initial password, and email address for the new user.

sdc-user create --login=NEWUSERNAME --password=PASSWORD123 --email=user@yourcompany.com

Subusers do not currently work with Docker instances. This functionality will be available in a future version of RBAC.

Step 3: Update the administrator role
sdc-role update 027344ad-8d2e-c767-e81f-b211966bca10 --members=NEWUSERNAME --default-members=NEWUSERNAME

Remember to use the unique id value from your admin role created earlier, as well as your new member username.

And you are done!

Don't forget, your subusers must login to the portal/api as the user PRIMARYUSERNAME/NEWUSERNAME