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..7c41df964 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -22,10 +22,12 @@ Kerberos keytab Keytab Keytabs +linux mountpoint msentraid NFS nss +OAuth OIDC OpenID ppa diff --git a/docs/assets/gdm-groups.png b/docs/assets/entraid-groups.png similarity index 100% rename from docs/assets/gdm-groups.png rename to docs/assets/entraid-groups.png 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/conf.py b/docs/conf.py index 95244f794..fac53a11b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -134,7 +134,7 @@ # 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 @@ -213,6 +213,10 @@ # myst_enable_extensions = set() +# Auto-generate header anchors +myst_heading_anchors = 3 + + # Custom Sphinx extensions; see # https://www.sphinx-doc.org/en/master/usage/extensions/index.html diff --git a/docs/howto/configure-authd.md b/docs/howto/configure-authd.md index 9bfa6d02a..adee70ca3 100644 --- a/docs/howto/configure-authd.md +++ b/docs/howto/configure-authd.md @@ -2,18 +2,23 @@ ## 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 a broker snap package, with a specific ``, such as `google` or `msentraid`: ```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. +The registration process for both Entra ID and Google IAM will be demonstrated. + +### 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 +42,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. Note that different brokers can require different configuration data. + +### 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..0f84fa805 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 but the process is equivalent for other providers. + +> 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` @@ -22,24 +25,6 @@ Upon successful authentication, the user is prompted to enter a local password. ![Prompt to create local password on successful authentication.](../assets/gdm-pass.png) -## Group management - -In our example the user `authd test` is a member of the Azure groups `Azure_OIDC_Test` and `linux-sudo`: - -![Azure portal interface showing the Azure groups.](../assets/gdm-groups.png) - -This translates to the following unix groups on the local machine: - -```shell -~$ groups -aadtest-testauthd@uaadtest.onmicrosoft.com sudo azure_oidc_test -``` - -There are three types of groups: -1. **Primary group**: Created automatically based on the user name -1. **Local group**: Group local to the machine prefixed with `linux-`. For instance if the user is a member of the Azure group `linux-sudo`, they will be a member of the `sudo` group locally. -1. **Remote group**: All the other Azure groups the user is a member of. - ## Commands ### authd @@ -50,12 +35,14 @@ 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 ``` + +> If you are using a different broker to `msentraid`, make sure to change the snap name when running this command. diff --git a/docs/howto/login-ssh.md b/docs/howto/login-ssh.md index fe1167c09..dbc065837 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 = @@ -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 @`. The format of `` is the user handle on Entra ID such as `user@domain.tld`. +Once this is all set up, you can ssh to the server in the same way that you would do with any server: `ssh @`. The format of `` is the user handle on the provider, 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..1b96acb7a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,9 +4,9 @@ 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, 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. +These brokers allow you to authenticate against MS Entra ID or Google IAM using multi-factor authentication 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/group-management.md b/docs/reference/group-management.md new file mode 100644 index 000000000..12a7fdb3d --- /dev/null +++ b/docs/reference/group-management.md @@ -0,0 +1,30 @@ +# Group management + +Groups are used to manage users that all need the same access and permissions to resources. +Groups from the remote provider can be mapped into local Linux groups for the user. + +```{note} + Groups are currently supported for the `msentraid` broker. +``` + +## MS Entra ID + +MS Entra ID supports creating groups and adding users to them. + +> See [Manage Microsoft Entra groups and group membership](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-manage-groups) + +For example the user `authd test`, is a member of the Entra ID groups `Azure_OIDC_Test` and `linux-sudo`: + +![Azure portal interface showing the Azure groups.](../assets/entraid-groups.png) + +This translates to the following unix groups on the local machine: + +```shell +~$ groups +aadtest-testauthd@uaadtest.onmicrosoft.com sudo azure_oidc_test +``` + +There are three types of groups: +1. **Primary group**: Created automatically based on the user name +1. **Local group**: Group local to the machine prefixed with `linux-`. For instance if the user is a member of the Azure group `linux-sudo`, they will be a member of the `sudo` group locally. +1. **Remote group**: All the other Azure groups the user is a member of. diff --git a/docs/reference/index.md b/docs/reference/index.md index 98b27c878..a8bf58880 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -6,4 +6,5 @@ :titlesonly: Troubleshooting +Group Management ``` diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md index dbe3da8e0..76a50625b 100644 --- a/docs/reference/troubleshooting.md +++ b/docs/reference/troubleshooting.md @@ -10,10 +10,10 @@ For ```authd``` entries, run: journalctl -u authd.service ``` -For the MS Entra ID broker entries, run: +For the broker entries, substitute `` with your broker's name and run: ```shell -journalctl -u snap.authd-msentraid.authd-msentraid.service +journalctl -u snap.authd-.authd-.service ``` For the GDM integration: @@ -68,12 +68,12 @@ 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-.authd-.service ``` Add the following lines to the override file and make sure to add `-vv` to the exec command: @@ -81,25 +81,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: +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: ```shell -snap switch authd-msentraid --stable -snap refresh authd-msentraid +snap switch authd- --stable +snap refresh authd- ``` ## Common issues and limitations