docs: add google authd-broker documentation

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -101,6 +101,12 @@ body:
         \`\`\`
         $(cat 2>&1 /var/snap/authd-msentraid/current/broker.conf | sed -E 's/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/<UUID redacted>/g')
         \`\`\`
+
+        #### authd-google configuration
+        \`\`\`
+        $(cat 2>&1 /var/snap/authd-google/current/broker.conf | sed -E 's/client_id = .*/client_id = <redacted>/g' | sed -E 's/client_secret = .*/client_secret = <redacted>/g')
+        \`\`\`
+
         EOF
         ```
 

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -49,7 +49,7 @@ body:
     attributes:
       label: "System information and logs"
       description: |
-        Provide details about the environment you experienced the issue in. Change msentraid for the provider you are using:
+        Provide details about the environment you experienced the issue in.
       value: |
         ### Environment
         * broker version: please run `snap info authd-msentraid`
@@ -73,22 +73,40 @@ body:
         journalctl -u snap.authd-msentraid.authd-msentraid.service
         ```
 
+        ####  Google broker entries:
+
+        ```raw
+        journalctl -u snap.authd-google.authd-google.service
+        ```
+
         ### Application settings
 
         Please redact/remove sensitive information:
 
-        ####  Broker configuration:
+        ####  MS Entra ID broker configuration:
 
         ```raw
         cat /var/snap/authd-msentraid/current/broker.conf
         ```
 
-        ####  Broker authd configuration:
+        ####  MS Entra ID broker authd configuration:
 
         ```raw
         cat /etc/authd/brokers.d/msentraid.conf
         ```
 
+        ####  Google broker configuration:
+
+        ```raw
+        cat /var/snap/authd-google/current/broker.conf
+        ```
+
+        ####  Google broker authd configuration:
+
+        ```raw
+        cat /etc/authd/brokers.d/google.conf
+        ```
+
   - type: textarea
     attributes:
       label: Relevant information

README.md

@@ -29,8 +29,8 @@ authd is an authentication daemon for cloud-based identity providers. It helps
 ensure the secure management of identity and access for Ubuntu machines anywhere
 in the world, on desktop and the server. authd's modular design makes it a
 versatile authentication service that can integrate with multiple identity
-providers. MS Entra ID is currently supported and several other identity
-providers are under active development.
+providers. `MS Entra ID` and `Google Cloud's Identity and Access Management` are currently
+supported and several other identity providers are under active development.
 
 ## Documentation
 
