Single sign-on

Tdarr supports Google, Microsoft, GitHub, and custom OpenID Connect (OIDC) sign-in. Google, Microsoft, and custom providers use OIDC. GitHub uses OAuth 2.0.

Each Tdarr instance needs its own application or client registration with each provider. There is no shared Tdarr OAuth client.

Requirements

• Run the Tdarr Server with TDARR_ENGINE=rust.
• Enable authentication with auth=true.
• Use a stable browser-facing URL for the WebUI. HTTPS is strongly recommended except for localhost testing.
• Keep password login available for an administrator until SSO has been tested.

Configure SSO

Create the first Tdarr administrator through the normal local registration flow. Then:

1. Sign in with a local administrator account.
2. Open Tools -> SSO.
3. Select Set up for a provider.
4. Follow the instructions in the dialog to create an application with the provider.
5. Enter the requested credentials, then select Save and enable.

Settings saved through the WebUI take effect without a Server restart. Credentials are stored in Tdarr's SQLite database and are not displayed again. Treat the database and its backups as sensitive.

Each provider has its own callback URL. Copy the URL shown by Tdarr exactly:

Provider	Callback path
Google	/api/v2/public/auth/sso/google/callback
Microsoft	/api/v2/public/auth/sso/microsoft/callback
GitHub	/api/v2/public/auth/sso/github/callback
Custom OIDC	/api/v2/public/auth/sso/oidc/callback

For example:

https://tdarr.example.com/api/v2/public/auth/sso/google/callback

The scheme, hostname, port, reverse-proxy prefix, and path must match the provider registration. Use the URL that users enter in their browser, not an internal container address. Do not add a trailing slash, query string, or fragment.

Provider setup

Google

1. Open Google Auth Platform from the Tdarr setup dialog.
2. Create or select a project and configure its branding and audience.
3. Under Clients, create a Web application client.
4. Add the Google callback URL shown by Tdarr to Authorized redirect URIs.
5. Create the client and download its JSON credentials file.
6. Return to Tdarr and select that file.

If the application is external and in testing mode, add each permitted account as a test user. See Google's OAuth web application guide and OpenID Connect guide.

Microsoft

1. Open Microsoft Entra app registrations from the Tdarr setup dialog.
2. Select New registration, enter a name, and choose the supported account types.
3. Under Authentication, add a Web platform with the Microsoft callback URL shown by Tdarr.
4. Under Certificates & secrets, create a client secret and copy its Value. Do not copy the Secret ID.
5. From Overview, copy the Application (client) ID.
6. Enter the client ID, client secret, and tenant in Tdarr.

Use common for work, school, and personal Microsoft accounts, organizations for work and school accounts, consumers for personal accounts, or a Directory tenant ID for one organization. The selected tenant must agree with the app registration's supported account types. See Microsoft's app registration guide and redirect URI guide.

GitHub

1. Open the GitHub OAuth application page from the Tdarr setup dialog.
2. Enter a name and set Homepage URL to the browser-facing URL of this Tdarr instance.
3. Set Authorization callback URL to the GitHub callback URL shown by Tdarr.
4. Register the application, copy its Client ID, and generate a client secret.
5. Enter the Client ID and client secret in Tdarr.

The GitHub account must have a verified email address. See GitHub's OAuth app creation guide.

Custom OIDC

Use this option for an OIDC provider such as AWS Cognito, Auth0, Okta, or Keycloak.

1. Create a confidential web application or client with the provider.
2. Enable the authorization code flow and allow the openid and email scopes.
3. Add the Custom OIDC callback URL shown by Tdarr to the allowed callback URLs.
4. Configure the ID token to include a non-empty email claim and email_verified: true.
5. Enter the issuer URL, client ID, and client secret in Tdarr.

The issuer must provide OIDC discovery at ISSUER/.well-known/openid-configuration and must exactly match the token's issuer.

For AWS Cognito, create a user pool app client for a traditional web application, generate a client secret, enable the authorization code grant with the openid and email scopes, and configure a user pool domain for managed login. Use the user pool issuer shown by AWS. Depending on the pool's issuer configuration, it has one of these formats:

