From 99462a7b8c3526b354d393ee4f38b34b2e649053 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Fri, 22 Nov 2024 10:04:41 +0000 Subject: [PATCH 1/5] add a feedback button --- docs/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 1f938d9de..b5de662ed 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -134,6 +134,9 @@ # NOTE: If set, links for viewing the documentation source files # and creating GitHub issues are added at the bottom of each page. "github_url": "https://github.com/ubuntu/authd", + # + # Add a feedback button + 'github_issues': 'enabled', # Docs branch in the repo; used in links for viewing the source files # # TODO: To customise the branch, uncomment and update as needed. From 6c4355f372bb17ad221b01ee878d88e560f48a8e Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Fri, 22 Nov 2024 10:30:01 +0000 Subject: [PATCH 2/5] make capitalisation of authd more consistent "authd" should not have capitalised first letter --- CONTRIBUTING.md | 2 +- docs/conf.py | 2 +- docs/explanation/authd-architecture.md | 6 +++--- docs/explanation/index.md | 2 +- docs/howto/index.md | 2 +- docs/howto/install-authd.md | 2 +- docs/index.md | 14 +++++++------- 7 files changed, 15 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 21806320d..6c6b8bc8f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,5 @@ -# Contributing to Authd +# Contributing to authd A big welcome and thank you for considering making a contribution to authd and Ubuntu! It’s people like you that help make these products a reality for users in our community. diff --git a/docs/conf.py b/docs/conf.py index b5de662ed..95244f794 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -23,7 +23,7 @@ # # TODO: Update with the official name of your project or product -project = "Authd" +project = "authd" author = "Canonical Ltd." diff --git a/docs/explanation/authd-architecture.md b/docs/explanation/authd-architecture.md index 24c4da156..4cb8cf364 100644 --- a/docs/explanation/authd-architecture.md +++ b/docs/explanation/authd-architecture.md @@ -1,12 +1,12 @@ -# Authd architecture +# authd architecture -Authd can help organisations ensure secure identity and access management by enabling seamless cloud-based authentication of Ubuntu machines. +authd can help organisations ensure secure identity and access management by enabling seamless cloud-based authentication of Ubuntu machines. Here we explain the architecture of authd and some of its design decisions. Links are provided at the end to support further reading. ## Architecture components -Authd acts as an interface between the host system and external identity providers. +authd acts as an interface between the host system and external identity providers. Remote information is cached when authenticating with authd, which improves performance while also facilitating offline access. The diagram below illustrates the components of authd and their communication methods: diff --git a/docs/explanation/index.md b/docs/explanation/index.md index b63a82f22..4ef39ab91 100644 --- a/docs/explanation/index.md +++ b/docs/explanation/index.md @@ -5,5 +5,5 @@ ```{toctree} :titlesonly: -Authd architecture +authd architecture ``` diff --git a/docs/howto/index.md b/docs/howto/index.md index 94a542b7e..fe86cbd07 100644 --- a/docs/howto/index.md +++ b/docs/howto/index.md @@ -9,5 +9,5 @@ Install authd Configure authd Login with GDM Login with SSH -Contributing to Authd +Contributing to authd ``` diff --git a/docs/howto/install-authd.md b/docs/howto/install-authd.md index f1a4fb096..8de24b474 100644 --- a/docs/howto/install-authd.md +++ b/docs/howto/install-authd.md @@ -4,7 +4,7 @@ This project consists of two components: * authd: The authentication daemon responsible for managing access to the authentication mechanism. * an identity broker: The services that handle the interface with an identity provider. There can be several identity brokers installed and enabled on the system. -Authd is delivered as a Debian package. +authd is delivered as a Debian package. ## System requirements diff --git a/docs/index.md b/docs/index.md index d278be5a7..266b917f6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,10 +1,10 @@ -# Authd +# authd -Authd is a versatile authentication service for Ubuntu, designed to seamlessly integrate with cloud identity providers like OpenID Connect and Entra ID. It offers a secure interface for system authentication, enabling cloud-based identity management. It can be used to support logins through both GDM and SSH. +authd is a versatile authentication service for Ubuntu, designed to seamlessly integrate with cloud identity providers like OpenID Connect and Entra ID. It offers a secure interface for system authentication, enabling cloud-based identity management. It can be used to support logins through both GDM and SSH. -Authd features a modular structure, facilitating straightforward integration with different cloud services. This design aids in maintaining strong security and effective user authentication. It's well-suited for handling access to cloud identities, offering a balance of security and ease of use. +authd features a modular structure, facilitating straightforward integration with different cloud services. This design aids in maintaining strong security and effective user authentication. It's well-suited for handling access to cloud identities, offering a balance of security and ease of use. -Authd uses brokers to interface with cloud identity providers through a [DBus API](https://github.com/ubuntu/authd/blob/HEAD/examplebroker/com.ubuntu.auth.ExampleBroker.xml). Currently only [MS Entra ID](https://learn.microsoft.com/en-us/entra/fundamentals/whatis) is supported. For development purposes, Authd also provides an example broker to help you develop your own. +authd uses brokers to interface with cloud identity providers through a [DBus API](https://github.com/ubuntu/authd/blob/HEAD/examplebroker/com.ubuntu.auth.ExampleBroker.xml). Currently only [MS Entra ID](https://learn.microsoft.com/en-us/entra/fundamentals/whatis) is supported. For development purposes, authd also provides an example broker to help you develop your own. The [MS Entra ID broker](https://github.com/ubuntu/oidc-broker) allows you to authenticate against MS Entra ID using MFA and the device authentication flow. @@ -41,18 +41,18 @@ The [MS Entra ID broker](https://github.com/ubuntu/oidc-broker) allows you to au ## Project and community -Authd is a member of the Ubuntu family. It’s an open source project that warmly welcomes community projects, contributions, suggestions, fixes and constructive feedback. +authd is a member of the Ubuntu family. It’s an open source project that warmly welcomes community projects, contributions, suggestions, fixes and constructive feedback. * [Code of conduct](https://ubuntu.com/community/ethos/code-of-conduct) * [Contribute](/howto/contributing) -Thinking about using Authd for your next project? Get in touch! +Thinking about using authd for your next project? Get in touch! ```{toctree} :hidden: :maxdepth: 2 -Authd +authd How-to guides Reference Explanation From c943cf32de5027e2f9d58597d7e300db71f2e692 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Fri, 22 Nov 2024 10:32:16 +0000 Subject: [PATCH 3/5] fix navigation from homepage grid --- docs/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/index.md b/docs/index.md index 266b917f6..8f959fda1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,7 +15,7 @@ The [MS Entra ID broker](https://github.com/ubuntu/oidc-broker) allows you to au ````{grid} 1 1 1 1 -```{grid-item-card} [How-to guides](index) +```{grid-item-card} [How-to guides](howto/index) **Step-by-step guides** covering key operations and common tasks ``` @@ -25,12 +25,12 @@ The [MS Entra ID broker](https://github.com/ubuntu/oidc-broker) allows you to au ````{grid} 1 1 2 2 :reverse: -```{grid-item-card} [Reference](index) +```{grid-item-card} [Reference](reference/index) **Technical information** on troubleshooting authd ``` -```{grid-item-card} [Explanations](index) +```{grid-item-card} [Explanation](explanation/index) **Discussion** of product architecture ``` From 7356268a03b32b556e214c5762084ff1e7091352 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Fri, 22 Nov 2024 11:09:37 +0000 Subject: [PATCH 4/5] add alt text to images --- docs/explanation/authd-architecture.md | 2 +- docs/howto/configure-authd.md | 8 ++++---- docs/howto/login-gdm.md | 10 +++++----- docs/howto/login-ssh.md | 2 +- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/explanation/authd-architecture.md b/docs/explanation/authd-architecture.md index 4cb8cf364..d67f85e06 100644 --- a/docs/explanation/authd-architecture.md +++ b/docs/explanation/authd-architecture.md @@ -11,7 +11,7 @@ Remote information is cached when authenticating with authd, which improves perf The diagram below illustrates the components of authd and their communication methods: -![isoflow-export-2024-08-30T13_44_31 725Z](../assets/authd-architecture.png) +![Isometric architecture diagram of authd.](../assets/authd-architecture.png) The architecture of authd consists of the following components: diff --git a/docs/howto/configure-authd.md b/docs/howto/configure-authd.md index 54f5bb7ea..aaca91cc1 100644 --- a/docs/howto/configure-authd.md +++ b/docs/howto/configure-authd.md @@ -17,19 +17,19 @@ Register a new application in the Microsoft Azure portal. Once the application i To register a new application, in Entra, select the menu `Identity > Applications > App registration` -![image](../assets/app-registration.png) +![Menu showing selection of App registrations under Applications.](../assets/app-registration.png) Then `New registration` -![image](../assets/new-registration.png) +![User interface showing selection of New registration in App registrations.](../assets/new-registration.png) And configure it as follows: -![image](../assets/configure-registration.png) +![Configuration screen for the new registration.](../assets/configure-registration.png) Under `Manage`, in the `API permissions` menu, set the following Microsoft Graph permissions: -![image](../assets/graph-permissions.png) +![Configuration screen for Microsoft Graph permissions.](../assets/graph-permissions.png) Ensure the API permission type is set to **Delegated** for each permission. diff --git a/docs/howto/login-gdm.md b/docs/howto/login-gdm.md index a03919555..c5c5b1048 100644 --- a/docs/howto/login-gdm.md +++ b/docs/howto/login-gdm.md @@ -10,23 +10,23 @@ Type your MS Entra ID user name. The format is ```user@domain.name``` Select the broker `Microsoft Entra ID` -![image](../assets/gdm-select-broker.png) +![Login screen showing selection of broker.](../assets/gdm-select-broker.png) If MFA is enabled, a QR code and a login code are displayed. -![image](../assets/gdm-qr.png) +![Display of QR code, login code and button to Request new login code.](../assets/gdm-qr.png) From a second device, flash the QR code or type the URL in a web browser, then follow the authentication process from your provider. Upon successful authentication, the user is prompted to enter a local password. This password can be used for offline authentication. -![image](../assets/gdm-pass.png) +![Prompt to create local password on successful authentication.](../assets/gdm-pass.png) ## Groups management -In our example the user `authd test` is a member of the following Azure groups: +In our example the user `authd test` is a member of the Azure groups `Azure_OIDC_Test` and `linux-sudo`: -![image](../assets/gdm-groups.png) +![Azure portal interface showing the Azure groups.](../assets/gdm-groups.png) This translates to the following unix groups on the local machine: diff --git a/docs/howto/login-ssh.md b/docs/howto/login-ssh.md index 9853fa151..b903fc94f 100644 --- a/docs/howto/login-ssh.md +++ b/docs/howto/login-ssh.md @@ -57,4 +57,4 @@ For instance: ssh user@domain.tld@remote.host ``` -![image](../assets/ssh-qr.png) +![Terminal interface showing option to authentice by login code or QR scan when user tries to ssh into server](../assets/ssh-qr.png) From 52f8436a76ce1bbd57cbe9d15b264f24c102aa1c Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Fri, 22 Nov 2024 11:16:03 +0000 Subject: [PATCH 5/5] make cards clickable on homepage --- docs/index.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/index.md b/docs/index.md index 8f959fda1..f0acc55d7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,6 +16,8 @@ The [MS Entra ID broker](https://github.com/ubuntu/oidc-broker) allows you to au ````{grid} 1 1 1 1 ```{grid-item-card} [How-to guides](howto/index) +:link: howto/index +:link-type: doc **Step-by-step guides** covering key operations and common tasks ``` @@ -26,11 +28,15 @@ The [MS Entra ID broker](https://github.com/ubuntu/oidc-broker) allows you to au :reverse: ```{grid-item-card} [Reference](reference/index) +:link: reference/index +:link-type: doc **Technical information** on troubleshooting authd ``` ```{grid-item-card} [Explanation](explanation/index) +:link: explanation/index +:link-type: doc **Discussion** of product architecture ```