OAuth / SSO

Truetask supports OAuth 2.0 and OpenID Connect (OIDC) for enterprise single sign-on (SSO). Users can authenticate with their existing corporate identity provider — Active Directory, Okta, Azure AD, Keycloak, or any OIDC-compliant provider — instead of managing separate credentials.

Enterprise feature

OAuth requires an Enterprise license.

Supported providers

Provider	Type
GitHub	Pre-configured
GitLab	Pre-configured
Gitea	Pre-configured
Gitee	Pre-configured
Linear	Pre-configured
Notion	Pre-configured
OIDC 2.0	Generic OpenID Connect
OIDC 3.0	Generic OpenID Connect

The OIDC providers allow connecting to any OAuth 2.0 / OpenID Connect compliant identity provider, including Okta, Auth0, Azure AD, Keycloak, and others.

Setup

1. Go to Settings > Server > OAuth
2. Select a provider and configure:

Field	Description
Client ID	OAuth application client ID from your provider
Client Secret	OAuth application client secret
Auth URL	Authorization endpoint (auto-filled for pre-configured providers)
Token URL	Token exchange endpoint (auto-filled for pre-configured providers)
User Info URL	User profile endpoint (auto-filled for pre-configured providers)
Display Name	Label shown on the login button

3. Configure field mappings to map your provider's user data to Truetask fields:

Truetask Field	Maps To	Description
ID	Unique identifier	Used to match returning users
Name	Display name	Shown in the UI
Username	Username	Used for mentions
Avatar URL	Profile picture URL	User avatar

4. Optionally enable PKCE (Proof Key for Code Exchange) for enhanced security
5. Save

Creating an OAuth application

Each provider requires you to register an OAuth application. The callback URL to use is:

https://your-truetask-url/api/oauth2-redirect

Replace your-truetask-url with your Truetask PUBLIC_URL.

Example: GitHub

1. Go to GitHub > Settings > Developer settings > OAuth Apps > New OAuth App
2. Set Authorization callback URL to https://your-truetask-url/api/oauth2-redirect
3. Copy the Client ID and Client Secret into Truetask

Example: Generic OIDC (Okta, Azure AD, Keycloak)

1. Register an application in your identity provider
2. Set the redirect URI to https://your-truetask-url/api/oauth2-redirect
3. In Truetask, select OIDC 2.0 or OIDC 3.0
4. Fill in the Auth URL, Token URL, and User Info URL from your provider's documentation
5. Map the user fields according to your provider's token claims

How it works

• Users see an OAuth login button on the sign-in page
• Clicking it redirects to the identity provider for authentication
• After authenticating, the user is redirected back to Truetask
• If the user doesn't have a Truetask account, one is created automatically
• Subsequent logins match the user by their provider ID

Multiple providers

You can configure multiple providers simultaneously. Each appears as a separate button on the login page. Users can link multiple providers to the same Truetask account.

Considerations

• OAuth is for authentication only — it does not sync roles, groups, or permissions from the identity provider.
• PKCE is recommended for all providers that support it. It prevents authorization code interception attacks.
• OAuth secrets are encrypted in the database if settings encryption is enabled.
• Test in staging first — verify field mappings and callback URLs before enabling in production.