docs: ADSys arch explanation

docs/custom_conf.py

@@ -19,13 +19,13 @@
 ############################################################
 
 # Product name
-project = 'Active Directory GPO client'
-author = 'Canonical Group Ltd'
+project = "Active Directory GPO client"
+author = "Canonical Group Ltd"
 
 # The title you want to display for the documentation in the sidebar.
 # You might want to include a version number here.
 # To not display any title, set this option to an empty string.
-html_title = project + ' documentation'
+html_title = project + " documentation"
 
 # The default value uses CC-BY-SA as the license and the current year
 # as the copyright year.
@@ -48,76 +48,64 @@
 #   -H 'Accept: application/vnd.github.v3.raw' \
 #   https://api.github.com/repos/canonical/<REPO> | jq '.created_at'
 
-copyright = '%s CC-BY-SA, %s' % (datetime.date.today().year, author)
+copyright = "%s CC-BY-SA, %s" % (datetime.date.today().year, author)
 
 ## Open Graph configuration - defines what is displayed as a link preview
 ## when linking to the documentation from another website (see https://ogp.me/)
 # The URL where the documentation will be hosted (leave empty if you
 # don't know yet)
 # NOTE: If no ogp_* variable is defined (e.g. if you remove this section) the
 # sphinxext.opengraph extension will be disabled.
-ogp_site_url = 'https://canonical-adsys.readthedocs-hosted.com/'
+ogp_site_url = "https://canonical-adsys.readthedocs-hosted.com/"
 # The documentation website name (usually the same as the product name)
 ogp_site_name = project
 # The URL of an image or logo that is used in the preview
-ogp_image = 'https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg'
+ogp_image = "https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg"
 
 # Update with the local path to the favicon for your product
 # (default is the circle of friends)
-html_favicon = '.sphinx/_static/favicon.png'
+html_favicon = ".sphinx/_static/favicon.png"
 
 # (Some settings must be part of the html_context dictionary, while others
 #  are on root level. Don't move the settings.)
 html_context = {
-
     # Change to the link to the website of your product (without "https://")
     # For example: "ubuntu.com/lxd" or "microcloud.is"
     # If there is no product website, edit the header template to remove the
     # link (see the readme for instructions).
-    'product_page': 'github.com/ubuntu/adsys',
-
+    "product_page": "github.com/ubuntu/adsys",
     # Add your product tag (the orange part of your logo, will be used in the
     # header) to ".sphinx/_static" and change the path here (start with "_static")
     # (default is the circle of friends)
-    'product_tag': '_static/tag.png',
-
+    "product_tag": "_static/tag.png",
     # Change to the discourse instance you want to be able to link to
     # using the :discourse: metadata at the top of a file
     # (use an empty value if you don't want to link)
     # 'discourse': 'https://discourse.ubuntu.com',
-
     # Change to the Mattermost channel you want to link to
     # (use an empty value if you don't want to link)
     # 'mattermost': 'https://chat.canonical.com/canonical/channels/documentation',
-
     # Change to the Matrix channel you want to link to
     # (use an empty value if you don't want to link)
     # 'matrix': 'https://matrix.to/#/#documentation:ubuntu.com',
-
     # Change to the GitHub URL for your project
     # This is used, for example, to link to the source files and allow creating GitHub issues directly from the documentation.
-    'github_url': 'https://github.com/ubuntu/adsys',
-
+    "github_url": "https://github.com/ubuntu/adsys",
     # Change to the branch for this version of the documentation
-    'github_version': 'main',
-
+    "github_version": "main",
     # Change to the folder that contains the documentation
     # (usually "/" or "/docs/")
-    'github_folder': '/docs/',
-
+    "github_folder": "/docs/",
     # Change to an empty value if your GitHub repo doesn't have issues enabled.
     # This will disable the feedback button and the issue link in the footer.
-    'github_issues': 'enabled',
-
+    "github_issues": "enabled",
     # Controls the existence of Previous / Next buttons at the bottom of pages
     # Valid options: none, prev, next, both
-    'sequential_nav': "none",
-
+    "sequential_nav": "none",
     # Controls if to display the contributors of a file or not
     "display_contributors": True,
-
     # Controls time frame for showing the contributors
-    "display_contributors_since": ""
+    "display_contributors_since": "",
 }
 
 # If your project is on documentation.ubuntu.com, specify the project
@@ -142,9 +130,9 @@
 
 # Links to ignore when checking links
 linkcheck_ignore = [
-    'http://127.0.0.1:8000',
-    'https://leonelson.com/2011/08/15/how-to-increase-your-csr-key-size-on-microsoft-iis-without-removing-the-production-certificate/',
-    ]
+    "http://127.0.0.1:8000",
+    "https://leonelson.com/2011/08/15/how-to-increase-your-csr-key-size-on-microsoft-iis-without-removing-the-production-certificate/",
+]
 
 # Pages on which to ignore anchors
 # (This list will be appended to linkcheck_anchors_ignore_for_url)
