guides/authentication.md

@@ -2,3 +2,39 @@
 OpenID exists so that individual sites do not need to implement ad-hoc login systems. An **OpenID Provider (OP)** can be used to authenticate the user with a single account, which can be shared with individual sites (**Relying Party (RP)**)
 
 [DjangoLDP-Account](https://git.startinblox.com/djangoldp-packages/djangoldp-account) provides an implementation which plays both roles- the provider and the relying party. It enables federated user authentication, providing a single identity which can be used across various RPs and client-side applications
+
+# Using DjangoLDP-Account's Authentication
+
+If you want to use DjangoLDP-Account, but you don't need to understand its internal workings, please refer to the [DjangoLDP-Account Readme](https://git.startinblox.com/djangoldp-packages/djangoldp-account) which has a step-by-step on installation and usage
+
+# How It Works
+
+This part of the guide is intended for developers who may need to understand DjangoLDP-Account's internal workings, as opposed to those who simply need to use it
+
+## The OIDC Workflow
+
+The underpinning technology for DjangoLDP-Account is the OpenID Connect (OIDC) workflow. It's necessary to understand this in order to understand how our implementation works:
+* [Implementation in PyOIDC, used by DjangoLDP-Account](https://pyoidc.readthedocs.io/en/latest/examples/rp.html)
+* [Example Workflow](https://github.com/solid/webid-oidc-spec/blob/master/example-workflow.md)
+
+## The OIDC Provider (OP)
+
+This section is TODO
+
+## The Relying Party (RP)
+
+### Login
+
+Login can be completed on two levels, the local level (using the local server), or the federated level (using a specified or discovered OIDC provider)
+
+A [template](https://git.startinblox.com/djangoldp-packages/djangoldp-account/blob/master/djangoldp_account/templates/registration/login.html) is defined which implements a login form with options for logging in to the local server, logging in with an arbitrary OIDC provider and for registering a new account
+
+#### Local Login
+
+DjanogLDP-Account defines a view `LDPAccountLoginView`, which is a simple implementation of the LoginView from [django-registration](https://django-registration.readthedocs.io/en/3.1/). Also from django-registration, this view is connected on the url path `/auth/login/`
+
+#### Federated Login
+
+DjangoLDP-Account defines a view `RPLoginView`, and provides a url for this view at `/oidc/login/`. The view leverages an `RPLoginEndpoint` class which defines the behaviour of the relying party's login system. [source code](https://git.startinblox.com/djangoldp-packages/djangoldp-account/blob/master/djangoldp_account/endpoints/rp_login.py)
+
+The key function is `op_login_url`, which is responsible for handling a federated login request. Login can be completed by providing a URL to the provider, or by providing an email or WebFinger ID. In the latter two cases, provider-discovery will be necessary (see 2.1 of the [Example Workflow](https://github.com/solid/webid-oidc-spec/blob/master/example-workflow.md))
\ No newline at end of file