Auth tutorial

docs/getting-started/creating-users.md

@@ -0,0 +1,39 @@
+## Auth Concepts
+
+Fleet has a concept of Users, AuthCerts, Roles and Policies.
+
+AuthCerts are for authenticating users when they access their fleet to identify who they are. Your first AuthCert was creating in the [installing fleet](/getting-started/installing-fleet-tool) guide. For more info on creating and revoking your certs see [managing authentication certificates](/how-to/auth/manage-certs).
+
+Roles and Policies are for authorizing users and dictating what they can and can't do. Policies are fine grained permissions which are grouped into Roles and applied to Users. For example you might have two policies ViewEnvironments and ModifyReleases which you combine into a role Developer, and apply to particular users.
+
+The first user created will have the Admin Role, which grants all privileges. Every other user will have no Roles, thus no privileges upon creation. When you are creating a new user you need to remember to give them the necessary Roles.
+
+### Creating a User
+
+Create a new user like so:
+
+```
+$ fleet auth user add [email protected]
+```
+
+This will send a verification email to that address.
+
+### Giving a User Permissions
+
+There are four roles available by default. These are:
+
+* Admin - can do anything
+* Auditor - can view billing reports and logs
+* Developer - can view and modify fleet resources (environments, releases, etc)
+* NoProd - denies modification privileges to environment named 'prod', overriding any access previously granted
+* Manager - can create new users, roles and policies
+
+You can give a user multiple roles, e.g. Developer and NoProd would allow them to modify most environments, but no the one named 'prod'.
+
+You can add a role to a user with the [user add_role command](/how-to/auth/manage-roles):
+
+```
+$ fleet auth user add_role [email protected] Developer
+```
+
+For more info on creating custom roles and policies or inspecting them see [here](/how-to/auth/manage-roles) and [here](/how-to/auth/manage-policies) respectively.

docs/getting-started/installing-fleet-tool.md