https://cognito-idp.REGION.amazonaws.com/USER_POOL_ID
https://issuer-cognito-idp.REGION.amazonaws.com/USER_POOL_ID

Do not use the managed login domain as the issuer. See the AWS guides for app clients, user pool domains, and OIDC endpoints.

Give users access

Enabling a provider does not open registration. Every provider account must be linked or assigned to a Tdarr user:

• To link an existing account, the user signs in locally, opens Tools -> Account, selects SSO, and completes provider sign-in.
• To create an SSO-only account, an administrator opens Tools -> Users, creates a user, enables SSO-only account, and enters the email address returned by the provider.

Tdarr roles remain managed in Tools -> Users. A provider account never grants the Tdarr administrator role by itself.

After an identity is linked, an administrator cannot replace or remove it. The user can unlink it only while another login method remains. Before unlinking the current provider, enable password login or sign in through a different linked provider.

An administrator cannot add password login to another user's SSO-only account, including by resetting its password. A user can re-enable password login from Tools -> Account only if they disabled it themselves or have the administrator role. Keep at least one tested local administrator account so a provider outage or configuration error does not lock out all administrators.

Disable a provider

Turning off a provider prevents future sign-in attempts through it. Users who are already signed in remain signed in until their existing sessions end.

Environment-managed setup

The WebUI setup is recommended. To manage a provider through environment variables instead, set its enabled variable to true and its credentials file variable to the file path:

Provider	Enabled	Credentials file
Google	googleSsoEnabled	googleSsoCredentialsFile
Microsoft	microsoftSsoEnabled	microsoftSsoCredentialsFile
GitHub	githubSsoEnabled	githubSsoCredentialsFile
Custom OIDC	oidcSsoEnabled	oidcSsoCredentialsFile

Relative credential paths are resolved beside Tdarr_Server_Config.json; absolute paths are also accepted. If either environment variable for a provider is set, those settings take precedence over its database settings and the provider becomes read-only in the WebUI. Environment changes require a Server restart.

For Google, use the JSON file downloaded from Google. Microsoft and GitHub credential files use this structure:

{
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "redirect_uri": "https://tdarr.example.com/api/v2/public/auth/sso/PROVIDER/callback",
  "tenant": "common"
}

Only Microsoft uses tenant; omit it for GitHub. Replace PROVIDER with microsoft or github.

Custom OIDC uses:

{
  "issuer": "https://identity.example.com",
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "redirect_uri": "https://tdarr.example.com/api/v2/public/auth/sso/oidc/callback"
}

Do not commit credential files or place them in the WebUI public directory.

Separate frontend URL

Tdarr normally derives the post-login destination from the callback URL. If the browser-facing frontend uses a different URL, set ssoFrontendUrl to that URL:

environment:
  - ssoFrontendUrl=https://tdarr.example.com

This is not a callback URL. It must begin with http:// or https:// and should not have a trailing slash.

Test the setup

1. Keep the local administrator session open.
2. Link a provider from Tools -> Account.
3. Use a private browser window to sign in through that provider.
4. Confirm that the correct Tdarr account and roles are used.
5. Test an SSO-only user before relying on SSO for administrators.

Troubleshooting

The login page shows Set up SSO

No provider is currently available. Confirm that at least one provider is enabled and has valid credentials. For environment-managed settings, restart the Server after making changes.

Redirect URI mismatch

Compare the provider's registered callback URL with the URL shown by Tdarr. Every part must match exactly. For Google, the downloaded JSON must contain the same URL in redirect_uris.

Account is not assigned

SSO is not open registration. Link the provider from an existing Tdarr account, or ask an administrator to assign the matching provider email to a user in Tools -> Users.

Custom OIDC requires a verified email

The provider's ID token must contain both a non-empty email claim and email_verified: true. Requesting the email scope alone does not guarantee that the provider will include them.

Microsoft error AADSTS50020

The Microsoft account type is not allowed by the app registration or selected tenant. Check both settings and try again.

GitHub does not return an email

Verify an email address on the GitHub account. Tdarr uses the verified primary address, or another verified address if no verified primary address is available.