Users and authentication

Aurral supports several users. Each user has their own permissions, playlists, listening history, and recommendations. Admins manage users in Settings > Users.

Permissions

An admin can give each user these permissions:

Permission	Built-in default
Access playlists and downloads	Off
Add artist	On
Add album	On
Change artist monitoring	Off
Delete artists	Off
Delete albums	Off
Delete tracks	Off

Admins have every permission.

To change what new users start with, open Settings > Users > Default permissions. The defaults apply to every account created afterwards, including accounts made by SSO or proxy sign-in. Existing users keep their permissions.

Account status

To stop a user from using Aurral without deleting the account, open Manage for the user and set Status to Suspended or Disabled. The two values have the same effect:

• The user cannot sign in with any method.
• Aurral ends the user’s sessions at once.
• The user’s scheduled flows do not run.
• Automatic upgrades and Search all skip the user’s playlists.

Set Status to Active to restore the account. You cannot suspend or disable the protected recovery admin.

Ways to sign in

Aurral supports these sign-in methods:

• A local username and password
• Local-network auto-login, for a single admin on a home network
• Native OpenID Connect (OIDC)
• Google, for users who linked a Google account
• Reverse-proxy authentication

A user can always sign in with their local password, if they have one.

Local-network auto-login

Auto-login signs in the only user automatically from the server’s local network. Turn it on during first-run setup, or in Settings > Users > Local network auto-login.

Auto-login works only when all these conditions are true:

• Setup is complete.
• Exactly one user exists, and that user is an admin.
• Aurral can find one trusted IPv4 subnet for the server.

When you add a second user, Aurral turns auto-login off. The setting shows why auto-login is unavailable when a condition is not met.

Native OIDC

Set OIDC_ENABLED=true and register Aurral as a client with your identity provider.

Required variables:

• OIDC_ISSUER: the issuer URL, used for discovery.
• OIDC_CLIENT_ID: the client ID.
• OIDC_CLIENT_SECRET: the client secret. It is not required when OIDC_TOKEN_ENDPOINT_AUTH_METHOD is none.
• OIDC_REDIRECT_URI: exactly https://aurral.example.com/sso/callback, with your Aurral host.

Optional role mapping:

• OIDC_DEFAULT_ROLE: user, the default, or admin.
• OIDC_ADMIN_USERS: usernames that get the admin role at sign-in.
• OIDC_GROUPS_CLAIM: the ID-token claim that holds group membership.
• OIDC_ADMIN_GROUPS: the groups in that claim that give the admin role.

See Environment variables for every OIDC variable.

The sign-in page shows Sign in with SSO. Aurral starts the sign-in at /api/auth/oidc/login, receives the result at /sso/callback, and then creates a normal Aurral session. The username comes from the OIDC_USERNAME_CLAIM claim, which is preferred_username by default. If that claim is missing, Aurral uses email.

The first OIDC sign-in of a new person creates an Aurral account. If the username is taken, Aurral adds the first free number, such as -2. The identity provider sets the role at each OIDC sign-in, so a role that you change in Aurral changes back at the next sign-in.

An account created by OIDC has no local password until an admin sets one.

To end the identity-provider session when a user selects Log out, set OIDC_LOGOUT_URL.

You can configure native OIDC and reverse-proxy authentication together. Choose one of them as the main sign-in method for your deployment.

Link SSO to an existing account

A user who already has an Aurral account can link SSO to it:

1. Sign in another way, for example with the local password.
2. Open Settings > Profile and select Connect next to Single sign-on under Sign-in methods.
3. Confirm the password if Aurral asks, then sign in with the identity provider.

Later SSO sign-ins open this account. Aurral refuses the link if the SSO account already belongs to another Aurral account. After the link, the identity provider sets the role at each SSO sign-in, as for any OIDC account. If it does not give the user the admin role, an admin who signs in with SSO becomes a regular user. The protected recovery admin keeps its role.

Sign in with Google

Google sign-in lets a user sign in to an account that already exists. It never creates an account and never changes a role. A user must link the Google account first, while signed in another way.

Set up Google sign-in