@@ -166,13 +154,14 @@
 # not need to be added here: myst_parser, sphinx_copybutton, sphinx_design,
 # sphinx_reredirects, sphinxcontrib.jquery, sphinxext.opengraph
 custom_extensions = [
-    'sphinx_tabs.tabs',
-    'canonical.youtube-links',
-    'canonical.related-links',
-    'canonical.custom-rst-roles',
-    'canonical.terminal-output',
-    'notfound.extension'
-    ]
+    "sphinx_tabs.tabs",
+    "canonical.youtube-links",
+    "canonical.related-links",
+    "canonical.custom-rst-roles",
+    "canonical.terminal-output",
+    "sphinxcontrib.mermaid",
+    "notfound.extension",
+]
 
 # Add custom required Python modules that must be added to the
 # .sphinx/requirements.txt file.
@@ -181,12 +170,10 @@
 # pyspelling, sphinx, sphinx-autobuild, sphinx-copybutton, sphinx-design,
 # sphinx-notfound-page, sphinx-reredirects, sphinx-tabs, sphinxcontrib-jquery,
 # sphinxext-opengraph
-custom_required_modules = []
+custom_required_modules = ["sphinxcontrib-mermaid"]
 
 # Add files or directories that should be excluded from processing.
-custom_excludes = [
-    'doc-cheat-sheet*',
-    ]
+custom_excludes = ["doc-cheat-sheet*", "diagrams/readme.md"]
 
 # Add CSS files (located in .sphinx/_static/)
 custom_html_css_files = []
@@ -217,17 +204,26 @@
 ### Additional configuration
 ############################################################
 
+
 ## Add any configuration that is not covered by the common conf.py file.
 def run_before_build(app):
     import subprocess
-    subprocess.run(['./make_toctree.sh', 'reference/policies/Computer Policies', 'reference/policies/User Policies'])
+
+    subprocess.run(
+        [
+            "./make_toctree.sh",
+            "reference/policies/Computer Policies",
+            "reference/policies/User Policies",
+        ]
+    )
+
 
 def setup(app):
-    app.connect('builder-inited', run_before_build)
+    app.connect("builder-inited", run_before_build)
 
 
 # Define a :center: role that can be used to center the content of table cells.
