Add google authd-broker documentation #724

nsklikas · 2025-01-13T16:04:06Z

UDENG-5740

Added the documentation changes that we discussed to include the newly published google authd broker snap. I deviated very slightly from some of the discussed changes, please let me know if you agree or not.

cc @edibotopic

codecov-commenter · 2025-01-13T16:14:14Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 83.02%. Comparing base (36511cd) to head (f21b555).
Report is 176 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #724      +/-   ##
==========================================
- Coverage   83.43%   83.02%   -0.42%     
==========================================
  Files          83       89       +6     
  Lines        8689     8988     +299     
  Branches       74       74              
==========================================
+ Hits         7250     7462     +212     
- Misses       1111     1179      +68     
- Partials      328      347      +19

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

.github/ISSUE_TEMPLATE/bug_report.yml

.github/ISSUE_TEMPLATE/feature_request.yml

edibotopic

Thanks @nsklikas -- this is great.

I've added some minor comments and suggestions.

One thing: did we agree to remove the Group Management section from the GDM guide? I think we did, and I'm not sure it adds much to the guide as it stands. Feel free to remove or comment it out. We might find a better place for it.

edibotopic · 2025-01-14T10:03:03Z

docs/index.md

@@ -4,9 +4,10 @@ authd is a versatile authentication service for Ubuntu, designed to seamlessly i

 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) and [Google IAM](https://cloud.google.com/iam/docs/overview) are supported. For development purposes, authd also provides an example broker to help you develop your own.


Suggested change

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) and [Google IAM](https://cloud.google.com/iam/docs/overview) are 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, both [MS Entra ID](https://learn.microsoft.com/en-us/entra/fundamentals/whatis) and [Google IAM](https://cloud.google.com/iam/docs/overview) are supported. For development purposes, authd also provides an example broker to help you develop your own.

I would remove "only" here, as it has the potential effect of minimising the offering.

edibotopic · 2025-01-14T10:08:46Z

docs/index.md

+
+These brokers allow you to authenticate against MS Entra ID or Google IAM using MFA and the device authentication flow.


Suggested change

These brokers allow you to authenticate against MS Entra ID or Google IAM using MFA and the device authentication flow.

These brokers allow you to authenticate against MS Entra ID or Google IAM using Multi-factor authentication (MFA) and the device authentication flow.

I would combine this with previous paragraph, as it's the same flow of thought.
I would also spell out MFA because there are already three initialisms in this one sentence and -- for the homepage -- we want to make sure that the broadest range of readers understands what is being offered.

edibotopic · 2025-01-14T10:15:48Z

docs/reference/troubleshooting.md

+For the Google IAM broker entries, run:
+
+```shell
+journalctl -u snap.authd-google.authd-google.service
+```
+


Suggested change

For the Google IAM broker entries, run:

```shell

journalctl -u snap.authd-google.authd-google.service

```

For the broker entries, run the following command, replacing `<broker-name>` with the appropriate broker, such as `google` or `msentraid`:

```shell

journalctl -u snap.authd-<broker-name>.authd-<broker-name>.service

Placeholders are used elsewhere in this reference, so we can probably do the same here instead of having two unique entries for each of the two brokers. As this will be the first use of placeholders in the page, it's helpful to be explicit about the placeholders needing to be substituted.

edibotopic · 2025-01-14T10:21:03Z

docs/reference/troubleshooting.md

@@ -68,38 +74,38 @@ Enable=true

 Then you need to restart the service with `sudo systemctl restart gdm`.

-#### authd-msentraid service
+#### authd-<broker> service


Suggested change

#### authd-<broker> service

#### authd broker service

Avoid using angle brackets in headers: it doesn't render.

It also doesn't make sense to have placeholder syntax in text that the user will not be copying and running.

edibotopic · 2025-01-14T10:22:32Z

docs/reference/troubleshooting.md

-snap switch authd-msentraid --edge
-snap refresh authd-msentraid
+snap switch authd-<broker_name> --edge
+snap refresh authd-<broker_name>
 ```

 Keep in mind that this version is not tested and may be incompatible with current released version of authd. You should switch back to stable after trying the edge channel:


Suggested change

Keep in mind that this version is not tested and may be incompatible with current released version of authd. You should switch back to stable after trying the edge channel:

Keep in mind that this version is not tested and may be incompatible with the current released version of authd. You should switch back to stable after trying the edge channel:

edibotopic · 2025-01-14T10:32:39Z

docs/howto/configure-authd.md


-Register a new application in the Microsoft Azure portal. Once the application is registered, note the `Application (client) ID` and the `Directory (tenant) ID` from the `Overview` menu. These IDs are respectively the `<CLIENT_ID>` and `<ISSUER_ID>` used in the broker configuration file described in this document.
+In this section we are going to register an OAuth 2.0 application that the broker can use to authenticate users.


Suggested change

In this section we are going to register an OAuth 2.0 application that the broker can use to authenticate users.

In this section we are going to register an OAuth 2.0 application that the broker can use to authenticate users.

The registration process for both Entra ID and Google IAM will be demonstrated.

Add line to indicate multiple brokers will be demonstrated.

edibotopic · 2025-01-14T10:36:27Z

docs/howto/configure-authd.md

+Now we can configure the broker, different brokers require different configuration.
+


Suggested change

Now we can configure the broker, different brokers require different configuration.

Now we can configure the broker. Note that different brokers can require different configuration data.

Original was not really a complete sentence, so rewriting for clarity.

edibotopic · 2025-01-14T10:41:08Z

docs/howto/login-gdm.md

@@ -2,11 +2,14 @@

 ## Logging in with a remote provider

-Once the system is configured you can log into your system using your MS Entra ID credentials and the device code flow.
+Once the system is configured you can log into your system using your remote provider credentials and the device code flow.
+In this example we are going to use MS Entra ID as the remote provider.


Suggested change

In this example we are going to use MS Entra ID as the remote provider.

In this example, we are going to use MS Entra ID as the remote provider but the process is equivalent for other providers.

Using an example like this is fine and justified, as long as it is representative.

edibotopic · 2025-01-14T10:45:03Z

docs/howto/login-gdm.md


 The main operation is to restart the broker to reload the configuration when it has changed. You can reload the broker with the command:

 ```shell
-snap restart authd-msentraid
+snap restart authd-<broker_name>


As this page is a self-contained example that uses msentraid, I don't think the placeholder is appropriate.

Suggested change

snap restart authd-<broker_name>

snap restart authd-msentraid

Maybe then add:

If you are using a different broker to `msentraid`, make sure to change the snap name when running this command.

edibotopic · 2025-01-14T10:56:16Z

docs/howto/login-ssh.md

@@ -51,7 +44,7 @@ ssh_allowed_suffixes = @example.com,@ubuntu.com

 Once this is all set up, you can ssh to the server in the same way you'd do with any server: `ssh <username>@<host>`. The format of `<username>` is the user handle on Entra ID such as `[email protected]`.

-For instance:
+For instance, here is an example using MS Entra ID as a provider:


It's OK to highlight use of MS Entra as an example here, but in the sentence immediately above we state that <username> is the user on handle on Entra ID -- perhaps change that to the more generic:

Once this is all set up, you can ssh to the server in the same way you'd do with any server: ssh <username>@<host>. The format of <username> is the user handle on the provider, such as [email protected].

didrocks · 2025-01-14T13:07:19Z

One thing: did we agree to remove the Group Management section from the GDM guide? I think we did, and I'm not sure it adds much to the guide as it stands. Feel free to remove or comment it out. We might find a better place for it.

I think we did say we wanted to move it out as a new, separate, page. I don’t think we want to update the documentation without it? The "group" page should hilight though that for now, this si only supported for MSEntra ID.

edibotopic · 2025-01-14T17:07:31Z

docs/reference/group-management.md

+# Group management
+
+Groups are used to manage users that all need the same access and permissions to resources.
+Groups from the remove provider can be mapped into local Linux groups for the user.


Suggested change

Groups from the remove provider can be mapped into local Linux groups for the user.

Groups from the remote provider can be mapped to local Linux groups for the user.

edibotopic · 2025-01-14T17:08:29Z

docs/reference/group-management.md

+Groups from the remove provider can be mapped into local Linux groups for the user.
+
+```{note}
+  Groups right now are only supported for the `msentraid` broker.


Suggested change

Groups right now are only supported for the `msentraid` broker.

Groups are currently supported for the `msentraid` broker.

nsklikas · 2025-01-15T11:10:03Z

Everything should be fine now.

I am not sure why the tests are failing, but it should be something unrelated to these changes. I tried to re-trigger the workflow, but they failed again.

As discussed, even if this PR is approved (and the tests are fixed), it will remain open until the google snap is released to stable.

adombeck · 2025-01-15T11:37:10Z

I am not sure why the tests are failing, but it should be something unrelated to these changes. I tried to re-trigger the workflow, but they failed again.

Yeah the PAM integration tests are very flaky again. Cc @3v1n0

didrocks · 2025-01-15T11:46:39Z

until the google snap is released to stable.

It is in stable already, just not listed until we do an official release:

  0.x/stable:    notag+e95802f.8885537      2025-01-09  (6) 8MB -
  0.x/candidate: ↑                                              
  0.x/beta:      ↑                                              
  0.x/edge:      0.2.0-pre1+651886f.e17a472 2025-01-13 (13) 9MB -

edibotopic

Thanks for your work on this @nsklikas .

I've added one last suggested change and am approving in advance.

edibotopic · 2025-01-15T12:53:35Z

docs/howto/login-ssh.md

@@ -49,9 +42,9 @@ ssh_allowed_suffixes = @example.com,@ubuntu.com

 ## Usage

-Once this is all set up, you can ssh to the server in the same way you'd do with any server: `ssh <username>@<host>`. The format of `<username>` is the user handle on Entra ID such as `[email protected]`.
+Once this is all set up, you can ssh to the server in the same way you'd do with any server: ssh <username>@<host>. The format of <username> is the user handle on the provider, such as `[email protected]`.


Suggested change

Once this is all set up, you can ssh to the server in the same way you'd do with any server: ssh <username>@<host>. The format of <username> is the user handle on the provider, such as `[email protected]`.

Once this is all set up, you can ssh to the server in the same way that you would do with any server: `ssh <username>@<host>`. The format of `<username>` is the user handle on the provider, such as `[email protected]`.

Without backticks these translate to incomplete html tags in the browser, I think, so some of the words disappear in the preview:

I hope I didn't suggest those changes (I don't think I did!) but I think the backticks are needed for rendering; also, something like the ssh one is a command, so it makes sense to use them there.