1. In the Google Cloud Console, create an OAuth client. Add the redirect URI https://aurral.example.com/sso/google/callback, with your Aurral host.
2. In Aurral, open Settings > Users > Google.
3. Enter the Client ID, Client secret, and Redirect URI.
4. Turn on Enabled.

Each user then opens Settings > Profile > Sign-in methods and selects Connect next to Google. After that, the user can select Sign in with Google on the sign-in page.

Plex sign-in was removed

Aurral no longer offers Sign in with Plex. Users who signed in with Plex use their password, Google, or single sign-on instead. An admin can set a password for a user in Settings > Users. If the admin signed in with Plex too, reset the admin password from the server.

Manage connected accounts

Settings > Profile > Sign-in methods lists the SSO and Google identities linked to your account. To remove one, select Disconnect.

You cannot remove your last way to sign in. If your account has no local password, set a password or link another account first.

Confirm your password for account changes

Some account changes need a recent sign-in:

• Change your password
• Connect or disconnect Google

If you signed in more than 15 minutes ago, Aurral asks for your current password first. If your account has no local password, sign out and sign in again, then retry.

SSO-only sign-in mode

To hide the username and password form on the sign-in page, open Settings > Users > Sign-in and turn on SSO-only. The setting has an effect only when OIDC or Google sign-in is configured.

The sign-in page still shows Sign in with a local account instead, so local accounts and the recovery admin cannot be locked out.

Reverse-proxy authentication

Set AUTH_PROXY_ENABLED=true to trust a username that your reverse proxy sends. The default header is x-forwarded-user. To use another header, set AUTH_PROXY_HEADER.

Caution

Set AUTH_PROXY_TRUSTED_IPS to the address of your reverse proxy. Without it, any client that can reach Aurral can send the header and act as any user.

When a new username first arrives from the proxy, Aurral creates a local user with that name. The role comes from these settings:

• AUTH_PROXY_DEFAULT_ROLE: the role for users who do not get the admin role another way.
• AUTH_PROXY_ADMIN_USERS: usernames that get the admin role.
• AUTH_PROXY_ROLE_HEADER and AUTH_PROXY_ADMIN_GROUPS: a header with the user’s groups, such as Authelia’s Remote-Groups, and the groups that give the admin role.

Aurral checks the role on every request. A role change in the proxy or identity provider applies at the next request. You do not have to edit the account in Aurral.

On the first request that your proxy authenticates, Aurral creates its own session, and the browser uses it for later API calls. To change how long a session lasts, set SESSION_EXPIRY_HOURS.

Page loads always go to the network, not to Aurral’s offline cache, so your proxy can send them to the identity provider when its session ends.

Most setups also protect /api with the proxy, so the proxy checks every request. An open tab has no page load to redirect. When the proxy rejects one of its API calls, Aurral reloads the tab, which sends it through the proxy again. Aurral reloads at most once every 30 seconds, so a wrong proxy setup cannot cause a reload loop.

If the proxy protects only page loads and leaves /api to Aurral’s session, an open page keeps working after the identity-provider session ends, until the Aurral session expires.

Authentik

Route /outpost.goauthentik.io directly to the Authentik outpost. Do not protect that route with auth_request. Check the route before you test Aurral:

curl -i https://aurral.example.com/outpost.goauthentik.io/ping

The response must be 204.

To end the Authentik session when a user logs out of Aurral, set:

AUTH_PROXY_LOGOUT_URL=https://aurral.example.com/outpost.goauthentik.io/sign_out

While proxy authentication is on and AUTH_PROXY_LOGOUT_URL is not set, Aurral hides Log out, because ending the Aurral session cannot end the proxy session.

An account created by the proxy has no local password until an admin sets one. Admins manage these accounts in Settings > Users.

Reset the admin password

Run this command next to your docker-compose.yml:

docker compose exec aurral node backend/scripts/resetAdminPassword.ts --password "new-password"

To generate a random password, use --generate instead of --password. From a source checkout, run pnpm run auth:reset-admin-password with the same options.

It resets the first admin account, or creates an admin account if there is none. Add --username <name> to reset another one.