diff --git a/explanation/authentication.rst b/explanation/authentication.rst new file mode 100644 index 0000000..da3197f --- /dev/null +++ b/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 `__ 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 `__, 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. diff --git a/explanation/index.rst b/explanation/index.rst index 0fff19d..fb57c47 100644 --- a/explanation/index.rst +++ b/explanation/index.rst @@ -10,10 +10,9 @@ JIMM Concepts .. toctree:: :maxdepth: 1 - JAAS overview - JAAS architecture - JAAS tags - JAAS security + Overview + Architecture + Tags + Security + Authentication CLI Tools - - diff --git a/explanation/jaas_security_scope.rst b/explanation/jaas_security_scope.rst index 21f8525..d7b29c6 100644 --- a/explanation/jaas_security_scope.rst +++ b/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 diff --git a/explanation/jaas_tags.rst b/explanation/jaas_tags.rst index 7755ca5..77ce71d 100644 --- a/explanation/jaas_tags.rst +++ b/explanation/jaas_tags.rst @@ -1,4 +1,4 @@ -JAAS tags +JAAS Tags ========= Introduction diff --git a/how-to/index.rst b/how-to/index.rst index b4d1076..04766cb 100644 --- a/how-to/index.rst +++ b/how-to/index.rst @@ -22,4 +22,4 @@ Terraform .. toctree:: :maxdepth: 1 - Using Terraform \ No newline at end of file + Use Terraform