✨ Refresh & document OIDC support

Parent issue: sequentech/meta#256

docs/general/guides/guides.md

@@ -4,13 +4,23 @@ title: Guides
 ---
 
 The following guides are available:
+
+## General guides
+
 - [Deployment Guide](./deployment/)
-- [Election Creation Guide](./election-creation/)
-- [Parent and Children Elections Guide](./parent-and-children-elections/)
-- [Write-ins Guide](./write-ins/)
-- [SmartLink Auth Guide](./smart-link-auth/)
 - [Messaging Voters Guide](./messaging-voters/)
 - [Electoral Board Ceremonies](./electoral-board-ceremonies/)
-- [Segmented Mixing Guide](./segmented-mixing/)
 - [Cron Tasks Guide](./cron-tasks/)
 - [Scheduled Events Guide](./scheduled-events/)
+
+## Election Configuration
+
+- [Election Creation Guide](./election-creation/)
+- [Parent and Children Elections Guide](./parent-and-children-elections/)
+- [Write-ins Guide](./write-ins/)
+- [Segmented Mixing Guide](./segmented-mixing/)
+
+## Authentication
+
+- [SmartLink Auth Guide](./smart-link-auth/)
+- [OpenID Connect Auth Guide](./openid-auth)

docs/general/guides/openid-auth/openid-auth.md

@@ -0,0 +1,71 @@
+---
+sidebar_position: 6
+title: OpenId Connect Auth Guide
+---
+
+## Introduction
+
+In this document we will explain everything you need to know about the OpenID
+Connect authentication mechanism: what it is, what it provides, how it works,
+and how to use it.
+
+## What it is
+
+OpenID Connect (OIDC) is an authentication method supported by the Sequent
+Platform that works on top of the OAuth 2.0 framework. OIDC allows voters to use
+single sign-on (SSO) to authenticate using 3rd-party OpenID Providers (OPs),
+such as an email provider or social network, to authenticate their identities.
+
+:::note Other Single sign-one methods
+
+Sequent Platform also supports the 
+[SmartLink authentication method](../smart-link-auth/)  to implement Single
+Sign-On.
+:::
+
+## How it works
+
+SmartLink is a native authentication method in Sequent platform. Voters will be
+sent from the Login page to a third-party OpenID Provider (OP), and
+authenticated there. Please note that still, **authorization is done by**
+**Sequent platform**. This means that the administrator need to upload the
+census in Sequent platform.
+
+The authentication flow compromises the following steps:
+1. Voters access the Login page.
+2. In the login page, the voter click in one of the OPs configured for the
+   election and listed in the login page.
+2. After clicking on the OP link, the voter is redirected to an external website
+   provided by the OP, where the voter can authenticate.
+3. Once authenticated in the external website of the OP, the voter is redirected
+   back to a callback Sequent Platform URL.
+4. Sequent Platform receives some authentication token from the OP, which it 
+   uses to verify the voter identity. If the voter `sub` from this token is part
+   of the election census, the voter authorization verification is successful
+   and the voter is redirected to the Voting Booth.
+
+This is more detailed in the Sequent OIDC Sequence diagram:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    Voter           ->>+ WebBrowser: Request Sequent Login Page
+    WebBrowser      ->>+ SequentBackend: Request Sequent Login Page
+    SequentBackend -->>- WebBrowser: Returns Sequent Login Page
+    WebBrowser     -->>- Voter: Renders Sequent Login Page
+    Voter           ->>+ WebBrowser: Click on OIDC Provider Login Page
+    WebBrowser      ->>+ OIDCProvider: Request OIDC Provider Login Page
+    OIDCProvider   -->>- WebBrowser: Returns OIDC Provider Login Page
+    WebBrowser     -->>- Voter: Renders OIDC Provider
+    Voter           ->>+ WebBrowser: Provides Authenticaton Credentials
+    WebBrowser      ->>+ OIDCProvider: Send Authenticaton Credentials to OIDC Provider
+    OIDCProvider   -->>- WebBrowser: [If successful]<br>Authenticates and redirect back to<br>Sequent Login Page + ODIC Auth Token
+    WebBrowser      ->>+ SequentBackend: Request Sequent Login Page
+    SequentBackend -->>- WebBrowser: Returns Sequent Login Page
+    WebBrowser     -->>- Voter: Renders Sequent Login Page
+    WebBrowser      ->>+ SequentBackend: [Login Page] Authenticates using OIDC Auth Token
+    SequentBackend -->>- WebBrowser: [If successful] Sends back Sequent Auth Token
+    WebBrowser      ->>+ SequentBackend: Redirects to Voting Booth
+    SequentBackend -->>- WebBrowser: Returns Voting Booth
+    WebBrowser     ->> Voter: Renders Voting Booth
+```

docs/general/guides/smart-link-auth/smart-link-auth.md

@@ -11,17 +11,17 @@ to use it.
 
 ## What it is
 
-SmartLink is a Single sign-on (SSO) authentication mechanism provided by the 
+SmartLink is a Single Sign-On (SSO) authentication mechanism provided by the 
 Sequent platform that uses a Keyed [HMAC](https://en.wikipedia.org/wiki/HMAC) 
 authentication token. It allows you to send voters that 
 are already authenticated  in your own platform or website to a voting link 
 for a specific election without forcing them to authenticate again in Sequent 
 Platform. It is a secure and simple way to implement Single sign-on.
 
 :::note Other Single sign-one methods
+
 Sequent Platform also supports the 
-[OpenID Connect authentication method](../../reference/election-creation-json#census-auth_method) 
-to implement Single sign-on.
+[OpenID Connect authentication method](../openid-auth/)  to implement Single Sign-On.
 :::
 
 ## How it works