OAuth Providers

SetGet supports OAuth 2.0 authentication with external providers, allowing users to sign in using their existing accounts from Google, GitHub, GitLab, or Gitea. This simplifies the sign-in experience and reduces the number of passwords users need to manage.

Supported providers

Provider	Protocol	Use case
Google	OAuth 2.0	Organizations using Google Workspace or personal Google accounts
GitHub	OAuth 2.0	Development teams with GitHub accounts
GitLab	OAuth 2.0	Teams using GitLab (cloud or self-hosted)
Gitea	OAuth 2.0	Teams using self-hosted Gitea instances

How OAuth authentication works

1. The user clicks the provider button on the SetGet sign-in page (e.g., "Sign in with Google").
2. The browser redirects to the provider's authorization page.
3. The user authenticates with the provider and grants SetGet permission to access their profile.
4. The provider redirects back to SetGet with an authorization code.
5. SetGet exchanges the code for an access token and retrieves the user's profile (email, name).
6. SetGet signs the user in (or creates a new account if this is their first sign-in).

General setup steps

Every OAuth provider follows the same general configuration pattern:

1. Create an OAuth application in the provider's developer console.
2. Note the Client ID and Client Secret generated by the provider.
3. Set the Callback URL (redirect URI) in the provider to point to your SetGet instance.
4. Enter the Client ID and Client Secret in SetGet's admin settings.
5. Enable the provider.

Callback URLs

Each provider has a dedicated callback URL:

Provider	Callback URL
Google	https://your-setget-domain.com/auth/google/callback
GitHub	https://your-setget-domain.com/auth/github/callback
GitLab	https://your-setget-domain.com/auth/gitlab/callback
Gitea	https://your-setget-domain.com/auth/gitea/callback

WARNING

Replace your-setget-domain.com with your actual SetGet instance domain. The callback URL must match exactly, including the protocol (https) and path. A mismatch causes authentication to fail with a "redirect_uri_mismatch" error.

Configure Google OAuth

Step 1: Create OAuth credentials in Google Cloud

1. Go to the Google Cloud Console.
2. Select or create a project.
3. Navigate to APIs & Services > Credentials.
4. Click Create Credentials > OAuth Client ID.
5. Select Web application as the application type.
6. Set the Authorized redirect URI to your SetGet Google callback URL.
7. Click Create.
8. Note the Client ID and Client Secret.

Step 2: Configure in SetGet

1. Navigate to Admin Panel > Authentication (or Workspace Settings > Security > OAuth).
2. Find the Google section.
3. Enter the Client ID and Client Secret.
4. Click Save.
5. Toggle Enable Google OAuth to on.

Google-specific settings

Setting	Description
Restrict to domain	Optionally restrict sign-in to users from a specific Google Workspace domain (e.g., yourcompany.com)
Allow personal accounts	Whether to allow non-Workspace Google accounts

TIP

If your organization uses Google Workspace, restricting OAuth to your domain prevents external Google accounts from signing in.

Configure GitHub OAuth

Step 1: Create an OAuth app in GitHub

1. Go to GitHub > Settings > Developer settings > OAuth Apps.
2. Click New OAuth App.
3. Fill in the details:

Field	Value
Application name	SetGet (or your preferred name)
Homepage URL	https://your-setget-domain.com
Authorization callback URL	https://your-setget-domain.com/auth/github/callback

4. Click Register application.
5. Note the Client ID.
6. Click Generate a new client secret and note the Client Secret.

Step 2: Configure in SetGet

1. Navigate to Admin Panel > Authentication.
2. Find the GitHub section.
3. Enter the Client ID and Client Secret.
4. Click Save.
5. Toggle Enable GitHub OAuth to on.

GitHub-specific settings

Setting	Description
Require organization membership	Optionally restrict sign-in to members of a specific GitHub organization
Organization name	The GitHub organization slug (e.g., my-org)

Configure GitLab OAuth

Step 1: Create an OAuth application in GitLab

For GitLab.com:

1. Go to GitLab > Preferences > Applications.
2. Click New Application.
3. Fill in the details:

Field	Value
Name	SetGet
Redirect URI	https://your-setget-domain.com/auth/gitlab/callback
Scopes	read_user, openid, email
Confidential	Yes