Oh my bad, copy/pasted from a rendered suggestion and forgot to add the backticks back.

Checks were failing when referencing anchors from different files

nsklikas requested a review from a team as a code owner January 13, 2025 16:04

nsklikas force-pushed the UDENG-5740 branch from 5445090 to f2cfc91 Compare January 13, 2025 16:07

adombeck reviewed Jan 13, 2025

View reviewed changes

.github/ISSUE_TEMPLATE/bug_report.yml Outdated Show resolved Hide resolved

adombeck reviewed Jan 13, 2025

View reviewed changes

.github/ISSUE_TEMPLATE/feature_request.yml Outdated Show resolved Hide resolved

adombeck reviewed Jan 13, 2025

View reviewed changes

.github/ISSUE_TEMPLATE/feature_request.yml Outdated Show resolved Hide resolved

nsklikas force-pushed the UDENG-5740 branch from f2cfc91 to df7a7b7 Compare January 13, 2025 17:36

edibotopic requested changes Jan 14, 2025

View reviewed changes

nsklikas force-pushed the UDENG-5740 branch 4 times, most recently from 1dbad01 to a3cdbc2 Compare January 14, 2025 12:44

nsklikas force-pushed the UDENG-5740 branch 3 times, most recently from 2c20152 to 2bc6942 Compare January 14, 2025 16:53

