diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 6fc68a77a..8105d1b1c 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.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}//g') \`\`\` + + #### authd-google configuration + \`\`\` + $(cat 2>&1 /var/snap/authd-google/current/broker.conf | sed -E 's/client_id = .*/client_id = /g' | sed -E 's/client_secret = .*/client_secret = /g') + \`\`\` + EOF ``` diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 2e49e8acf..ae1300a5d 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.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 diff --git a/README.md b/README.md index 03831b4f5..9c799cf0a 100644 --- a/README.md +++ b/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 diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index cf9db2e7e..ed5b2fbb8 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -26,6 +26,7 @@ mountpoint msentraid NFS nss +OAuth OIDC OpenID ppa diff --git a/docs/assets/google-app-credentials.png b/docs/assets/google-app-credentials.png new file mode 100644 index 000000000..22c213cb0 Binary files /dev/null and b/docs/assets/google-app-credentials.png differ diff --git a/docs/assets/google-app-registration.png b/docs/assets/google-app-registration.png new file mode 100644 index 000000000..2f6071e3e Binary files /dev/null and b/docs/assets/google-app-registration.png differ diff --git a/docs/assets/google-choose-app-type.png b/docs/assets/google-choose-app-type.png new file mode 100644 index 000000000..338b5c282 Binary files /dev/null and b/docs/assets/google-choose-app-type.png differ diff --git a/docs/howto/configure-authd.md b/docs/howto/configure-authd.md index 9bfa6d02a..bb156b31e 100644 --- a/docs/howto/configure-authd.md +++ b/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-/current/conf/authd/.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 `` and `` 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 `` and `` 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 `` and `` 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//v2.0 +issuer = 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_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` diff --git a/docs/howto/install-authd.md b/docs/howto/install-authd.md index 8de24b474..f3fb2937c 100644 --- a/docs/howto/install-authd.md +++ b/docs/howto/install-authd.md @@ -28,10 +28,12 @@ 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 @@ -39,3 +41,13 @@ 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. diff --git a/docs/howto/login-gdm.md b/docs/howto/login-gdm.md index 98606816a..bb98258ba 100644 --- a/docs/howto/login-gdm.md +++ b/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 ```user@domain.name``` +Type your remote provider user name. The format is ```user@domain.name``` 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- ``` diff --git a/docs/howto/login-ssh.md b/docs/howto/login-ssh.md index fe1167c09..06bc7fd45 100644 --- a/docs/howto/login-ssh.md +++ b/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-/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//v2.0 -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 = @@ -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 @`. The format of `` is the user handle on Entra ID such as `user@domain.tld`. -For instance: +For instance, here is an example using MS Entra ID as a provider: ```shell ssh user@domain.tld@remote.host diff --git a/docs/index.md b/docs/index.md index f0acc55d7..c8424bd87 100644 --- a/docs/index.md +++ b/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. --------- diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md index dbe3da8e0..9f1b1506c 100644 --- a/docs/reference/troubleshooting.md +++ b/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,12 +74,12 @@ Enable=true Then you need to restart the service with `sudo systemctl restart gdm`. -#### authd-msentraid service +#### authd- 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-.authd-.service ``` Add the following lines to the override file and make sure to add `-vv` to the exec command: @@ -81,25 +87,25 @@ Add the following lines to the override file and make sure to add `-vv` to the e ``` [Service] ExecStart= -ExecStart=/usr/bin/snap run authd-msentraid -vv +ExecStart=/usr/bin/snap run authd- -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-`. ## 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- --edge +snap refresh authd- ``` 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- --stable +snap refresh authd- ``` ## Common issues and limitations