@@ -0,0 +1,90 @@
+## Getting the Fleet Tool
+
+The Fleet CLI tool uses the Fleet API (not currently documented) to control your fleet. To do so it requires that you:
+
+1. Specify the hostname/location of your fleet.
+1. Have an account with a verified email address and the requisite permissions.
+1. Authenticate your requests with an SSL client certificate.
+
+This guide will show you:
+
+1. where to download the Fleet CLI tool
+1. how verify your email address and get a signed SSL client certificate
+1. how to set up a configuration file
+
+### Downloading Fleet CLI Tool
+
+Download the latest Fleet CLI tool from [HERE](TODO). It contains a [PEX](https://github.com/pantsbuild/pex) file that is run with the shebang `#!/usr/bin/env python2.7`. Run `env python2.7` to confirm you have a compatible version of python installed.
+
+#### On Linux
+
+Create a folder in `/opt` to store the fleet binary and add the location to PATH:
+
+```
+$ mkdir -p /opt/anchorfleet
+$ mv fleet /opt/anchorfleet/.
+$ echo 'export PATH=/opt/anchorfleet/:$PATH' >> ~/.bashrc
+```
+
+If you don't use bash remember to change the above commands to suit your shell, e.g. '~/.zshrc'.
+
+#### On OSX
+
+You can do the above for OSX if you wish however on OSX it is more conventional to put 3rd-party binaries in `/usr/local/bin`:
+
+```
+$ mkdir -p /usr/local/bin
+$ mv fleet /usr/local/bin/.
+$ echo $PATH | grep '/usr/local/bin' || echo 'export PATH=/usr/local/bin:$PATH' >> ~/.bash_profile
+```
+
+This only adds `/usr/local/bin` to PATH if it is not already in your PATH.
+
+If you don't use bash remember to change the above commands to suit your shell, e.g. '~/.zshrc'. If your terminal program doesn't run a login shell remember to use `~/.bashrc` instead.
+
+### Verifying your email address and getting a Certificate
+
+At this stage we will assume your account has been created. If you are the admin of a new fleet, this will have been done when your fleet was created. Otherwise you may be a developer and an admin has already created your account. In both cases there should be an email in your account. For more info on creating a new account see [here](TODO).
+
+The verification email you have received will contain a token that looks something like this: "Cnm9QQ.NEz8Pjzqq-FSPVQzpzdb_QN3yaE".
+
+Before you use this token you will need know the hostname for your fleet. Say for example your fleet name is "myfleet", your hostname will be "myfleet.f.nchr.io".
+
+Lastly you need a label for the certificate you are about to create. In this example we will label it "MyDesktop".
+
+Assuming your email is [email protected], we combine this to verify your account and create your cert like so:
+
+```
+$ fleet --host myfleet.f.nchr.io auth user verify [email protected] MyDesktop
+<paste token: Cnm98A.ppWmKt7GNSA6hWxpjR1y_v6VIuk, and press ctrl+D>
+```
+
+If this step failed it is likely that your verification token has expired. You can have a new token resent to your inbox by running:
+
+```
+$ fleet --host myfleet.f.nchr.io auth user verify --resend-email [email protected] MyDesktop
+<paste token: Cnm98A.ppWmKt7GNSA6hWxpjR1y_v6VIuk, and press ctrl+D>
+```
+
+Note the `--resend-email` flag. When the program pauses to wait for your token, check your inbox and use the newest token sent to you.
+
+If it worked you now have a key and cert file in the configuration directory mentioned below.
+
+### Set up a configuration directory
+
+It can be annoying to always add the `--host` flag at the begining of every command. Likewise for adding `--key-file` and `--cert-file` which we would have to do for all future commands. That's why the fleet tool creates a configuration directory in `~/.config/anchorfleet/`.
+
+Next we can create a config file so we don't have to specify:
+
+```
+$ cat <<CONFIG > ~/.config/anchorfleet/config.ini
+[Fleet client]
+host: myfleet.f.nchr.io
+#cert-file: ~/.config/anchorfleet/default.crt
+#key-file: ~/.config/anchorfleet/default.key
+CONFIG
+```
+
+This creates a config file with the above contents in a format compatible with python's [config parser](https://docs.python.org/2/library/configparser.html) library. Note the commented out options and their default settings. By default the first key/cert pair you create will be symlinked to default.crt and default.key. You can uncomment and override these if you wish.
+
+You now have the Fleet CLI Tool installed and configured with your verified account's certificate files. To see how to create new users and manage their permissions [click here](/getting-started/creating-users). To see how to use fleet to manage your magento site [click here](/getting-started/first-deployment).

docs/how-to/auth/manage-certs.md

@@ -0,0 +1,52 @@
+An authentication certificate ([ssl client certificate](https://en.wikipedia.org/wiki/Client_certificate)) is used by a [user](/how-to/auth/manage-users) to identify who they are to fleet. A user can have multiple auth certs, for example one for their work computer, one for their home computer.
+
+Auth certs have have a label so you can easily remember which is which.
+
+Listing existing auth certs
+----
+
+By default, revoked certs are not shown.
+
+```
+$ fleet auth cert list
+email             label
+----------------  ---------
+[email protected]  HomeComputer
+```
+
+Creating an auth cert
+----
+
+To create an auth cert you must specify an email corresponding to a user and redirect a key file into the command:
+
+```
+$ fleet auth cert add [email protected] WorkComputer < key.pem > work.key
+$ fleet auth cert add [email protected] HomeComputer < key.pem > home.key
+```
+
+This creates a CSR ([Certificate Signing Request](https://en.wikipedia.org/wiki/Certificate_sigining_request)), sends it to the fleet and returns a signed crt.pem file ([x509 client cert](https://en.wikipedia.org/wiki/X.509)) that you can use to authenticate yourself to fleet.
+
+You can generate an RSA key file using openssl like so:
+
+```
+$ openssl genrsa -out key.pem 4096
+```
+
+NB: the CSR is generated using your local installation of openssl. If openssl is not installed it won't work.
+
+Revoking an auth cert
+----
+
+Revoke a user's auth cert by label:
+
+```
+$ fleet auth cert remove [email protected] HomeComputer
+Revoked label: HomeComputer for email: [email protected]
+$ fleet auth cert remove [email protected] 'Work Computer'
+Revoked label: Work Computer for email: [email protected]
+```
+
+Expiry
+----
+
+Auth certs expire two years after being signed and will eventually need to be rotated. This means you'll need to create a new cert and then revoke the old cert.

docs/how-to/auth/manage-policies.md

@@ -0,0 +1,91 @@
+Policies are JSON objects that describe what a user can or cannot do.
+
+Policies Schema
+----
+
+An example policy:
+
+```
+{
+	"name": "DenyProdEnv",
+	"effect": "deny",
+	"resource": ["environments"],
+	"method": ["*"],
+	"params": [{"env_name": "prod"}]
+}
+```
+
+This is read as: "Do not allow any HTTP methods on the resource 'environments' with params `env_name = prod`".
+
+| Key      | Required | Type     | Description                                                |
+|----------|----------|----------|------------------------------------------------------------|
+| name     | yes      | string   | For descriptive purposes.                                  |
+| effect   | yes      | string   | Either "allow" or "deny"                                   |
+| resource | no\*     | string[] | Resources to be affected by this policy, including "\*"    |
+| method   | no\*     | string[] | HTTP methods to be affected by this policy, including "\*" |
+| params   | no       | object[] | JSON objects to refine the policy further                 |
+
+\*: *Although resource and method are optional, at least one of them must be present (either resource *or* method). When absent they both default to '\*'.*
+
+For documentation of what resources are available, what the HTTP methods do for a given resource, and what params each method for each resource is, see the API documentation (coming soon).
+
+Listing Policies
+----
+
+```
+$ fleet auth policy list
+Name
+--------
+AllowAll
+DenyProdEnv
+```
+
+Only policy names are listed. To see the JSON object representing the policy use the describe command.
+
+Describing Policies
+----
+
+```
+$ fleet auth policy describe AllowAll
+{
+  "resource": [
+    "*"
+  ],
+  "method": [
+    "*"
+  ],
+  "name": "AllowAll",
+  "effect": "Allow"
+}
+```
+
+Adding Policies
+---
+
+Policies are added by redirecting a JSON policy object into the command:
+
+```
+$ cat > policy.json
+{
+  "resource": [
+    "*"
+  ],
+  "method": [
+    "*"
+  ],
+  "name": "DenyAll",
+  "effect": "deny"
+}
+$ fleet auth policy add < policy.json
+Added policy: DenyAll
+```
+
+If what you redirect in isn't valid JSON it'll be rejected.
+
+Removing Policies
+----
+
+```
+$ fleet auth policy remove DenyProdEnv
+Removed policy: DenyAll
+```

docs/how-to/auth/manage-roles.md

@@ -0,0 +1,50 @@
+Roles are groupings of [policies](/how-to/auth/manage-policies) that are assigned to [users](/how-to/auth/manage-users) to manage authorization.
+
+Listing roles
+----
+
+```
+$ fleet auth role list
+Role       Policies
+---------  ----------
+Admin      AllowAll
+JuniorDev  AllowAll, DenyProdEnv
+```
+
+Creating a role
+----
+
+You can optionally provide policies with a comma separated list to include in a role when you create it or you can add them later.
+
+```bash
+$ fleet auth role add Admin
+Added role: Admin
+$ fleet auth role add Admin --policies AllowAll
+Added role: Admin
+$ fleet auth role add JuniorDev --policies "AllowEnvironments, AllowReleases, DenyProdEnv"
+Added role: JuniorDev
+```
+
+Removing a role
+----
+
+```
+$ fleet auth role remove Admin
+Removed role: Admin
+```
+
+Adding Policies to a role
+----
+
+```
+$ fleet auth role add_policies JuniorDev AllowWhitelists,AllowSnapshots
+Added policies: AllowWhitelists, AllowSnapshots to role: JuniorDev
+```
+
+Removing Policies from a role
+----
+
+```
+$ fleet auth role remove_policies JuniorDev DenyProdEnv
+Removed policies: DenyProdEnv from role: JuniorDev
+```