edibotopic reviewed Jan 14, 2025

View reviewed changes

nsklikas force-pushed the UDENG-5740 branch 2 times, most recently from 903c971 to c3e9c8f Compare January 15, 2025 10:35

nsklikas requested a review from edibotopic January 15, 2025 11:07

edibotopic approved these changes Jan 15, 2025

View reviewed changes

nsklikas force-pushed the UDENG-5740 branch from c3e9c8f to 5d4f528 Compare January 15, 2025 15:08

nsklikas added 3 commits January 15, 2025 16:14

docs: add google authd-broker documentation

76936a2

docs: auto-generate anchors

b1069ec

Checks were failing when referencing anchors from different files

docs: move group management to separate file

f21b555

nsklikas force-pushed the UDENG-5740 branch from 5d4f528 to f21b555 Compare January 15, 2025 15:14

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add google authd-broker documentation #724

Add google authd-broker documentation #724

nsklikas commented Jan 13, 2025

codecov-commenter commented Jan 13, 2025 •

edited

Loading

edibotopic left a comment

edibotopic Jan 14, 2025

edibotopic Jan 14, 2025

edibotopic Jan 14, 2025

edibotopic Jan 14, 2025

edibotopic Jan 14, 2025

edibotopic Jan 14, 2025

edibotopic Jan 14, 2025

