Email verify docs

docs/getting-started/creating-users.md

@@ -0,0 +1,31 @@
+## 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 create test@example.com
+```
+
+This will send a verification email to that address. Until the user is verified they will not be able to log in. Direct the new user to the docs on how to verify themselves [here](/how-to/auth/manage-users#verifying-a-user). For how to give them new permissions to work with the fleet once they _have_ logged in, read on.
+
+### Giving a User Permissions
+
+You can add a role to a user with the [user add_role command](/how-to/auth/manage-roles):
+
+```
+$ fleet auth user add_role test@example.com Admin
+```
+
+This will allow the user to do anything to the fleet. If you wish to restrict their permissions you'll need to create policies, put them in roles, then add the roles to the user.
+
+For more info on creating custom roles and policies, inspecting them and seeing example policies 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 test@example.com, we combine this to verify your account and create your cert like so:
+
+```
+$ fleet --host myfleet.f.nchr.io auth user verify test@example.com 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 test@example.com 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,43 @@
+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
+----------------  ---------
+test@example.com  HomeComputer
+```
+
+Creating an auth cert
+----
+
+To create an auth cert you must specify an email corresponding to a user and a label to identify the cert:
+
+```
+$ fleet auth cert create test@example.com WorkComputer
+```
+
+This creates a key at ~/.config/anchorfleet/WorkComputer.key and sends a CSR ([Certificate Signing Request](https://en.wikipedia.org/wiki/Certificate_sigining_request)) to the fleet and returns a signed crt.pem file ([x509 client cert](https://en.wikipedia.org/wiki/X.509)). The crt is written to ~/.config/anchorfleet/WorkComputer.crt.
+
+NB: the key and CSR are 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 revoke test@example.com HomeComputer
+Revoked label: HomeComputer for email: test@example.com
+```
+
+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,142 @@
+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.
+
+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 created by redirecting a JSON policy object into the command:
+
+```
+$ cat > policy.json
+{
+  "resource": [
+    "*"
+  ],
+  "method": [
+    "*"
+  ],
+  "name": "DenyAll",
+  "effect": "deny"
+}
+$ fleet auth policy create < policy.json
+Added policy: DenyAll
+```
+
+If what you redirect in isn't valid JSON it'll be rejected.
+
+Destroying Policies
+----
+
+```
+$ fleet auth policy destroy DenyProdEnv
+Removed policy: DenyAll
+```
+
+
+Example Policies
+----
+
+Below are some example policies, showcasing what can be done with them.
+
+**Admin**, can access all resources through all methods:
+
+```
+{
+  "name": "Admin",
+  "effect": "Allow",
+  "resource": ["*"],
+  "method": ["*"]
+}
+```
+
+**Developer**, can edit just the resources needed for the day to day management of the fleet:
+
+```
+{
+  "name": "Developer",
+  "effect": "Allow",
+  "resource": ["environments", "releases", "whitelists", "snapshots", "certificates"],
+  "method": ["*"]
+}
+```
+
+**NoProd**, when combined with the above policy could prevent access to environments of a particular name, for example 'prod':
+
+```
+{
+  "name": "NoProd",
+  "effect": "Deny",
+  "resource": ["environments"],
+  "params": [{"env_name": "prod"}],
+  "method": ["*"]
+}
+```
+
+**Manager**, can create new users and permissions:
+
+```
+{
+  "name": "Manager",
+  "effect": "Allow",
+  "resource": ["auth_keys", "users", "roles", "policies"],
+  "method": ["*"]
+}
+```

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 create Admin
+Added role: Admin
+$ fleet auth role create Admin --policies AllowAll
+Added role: Admin
+$ fleet auth role create JuniorDev --policies "AllowEnvironments, AllowReleases, DenyProdEnv"
+Added role: JuniorDev
+```
+
+Destroying a role
+----
+
+```
+$ fleet auth role destroy 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
+```