-rst_prolog = '''
+rst_prolog = """
 .. role:: center
    :class: align-center
-'''
+"""

docs/diagrams/arch-adsys.mmd

@@ -0,0 +1,17 @@
+%%{init: {"theme": "base", "themeVariables": {
+      'background': '#DDC9D4',
+      'primaryColor': '#FFF',
+      'primaryTextColor': '#E95420',
+      'primaryBorderColor': '#7C0000',
+      'lineColor': '#E95420',
+      'secondaryColor': '#CECAC5'
+}}}%%
+flowchart TB
+    adcli(Ubuntu machine)
+    adsys(ADSys)
+    adcon(Active Directory controller)
+
+    adcli --"authenticate user"--> adsys
+    adsys --"fetch GPOs"--> adcon
+    adcon --"relevant policies resolved"--> adsys
+    adsys --"parse policies and apply"--> adcli

docs/diagrams/arch-sssd.mmd

@@ -0,0 +1,18 @@
+%%{init: {"theme": "base", "themeVariables": {
+      'background': '#DDC9D4',
+      'primaryColor': '#FFF',
+      'primaryTextColor': '#E95420',
+      'primaryBorderColor': '#7C0000',
+      'lineColor': '#E95420',
+      'secondaryColor': '#CECAC5'
+}}}%%
+flowchart TB
+    adcli(Ubuntu machine)
+    sssd(SSSD)
+    adcon(Active Directory controller)
+
+    adcli --"log in with user"--> sssd
+    sssd --"send user credentials"--> adcon
+    sssd --"allow authentication"--> adcli
+    adcon --"return user information"--> sssd
+

docs/diagrams/arch-state.mmd

@@ -0,0 +1,44 @@
+%%{init: {"theme": "base", "themeVariables": {
+      'background': '#DDC9D4',
+      'primaryColor': '#FFF',
+      'primaryTextColor': '#E95420',
+      'primaryBorderColor': '#7C0000',
+      'lineColor': '#E95420',
+      'secondaryColor': '#CECAC5'
+}}}%%
+stateDiagram-v2
+    um: Ubuntu machine
+    client: client.domain.com enrolled
+    user: user authenticated
+    fetch: fetch GPOs
+    parse: parse GPOs
+    update: update cached GPOs
+    GPOs: check GPOs are up-to-date
+    GPOs_applied_check: check GPOs are applied
+    GPOs_enforced_check: check GPOs are enforced
+    GPOs_apply: authenticate user and apply GPOs
+    auth_deny: don't authenticate user
+
+    state SSSD {
+
+        um --> client: enroll to domain.com
+        client --> um: unenroll from domain.com
+        client --> user: authenticate user
+    }
+
+    SSSD --> ADSys: if ADSys installed
+    SSSD --> End : if ADSys not installed
+
+    state ADSys{
+        start --> GPOs
+        GPOs --> fetch: if no
+        GPOs --> parse : if yes
+        fetch --> update
+        update --> GPOs
+        parse --> GPOs_applied_check
+        GPOs_applied_check --> GPOs_enforced_check: if no
+        GPOs_applied_check --> GPOs_apply: if yes
+        GPOs_enforced_check --> GPOs_apply: if no
+        GPOs_enforced_check --> auth_deny: if yes
+
+    }

docs/diagrams/readme.md

@@ -0,0 +1,22 @@
+# Mermaid diagrams
+
+Architecture diagrams for ADSys are built using Mermaid.
+
+Each diagram is defined in `docs/diagrams/` using a `.mmd` file.
+
+A custom theme is used that is suitable for viewing in
+light or dark mode.
+
+To use the theme in a new diagram, include the following at the top of any
+`.mmd` file:
+
+```
+%%{init: {"theme": "base", "themeVariables": {
+      'background': '#DDC9D4',
+      'primaryColor': '#FFF',
+      'primaryTextColor': '#E95420',
+      'primaryBorderColor': '#7C0000',
+      'lineColor': '#E95420',
+      'secondaryColor': '#CECAC5'
+}}}%%
+```

docs/explanation/adsys-ref-arch.md

@@ -0,0 +1,57 @@
+# ADSys architecture
+
+Here, we explain ADSys and SSSD, and how they are used in combination for
+managing authentication and policies.
+
+## ADSys and SSSD
+
+ADSys is a GPO client. In an AD-managed infrastructure, it can help with the
+management and control of Ubuntu clients through the AD controller. It
+compliments and depends on SSSD, which is a daemon that handles authentication
+and provides authorisation to access remote directories, including AD. ADSys
+can also be used in combination with Winbind, but here we will focus on SSSD.
+
+SSSD runs on the client Ubuntu machine and enables basic authentication with AD.
+When a client machine that is enrolled in the domain attempts to log in, SSSD
+sends the user’s information to the AD controller. If the credentials are
+valid, they are returned to SSSD. This allows the user to successfully
+authenticate.
+
+```{tip}
+The diagrams on this page can be zoom with a scroll-wheel
+and panned by clicking and dragging the left mouse button.
+```
+
+```{mermaid} ../diagrams/arch-sssd.mmd
+:zoom:
+:align: center
+```
+
+After the user is authenticated, ADSys queries the provider for policies that
+are directed to the authenticated user in the AD domain and resolves them,
+before applying the policies to the client.
+
+```{mermaid} ../diagrams/arch-adsys.mmd
+:zoom:
+:align: center
+```
+
+## Authentication and policy flow
+
+A detailed visual explanation of the authentication and policy flow with ADSys
+and SSSD is shown below:
+
+```{mermaid} ../diagrams/arch-state.mmd
+:zoom:
+:align: center
+```
+
+SSSD manages the enrolment and authentication of clients with AD. If ADSys is
+not installed, the control and management of AD clients stops at that point.
+
+If ADSys is installed, it checks whether GPOs on the client are up-to-date. If
+not they are fetched from the domain controller. Once the latest GPOs are
+available, they are parsed and applied. The user then authenticates
+successfully and the GPOs are applied. If the GPOs are not applied and they are
+enforced, then ADSys will not permit the session to continue.
+

docs/explanation/index.md

@@ -2,11 +2,21 @@
 
 **Discussion and clarification** of key topics.
 
+## Architecture
+
+The architecture of ADSys, and how it works with SSSD, is explained here:
+
+```{toctree}
+:titlesonly:
+Architecture <adsys-ref-arch>
+```
+
 ## Managers
 
-ADSys supports a wide variety of managers to configure and control various aspects of the client systems.
+ADSys supports a wide variety of managers to configure and control various
+aspects of the client systems.
 
-Managers available with ADSys are
+Managers available with ADSys are:
 
 ```{toctree}
 :titlesonly:

docs/how-to/set-up-ad.md

@@ -10,7 +10,7 @@ As a rule of thumb, we generally separate the Ubuntu configuration from the Wind
 
 ## Ubuntu administrative template generations
 
-**ADSys** ships with pre-built Active Directory administrative templates that you can install on your Active Directory server. You will find two flavors of them:
+**ADSys** ships with pre-built Active Directory administrative templates that you can install on your Active Directory server. You will find two flavours of them:
 
 * One listing only Long Term Supported (LTS) Ubuntu versions.
 * One listing all currently supported Ubuntu versions, including non LTS.