edibotopic Jan 14, 2025

edibotopic Jan 14, 2025

edibotopic Jan 14, 2025

didrocks commented Jan 14, 2025

edibotopic Jan 14, 2025

edibotopic Jan 14, 2025

nsklikas commented Jan 15, 2025

adombeck commented Jan 15, 2025

didrocks commented Jan 15, 2025

edibotopic left a comment

edibotopic Jan 15, 2025

nsklikas Jan 15, 2025


		These brokers allow you to authenticate against MS Entra ID or Google IAM using MFA and the device authentication flow.

	Keep in mind that this version is not tested and may be incompatible with current released version of authd. You should switch back to stable after trying the edge channel:
	Keep in mind that this version is not tested and may be incompatible with the current released version of authd. You should switch back to stable after trying the edge channel:


		Register a new application in the Microsoft Azure portal. Once the application is registered, note the `Application (client) ID` and the `Directory (tenant) ID` from the `Overview` menu. These IDs are respectively the `<CLIENT_ID>` and `<ISSUER_ID>` used in the broker configuration file described in this document.
		In this section we are going to register an OAuth 2.0 application that the broker can use to authenticate users.

	In this section we are going to register an OAuth 2.0 application that the broker can use to authenticate users.
	In this section we are going to register an OAuth 2.0 application that the broker can use to authenticate users.
	The registration process for both Entra ID and Google IAM will be demonstrated.

		Now we can configure the broker, different brokers require different configuration.

	Now we can configure the broker, different brokers require different configuration.
	Now we can configure the broker. Note that different brokers can require different configuration data.

	In this example we are going to use MS Entra ID as the remote provider.
	In this example, we are going to use MS Entra ID as the remote provider but the process is equivalent for other providers.

	snap restart authd-<broker_name>
	snap restart authd-msentraid

	Groups from the remove provider can be mapped into local Linux groups for the user.
	Groups from the remote provider can be mapped to local Linux groups for the user.

	Groups right now are only supported for the `msentraid` broker.
	Groups are currently supported for the `msentraid` broker.

	Once this is all set up, you can ssh to the server in the same way you'd do with any server: ssh <username>@<host>. The format of <username> is the user handle on the provider, such as `[email protected]`.
	Once this is all set up, you can ssh to the server in the same way that you would do with any server: `ssh <username>@<host>`. The format of `<username>` is the user handle on the provider, such as `[email protected]`.

Add google authd-broker documentation #724

Are you sure you want to change the base?

Add google authd-broker documentation #724

Conversation

nsklikas commented Jan 13, 2025

codecov-commenter commented Jan 13, 2025 • edited Loading

Codecov Report

edibotopic left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

didrocks commented Jan 14, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nsklikas commented Jan 15, 2025

adombeck commented Jan 15, 2025

didrocks commented Jan 15, 2025

edibotopic left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov-commenter commented Jan 13, 2025 •

edited

Loading