Auth tutorial

docs/getting-started/creating-users.md

@@ -0,0 +1,39 @@
+## Auth Concepts
+
+Fleet auth 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/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 admin privileges and every other user by default will have no privileges. When you are creating a new user you need to remember to give them the necessary permissions.
+
+### 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:
+
+1. Admin - can do anything
+2. Reports - can view billing reports and logs
+3. Developer - can view and modify fleet resources (environments, releases, etc)
+4. NoProd - can NOT modify the production environment
+5. 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/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/manage-roles) and [here](/how-to/manage-policies) respectively.

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

@@ -0,0 +1,64 @@
+## Getting the Fleet Tool
+
+Thee 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
+2. have an account with a verified email address and the requisite permissions
+3. authenticate your requests with an SSL client certificate
+
+This guide will show you:
+
+1. where to download the Fleet CLI tool
+2. how verify your email address and get a signed SSL client certificate
+3. how to set up a configuration file
+
+### Downloading Fleet CLI Tool
+
+Download the latest Fleet CLI tool from [HERE](TODO). For now add it to your PATH. In the future this may be available as a package on PyPI or something similar.
+
+### 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/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/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.

docs/how-to/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/manage-roles.md

@@ -0,0 +1,50 @@
+Roles are groupings of [policies](/how-to/manage-policies) that are assigned to [users](/how-to/manage-users) to manage authorization.
+
+Listing roles
+----
+
+```
+$ fleet auth role list
+Name       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
+```

docs/how-to/manage-users.md

@@ -0,0 +1,78 @@
+In this document, a user refers to a developer using fleet, not an end user accessing the magento site. Users are primarily used to manage authentication and authorization.
+
+Listing existing users
+----
+
+```
+$ fleet auth user list
+UUID                                 Email            Roles
+-----------------------------------  ---------------  -------
+4bb1538b-30f1-4017-9d82-6a5b3a407534 [email protected] Admin
+```
+
+The UUID is a unique identity generated for each user that never changes. However most actions accept an email as that is more readable.
+
+Creating a user
+----
+
+You can add [roles](/how-to/manage-roles) to a user when you create them, or you can do that separately. A user with no roles will not be authorized to do anything and has no authentication certificates.
+
+```
+$ fleet auth user add [email protected]
+Added user: [email protected]
+```
+
+When adding roles use a comma separated list:
+
+```
+$ fleet auth user add [email protected] --roles Developer,Accountant
+$ fleet auth user add [email protected] --roles Developer
+$ fleet auth user add [email protected] --roles "Developer, CertManager"
+```
+
+When you create a new user a verification email will be sent to their email address. The user needs to verify their account before they can do anything.
+
+Verifying a user
+----
+
+Verifying a user will also create a [certificate](/how-to/manage-certs) for them. Thus verification requires an email address, a label for the certificate, and a [private key file](/how-to/manage-certs#creating-an-auth-cert).
+
+```
+$ fleet auth user verify [email protected] mylabel key.pem
+Please enter the verification token. End with EOF.
+----------%<----------
+```
+
+You will then need to paste your verification token into the cli and a certificate will be printed out, e.g.:
+```
+$ fleet auth user verify [email protected] mylabel key.pem
+Please enter the verification token. End with EOF.
+----------%<----------
+Cnm98A.ppWmKt7GNSA6hWxpjR1y_v6VIuk
+---------->%-----------
+Verified user: [email protected]
+Certificate:
+    Data:
+        Version: 3 (0x2)
+        Serial Number: 2 (0x2)
+    Signature Algorithm: sha256WithRSAEncryption
+...
+```
+
+If you want to write the certificate directly to file you can redirect the output and the prompt text will be silenced:
+
+```
+$ fleet auth user verify [email protected] mylabel key.pem > cert.pem
+<paste token: Cnm98A.ppWmKt7GNSA6hWxpjR1y_v6VIuk, and press ctrl+D>
+$ openssl x509 -text -noout -in cert.pem
+```
+
+Destroying a user
+----
+
+When a user is destroyed all of their [authentication certificates](/how-to/manage-certs) are revoked. This is not reversible.
+
+```
+$ fleet auth user remove [email protected]
+Removed user: [email protected] and revoked certificates
+```

mkdocs.yml

@@ -48,6 +48,8 @@ pages:
 - Getting Started:
   - 'Getting Started': 'getting-started/getting-started.md'
   - 'Configuring Revision Control': 'getting-started/configuring-revision-control.md'
+  - 'Installing Fleet Tool': 'getting-started/installing-fleet-tool.md'
+  - 'Creating Users': 'getting-started/creating-users.md'
   - 'First Deployment': 'getting-started/first-deployment.md'
   - 'Pushing Out a Change': 'getting-started/pushing-a-change.md'
   - 'Cleaning Up Environments': 'getting-started/cleaning-up-environments.md'
@@ -64,6 +66,10 @@ pages:
   - 'Manage SSL Certificates': 'how-to/manage-certificates.md'
   - 'Manage SQL Scripts': 'how-to/manage-sql-scripts.md'
   - 'Manage Code Repository': 'how-to/manage-code-repository.md'
+  - 'Manage Users': 'how-to/manage-users.md'
+  - 'Manage Authentication Certificates': 'how-to/manage-certs.md'
+  - 'Manage Roles': 'how-to/manage-roles.md'
+  - 'Manage Policies': 'how-to/manage-policies.md'
   - 'Access Inactive Releases': 'how-to/access-inactive-releases.md'
   - 'Configure DNS': 'how-to/configure-dns.md'
   - 'Migrate Between Plans': 'how-to/migrate-between-plans.md'