rs_user_policy

= rs_user_policy

A useful tool for managing many users across many RightScale accounts.

While the tests are not exhaustive, the current build status is.. {}[https://travis-ci.org/rgeyer/rs_user_policy]

== Usage

You must pass in your RightScale authentication information, and a policy file. You can also specify one or many RightScale accounts using the --rs-acct-num or -a parameters. If an account that you specify is an Enterprise Master account, all Enterprise Children accounts will automatically be discovered and included.

Options: --rs-email, -r : You RightScale User Email Address --rs-pass, -s : Your RightScale User Password --rs-acct-num, -a : A RightScale Enterprise Master Account ID --policy, -p : The path to a JSON file containing the role to permissions policy to enforce --user-assignments, -u : The path to a JSON file containing email address => role pairs for user assignments --empty-user-assignments-fatal, -e: A flag which asserts that the provided user_assigments should contain at least one user_assignment mapping. If there are 0 user assignments found, rs_user_policy will terminate. --audit-dir, -d : A directory where audit logs will be stored. By default this is the current working directory. --dry-run, -y: A flag indicating that no changes should be made, only the user_assignments.json should be evaluated (or created) and the audit_log.json produced --authority, -t: A flag indicating that all users in the user_assignments file "MUST" exist, and will always be created. Effectively asserting that the user_assignments is your canonical authority for users. --help, -h: Show this message

Example (One account) rs_user_policy -r "[e-mail]" -s "password" -p policy.json -u user_assignments.json -a 12345

Example (Multiple accounts) rs_user_policy -r "[e-mail]" -s "password" -p policy.json -u user_assignments.json -a 12345 -a 67891 -a 11121

=== Managing existing user permissions

The binary contained in this gem accepts two files as inputs to determine it's behavior. The first, is a policy JSON file which specifies the permissions to be applied to users.

Policy JSON should be in the following format

{ "role_name": { "default": [<permissions_here>], "/api/accounts/12345": [<permissions_here>] } }

Here the "role_name" is what can be assigned to a user. The keys of the hash ("default" and "/api/accounts/12345") refer to the account(s) the role should have access to, and the value for those keys is an array of permissions that should be assigned for that role in that account.

The "default" account will apply to all accounts encountered.

The second input file is the user assignments JSON file which assigns users to roles using their email.

User Assignment JSON should be in the following format

{ "[e-mail]": { "roles": [ "role_name" ] } }

There are two default roles which do not need to be defined in the policy file. "immutable" which indicates that no changes should be performed on the user, and "delete" which indicates that all permissions should be removed for the user in all accounts. Both "immutable" and "delete", if present will take precedence over any other roles assigned to the user.

So, given a policy file like;

{ "team1": { "default": ['observer', 'actor'], "/api/accounts/12345": ['observer', 'actor', 'server_login', 'admin'] }, "team2": { "default": ['observer', 'lite_user'], "/api/accounts/23456": ['observer', 'actor'] } }

And a user assignments file like;

{ "[e-mail]": { "roles": [ "team1" ] }, "[e-mail]": { "roles": [ "team2" ] } }

And operating on the accounts 12345 and 23456; user1 will be assigned observer and actor rights on account 23456, and observer, actor, server_login, and admin rights on account 12345 user2 will be assigned observer and lite_user rights on account 12345, and observer and actor rights on account 23456

Got that? Cool!

=== Creating new users

This tool can also be used to create net-new users who have either never used RightScale, or who have never been associated with one of the accounts targetted by the tool. For those type of users some additional parameters are necessary in the user_assignments source file. The minimum set of properties is ["roles", "company", "first_name", "last_name", "phone"]

{ "[e-mail]": { "roles": ["team1"], "company": "RightScale", "first_name": "Net", "last_name": "New", "phone": "9999999999", "create": "yes" } }

The order of the additional parameters does not matter. The properties list can also include "identity_provider_href" and "principal_uid" or "password" to specify the users authentication details. If no authentication details are supplied a random secure password will be generated, and written to the output user_assignments.json file.

NOTE: See the Authority section below for details on the "create" property

If a user with the specified email already exists, but that user does not have any permissions in the account(s) targetted by the tool, these additional properties are still required, but will be ignored.

==== Authority

By default, rs_user_policy assumes that RightScale is the authority for the existence of users. Meaning, if a user exists in the user_assigments, but does not exist in RightScale, the user will not be created by rs_user_policy. In order to override this there are two options.

• Specifying the --authority commandline option implies that ALL users who are in the user_assignments should be created with the provided parameters
• For individual users in the user_assignments, you can add a property named "create" with any value. The user will be created, and the "create" property will be removed.

== Output

When the script is run, it will produce two JSON files as output.

First is the audit_log-.json file. This will contain a history of all actions taken on all users. If --dry-run is specified, it will show the changes which would have been performed.

Second is the user_assignments-.json file. This will be a combination of the users read in from JSON in file specified by the --user-assignments option, plus any new users discovered in the accounts operated on. New users will be assigned the "immutable" role. This allows you to run rs_user_policy with the --dry-run option, or with no user assignments input to discover users, then assign roles to those users in the produced JSON, then use that file as the --user-assignments input for a subsequent run.

== TODO

• In absence of a policy.json, create a new policy.json with base roles for each account discovered (I.E. Admin, Observer, Designer, etc)
• Perhaps allow a role to inherit from another, or be a concatenation of several?
• Provide a mechanism for "temporary" users with an expiration date
  • Perhaps allow the user to enter a different role after the expiration date, rather than being removed completely?
• Optionally do not discover child accounts, but only use specified accounts.
• Extend multi_client to perform tasks concurrently in multiple threads.

== Copyright

Copyright (c) 2012-2013 Ryan J. Geyer. See LICENSE.txt for further details.