Add authentication doc

additionally minor cleanup

explanation/authentication.rst

@@ -0,0 +1,48 @@
+JAAS Authentication
+===================
+
+As a brief refresher, authentication refers to the process of proving something to be true, in this case proving that
+the user logging in is who they say they are.
+
+This is one of the key features of JAAS. Where Juju controllers implement login via commonly understood username/password authentication,
+JAAS uses `OAuth 2.0 <https://auth0.com/intro-to-iam/what-is-oauth-2>`__ and `OIDC <https://developer.okta.com/blog/2019/10/21/illustrated-guide-to-oauth-and-oidc>`__. 
+While a full explanation of OAuth and OIDC are out of the scope of this document, you are likely already familiar with 
+the benefits of these standards when you log into various services across the internet. 
+
+These standards define how services can access your resources on your behalf and how services can authenticate your identity. 
+When logging into a web application that employs OIDC you will commonly be asked to login via a different website or provider, 
+like your email or social media provider and this information is then securely passed onto the original application.
+
+Login Providers
+---------------
+
+Because JAAS uses the OAuth 2.0/OIDC standard, theoretically various providers can be connected to JAAS and used as a login provider. 
+However, due to the varying security practices and slight deviations from the standard, not all providers are supported with JAAS.
+
+Officially, JAAS supports `Ory Hydra <https://www.ory.sh/hydra/>`__, a cloud native OAuth 2.0 and OIDC server. This is a key component of
+the `Canonical identity platform`_ which not only provides a standards compliant OAuth/OIDC server but also allows you to configure 
+social sign-on via other OIDC compliant identity providers (e.g. Azure AD, Google, Okta, etc.).
+
+
+Authentication Methods
+----------------------
+
+JAAS offers multiple OAuth 2.0 flows (a sequence of steps to login). Each of which is referred to as a **grant type**.
+
+**Authorization Code grant**: This flow is the most common and use by web application. You will encounter this flow with JAAS when using
+the Juju dashboard. The login process will redirect your broser to JAAS' identity provider and ask you to login before redirecting you
+to the dashboard. At this point you have been authenticated and can use your resources through the graphical interface.
+
+**Device Code grant**: You will encounter this flow when using the Juju CLI with JAAS. If you are logging in for the first time or if your
+session has expired you will be prompted with URL and unique code. Navigating to the page will ask you to login and provide the code.
+During this time the CLI will continually ping the server until authentication is complete.
+
+Sessions
+--------
+
+A brief mention on sessions is also important in the context of authentication. While JAAS authenticates a user by communicating with 
+an external identity provider, this is neither performant nor would make a great user experience if a user were asked to log in after each interaction.
+
+To solve this, JAAS also provides users with their own application sessions. Depending on your authentication flow, your session with
+JAAS will last a varying amount of time until you are asked to log in again. This is a configurable option to cater for different 
+organisational needs.

explanation/index.rst

@@ -10,10 +10,9 @@ JIMM Concepts
 .. toctree::
    :maxdepth: 1
 
-   JAAS overview <jaas_overview>
-   JAAS architecture <jaas_architecture>
-   JAAS tags <jaas_tags>
-   JAAS security <jaas_security_scope>
+   Overview <jaas_overview>
+   Architecture <jaas_architecture>
+   Tags <jaas_tags>
+   Security <jaas_security_scope>
+   Authentication <authentication>
    CLI Tools <cli_tools>
-
-

explanation/jaas_security_scope.rst

@@ -1,5 +1,5 @@
-JAAS: Security Scope
-========================
+JAAS Security Scope
+===================
 
 The scope of JAAS' security covers multiple aspects, including:
 
@@ -20,6 +20,8 @@ We recommend the `Canonical identity platform`_ as the preferred IdP for JAAS. T
 authentication on behalf of JAAS using OAuth 2.0 and OIDC. For authorisation, JAAS provides this by means
 of tags and ReBAC (Relation-Based Access Control).
 
+See the following pages for more details on how JAAS provides :doc:`authentication <./authentication>` and authorization.
+
 Auditing and logging
 --------------------
 JAAS provides audit logs of all access to each model managed by JAAS, including information on which user 

explanation/jaas_tags.rst

@@ -1,4 +1,4 @@
-JAAS tags
+JAAS Tags
 =========
 
 Introduction

how-to/index.rst

@@ -22,4 +22,4 @@ Terraform
 .. toctree::
    :maxdepth: 1
 
-   Using Terraform <use_terraform>
+   Use Terraform <use_terraform>