4. Click Save application.
5. Note the Application ID (Client ID) and Secret (Client Secret).

For self-hosted GitLab:

1. As an admin, go to Admin Area > Applications.
2. Follow the same steps as above.

Step 2: Configure in SetGet

1. Navigate to Admin Panel > Authentication.
2. Find the GitLab section.
3. Enter the Client ID and Client Secret.
4. If using a self-hosted GitLab instance, enter the GitLab URL (e.g., https://gitlab.yourcompany.com).
5. Click Save.
6. Toggle Enable GitLab OAuth to on.

GitLab-specific settings

Setting	Description
GitLab URL	The base URL of your GitLab instance (default: https://gitlab.com)
Require group membership	Optionally restrict sign-in to members of a specific GitLab group

Configure Gitea OAuth

Step 1: Create an OAuth application in Gitea

1. Sign in to your Gitea instance as an admin.
2. Go to Site Administration > Applications.
3. Click Create a new OAuth2 Application.
4. Fill in the details:

Field	Value
Application Name	SetGet
Redirect URI	https://your-setget-domain.com/auth/gitea/callback

5. Click Create Application.
6. Note the Client ID and Client Secret.

Step 2: Configure in SetGet

1. Navigate to Admin Panel > Authentication.
2. Find the Gitea section.
3. Enter the Client ID and Client Secret.
4. Enter the Gitea URL (e.g., https://gitea.yourcompany.com).
5. Click Save.
6. Toggle Enable Gitea OAuth to on.

Gitea-specific settings

Setting	Description
Gitea URL	The base URL of your Gitea instance (required; no default)

Enable and disable providers

Enable a provider

1. Navigate to Admin Panel > Authentication.
2. Ensure the Client ID and Client Secret are configured.
3. Toggle the provider to Enabled.
4. The provider's button appears on the sign-in page.

Disable a provider

1. Navigate to Admin Panel > Authentication.
2. Toggle the provider to Disabled.
3. The provider's button is removed from the sign-in page.

WARNING

Disabling a provider does not delete existing accounts created through that provider. Users who previously signed in with the disabled provider can still sign in using email/password or another enabled method (if they have set one up).

Account linking

When a user signs in with an OAuth provider and an account with the same email already exists:

Scenario	Behavior
Email matches an existing account	Accounts are linked; user signs in to existing account
Email does not match any account	New account is created
User unlinks an OAuth provider	They can still sign in with email/password or other providers

Users can view and manage linked OAuth providers in Profile Settings > Security > Connected Accounts.

Provider comparison

Feature	Google	GitHub	GitLab	Gitea
Cloud hosted	Yes	Yes	Yes (gitlab.com)	No (self-hosted only)
Self-hosted support	No	No (GitHub Enterprise has different setup)	Yes	Yes
Domain restriction	Yes	Via org membership	Via group membership	No
Scopes required	email, profile	user:email	read_user, openid, email	user
Setup complexity	Low	Low	Medium	Medium

Security considerations

• Store Client Secrets securely — never commit them to version control or expose them in frontend code.
• Use HTTPS — OAuth callback URLs must use HTTPS in production.
• Restrict by domain or org — when possible, limit who can authenticate to prevent unauthorized access.
• Review connected accounts — periodically audit which OAuth providers are linked to user accounts.
• Rotate secrets — regenerate Client Secrets periodically and update them in SetGet.

Troubleshooting

Issue	Likely cause	Resolution
"redirect_uri_mismatch" error	Callback URL mismatch	Verify the callback URL in the provider matches exactly
"invalid_client" error	Client ID or Secret incorrect	Re-check credentials in provider console
Provider button not appearing	Provider not enabled	Toggle the provider to Enabled in admin settings
Account not linked	Email addresses differ	Ensure the OAuth provider returns the same email as the SetGet account
Self-hosted GitLab/Gitea fails	GitLab/Gitea URL not set	Enter the correct base URL in SetGet settings
SSL errors with self-hosted providers	Certificate not trusted	Ensure the self-hosted instance uses a valid SSL certificate

Related pages

• Security Overview — authentication and authorization overview
• SSO — SAML-based enterprise authentication
• MFA — multi-factor authentication
• Session Management — manage active sessions