@@ -46,12 +46,12 @@ 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 [MS Entra ID](https://learn.microsoft.com/en-us/entra/fundamentals/whatis)
-is supported as an identity provider.
-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.
+and [Google IAM](https://cloud.google.com/iam/docs/overview)
+are supported as identity providers.
+They allow you to authenticate using MFA and the device authentication flow.
 
 For development purposes, authd also provides an
-[example broker](https://github.com/ubuntu/authd/tree/main/examplebroker) 
+[example broker](https://github.com/ubuntu/authd/tree/main/examplebroker)
 to help you develop your own.
 
 ## Get involved

docs/.custom_wordlist.txt

@@ -26,6 +26,7 @@ mountpoint
 msentraid
 NFS
 nss
+OAuth
 OIDC
 OpenID
 ppa

docs/howto/configure-authd.md

@@ -2,18 +2,22 @@
 
 ## Broker discovery
 
-Create the directory that will contain the declaration files of the broker and copy the one from the Entra ID broker snap package:
+Create the directory that will contain the declaration files of the broker and copy the one from the broker snap package:
 
 ```shell
 sudo mkdir -p /etc/authd/brokers.d/
-sudo cp /snap/authd-msentraid/current/conf/authd/msentraid.conf /etc/authd/brokers.d/
+sudo cp /snap/authd-<broker_name>/current/conf/authd/<broker_name>.conf /etc/authd/brokers.d/
 ```
 
 This file is used to declare the brokers available on the system. Several brokers can be enabled at the same time.
 
-## Entra ID configuration
+## Application registration
 
-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.
+
+### Entra ID
+
+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 a `<CLIENT_ID>` and `<ISSUER_ID>` that will be used in the next section.
 
 To register a new application, in Entra, select the menu `Identity > Applications > App registration`
 
@@ -37,38 +41,73 @@ Finally, as the supported authentication mechanism is the device workflow, you n
 
 [The Microsoft documentation](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) provides detailed instructions for registering an application with the Microsoft identity platform.
 
+### Google IAM
+
+Register a new application in Google IAM. Once the application is registered, note the `Client ID` and the `Client secret`. These values are respectively the `<CLIENT_ID>` and `<CLIENT_SECRET>` that will be used in the next section.
+
+To register a new application go to the [Credentials page](https://console.cloud.google.com/apis/credentials).
+
+Click `Create credentials > OAuth client ID`.
+
+![Menu showing selection of Create credentials > OAuth client ID.](../assets/google-app-registration.png)
+
+Select the `TVs and Limited Input devices` application type.
+
+![Menu showing app type.](../assets/google-choose-app-type.png)
+
+Name your OAuth 2.0 client and click `Create`.
+
+Your app's `Client ID` and `Client Secret` will be shown on your page, store them somewhere as you will need them in the next step.
+
+![Screen showing app credentials.](../assets/google-app-credentials.png)
+
+For more detailed information please refer to the [OAuth 2.0 for TV and Limited-Input Device Applications documentation](https://developers.google.com/identity/protocols/oauth2/limited-input-device).
+
 ## Broker configuration
 
-To configure the broker, edit the file `/var/snap/authd-msentraid/current/broker.conf`:
+Now we can configure the broker, different brokers require different configuration.
+
+### Entra ID
+
+To configure Entra ID, edit  `/var/snap/authd-msentraid/current/broker.conf`:
 
 ```ini
 [oidc]
-issuer = https://login.microsoftonline.com/<ISSUER_ID>/v2.0
+issuer = <ISSUER_URL>
 client_id = <CLIENT_ID>
+```
 
-[users]
-## The directory where the home directory will be created for new users.
-## Existing users will keep their current directory.
-## The user home directory will be created in the format of {home_base_dir}/{username}
-#home_base_dir = /home
+### Google IAM
 
-## The username suffixes that are allowed to login via ssh without existing previously in the system.
-## The suffixes must be separated by commas.
-#ssh_allowed_suffixes = @example.com,@anotherexample.com
+To configure Google IAM, edit  `/var/snap/authd-google/current/broker.conf`:
+
+```ini
+[oidc]
+issuer = https://accounts.google.com
+client_id = <CLIENT_ID>
+client_secret = <CLIENT_SECRET>
 ```
 
+## Restart the broker
+
 When a configuration file is added you have to restart authd:
 
 ```shell
 sudo systemctl restart authd
 ```
 
-When the configuration of a broker is updated, you have to restart the broker:
+When the configuration of an `msentraid` broker is updated, you have to restart the broker:
 
 ```shell
 sudo snap restart authd-msentraid
 ```
 
+When the configuration of a `google` broker is updated, you have to restart the broker:
+
+```shell
+sudo snap restart authd-google
+```
+
 ## System configuration
 
 By default on Ubuntu, the login timeout is 60s. This may be too brief for a device code flow authentication. It can be set to a different value by changing the value of `LOGIN_TIMEOUT` in `/etc/login.defs`

docs/howto/install-authd.md

@@ -28,14 +28,26 @@ Install the following Debian packages (note that `gnome-shell` and `yaru-theme*`
 sudo apt install authd gnome-shell yaru-theme-gnome-shell
 ```
 
-## MS Entra ID broker
+## Install brokers
 
 The brokers are provided as Snap packages and available from the Snap Store.
 
+### MS Entra ID broker
+
 To install the MS Entra ID broker, run the following command:
 
 ```shell
 sudo snap install authd-msentraid
 ```
 
 At this stage, you have installed the main service and an identity broker to authenticate against Microsoft Entra ID.
+
+### Google IAM broker
+
+To install the Google IAM broker, run the following command:
+
+```shell
+sudo snap install authd-google
+```
+
+At this stage, you have installed the main service and an identity broker to authenticate against Google IAM.

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.
+
+> See all the available providers: [Install brokers](./install-authd.md#install-brokers)
 
 In the login screen (greeter), select ```not listed``` below the user name field.
 
-Type your MS Entra ID user name. The format is ```[email protected]```
+Type your remote provider user name. The format is ```[email protected]```
 
 Select the broker `Microsoft Entra ID`
 
@@ -50,12 +53,12 @@ If you want to restart the service, you can stop it with ```systemctl stop authd
 
 Run ```/usr/libexec/authd --help``` to display the entire help.
 
-## Entra ID broker
+## Broker management
 
-The broker is managed through the ```snap``` command. 
+The broker is managed through the ```snap``` command.
 
 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>
 ```

docs/howto/login-ssh.md

@@ -23,19 +23,12 @@ sudo systemctl restart ssh
 
 ### Broker configuration
 
-To configure the broker edit the file `/var/snap/authd-msentraid/current/broker.conf` and set the key `ssh_allowed_suffixes` with the list of domains that you want to allow.
+To configure the broker edit the file `/var/snap/authd-<broker_name>/current/broker.conf` and set the key `ssh_allowed_suffixes` with the list of domains that you want to allow.
 
 ```
-[oidc]
-issuer = https://login.microsoftonline.com/<ISSUER_ID>/v2.0
-client_id = <CLIENT_ID>
+...
 
 [users]
-# The directory where the home directory will be created for new users.
-# Existing users will keep their current directory.
-# The user home directory will be created in the format of {home_base_dir}/{username}
-# home_base_dir = /home
-
 # The username suffixes that are allowed to log in via ssh without existing previously in the system.
 # The suffixes must be separated by commas.
 ssh_allowed_suffixes = <ALLOWED DOMAINS>
@@ -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:
 
 ```shell
 ssh [email protected]@remote.host

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.
+
+These brokers allow you to authenticate against MS Entra ID or Google IAM using MFA and the device authentication flow.
 
-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.
 
 ---------
 

docs/reference/troubleshooting.md

@@ -16,6 +16,12 @@ For the MS Entra ID broker entries, run:
 journalctl -u snap.authd-msentraid.authd-msentraid.service
 ```
 
+For the Google IAM broker entries, run:
+
+```shell
+journalctl -u snap.authd-google.authd-google.service
+```
+
 For the GDM integration:
 
 ```shell
@@ -68,38 +74,38 @@ Enable=true
 
 Then you need to restart the service with `sudo systemctl restart gdm`.
 
-#### authd-msentraid service
+#### authd-<broker> service
 
 To increase the verbosity of the broker service, edit the service file:
 
 ```shell
-sudo systemctl edit snap.authd-msentraid.authd-msentraid.service
+sudo systemctl edit snap.authd-<broker_name>.authd-<broker_name>.service
 ```
 
 Add the following lines to the override file and make sure to add `-vv` to the exec command:
 
 ```
 [Service]
 ExecStart=
-ExecStart=/usr/bin/snap run authd-msentraid -vv
+ExecStart=/usr/bin/snap run authd-<broker_name> -vv
 ```
 
-You will then need to restart the service with `snap restart authd-msentraid`.
+You will then need to restart the service with `snap restart authd-<broker_name>`.
 
 ## Switch the snap to the edge channel
 
 Maybe your issue is already fixed! You should try switching to the edge channel of the broker snap. You can easily do that with:
 
 ```shell
-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:
 
 ```shell
-snap switch authd-msentraid --stable
-snap refresh authd-msentraid
+snap switch authd-<broker_name> --stable
+snap refresh authd-<broker_name>
 ```
 
 ## Common issues and limitations