Onboard an authd user¶

authd creates a local user record the first time a user logs in successfully through a configured identity broker.

You do not create this record with authctl.

Prerequisites¶

Before you start the onboarding process, make sure that authd and a broker are installed and configured.

If you haven’t completed these steps, follow the guides on installing authd and configuring authd.

Allow the user to log in¶

The default broker configuration allows only the first user to log in. That user then becomes the owner of the machine.

To allow all users who can authenticate with the identity provider, set allowed_users to ALL:

Microsoft Entra ID

Edit /var/snap/authd-msentraid/current/broker.conf:

[users]
allowed_users = ALL

Then restart the broker:

sudo systemctl restart snap.authd-msentraid.authd-msentraid.service

Google IAM

Edit /var/snap/authd-google/current/broker.conf:

[users]
allowed_users = ALL

Then restart the broker:

sudo systemctl restart snap.authd-google.authd-google.service

Keycloak

Edit /var/snap/authd-oidc/current/broker.conf:

[users]
allowed_users = ALL

Then restart the broker:

sudo systemctl restart snap.authd-oidc.authd-oidc.service

Granting access to a specific user

If you don’t want to grant access to all users, add the user’s exact name to allowed_users:

See configure allowed users for other access policies.

Have the user log in¶

Have the user complete an online login through GDM.

To onboard through SSH, first configure ssh_allowed_suffixes_first_auth, as described in the SSH guide; first-time SSH login is disabled by default.

After the first successful login, authd creates the local account and its home directory.

Verify the user account¶

You can verify that the account is available on the system with the following commands:

getent passwd alice@example.com
id alice@example.com

Additional user management actions with authctl¶

To change the user’s local shell, home directory, or UID after onboarding, use the commands in the authctl reference.