GitLab OAuth¶

This guide covers setting up GitLab as an OAuth provider for your application. GitLab OAuth works with both GitLab.com and self-hosted GitLab instances.

Creating a GitLab OAuth Application¶

Step 1: Navigate to Application Settings¶

For GitLab.com:

Go to https://gitlab.com/-/user_settings/applications
Or: User Settings > Applications

For Self-Hosted GitLab:

Go to https://your-gitlab.com/-/user_settings/applications
For group-level apps: Group Settings > Applications
For instance-wide apps (admin): Admin Area > Applications

Step 2: Configure Your Application¶

Fill in the required fields:

Name: A descriptive name for your app (e.g., “My Awesome App”)
Redirect URI: Where GitLab redirects after authorization. For development: http://localhost:8000/auth/gitlab/callback For production: https://myapp.com/auth/gitlab/callback
Scopes: Select the scopes your application needs: - read_user (recommended) - email (if you need email access)

Step 3: Get Your Credentials¶

After creating the app:

Note your Application ID (client ID)
Copy your Secret (client secret)

Warning

Never commit your Secret to version control. Use environment variables or a secrets manager.

Usage Example¶

from litestar import Litestar
from litestar_oauth.contrib.litestar import OAuthPlugin, OAuthConfig

app = Litestar(
    plugins=[
        OAuthPlugin(
            config=OAuthConfig(
                redirect_base_url="https://example.com",
                gitlab_client_id="your-application-id",
                gitlab_client_secret="your-secret",
                gitlab_url="https://gitlab.com",  # or your self-hosted URL
                gitlab_scope="read_user email",
            )
        )
    ],
)

from litestar_oauth.providers import GitLabOAuthProvider

# For GitLab.com
provider = GitLabOAuthProvider(
    client_id="your-application-id",
    client_secret="your-secret",
    scope=["read_user", "email"],
)

# For self-hosted GitLab
provider = GitLabOAuthProvider(
    client_id="your-application-id",
    client_secret="your-secret",
    base_url="https://gitlab.mycompany.com",
    scope=["read_user", "email"],
)

# Generate authorization URL
auth_url = await provider.get_authorization_url(
    redirect_uri="https://example.com/auth/gitlab/callback",
    state="random-state-token",
)

# After callback, exchange code for token
token = await provider.exchange_code(
    code="authorization-code",
    redirect_uri="https://example.com/auth/gitlab/callback",
)

# Get user info
user_info = await provider.get_user_info(token.access_token)

Self-Hosted GitLab¶

To use a self-hosted GitLab instance, provide the base_url parameter:

provider = GitLabOAuthProvider(
    client_id="your-application-id",
    client_secret="your-secret",
    base_url="https://gitlab.mycompany.com",
)

The provider will automatically construct the correct OAuth endpoints based on your base URL.

Available Scopes¶

GitLab offers various scopes:

Scope	Description
`read_user`	Read user profile (username, email, avatar)
`email`	Read user’s email address
`api`	Full API access (read/write)
`read_api`	Read-only API access
`read_repository`	Read repository contents
`write_repository`	Write to repository
`openid`	OpenID Connect authentication
`profile`	Read user profile info (OIDC)

Default scopes in litestar-oauth: read_user, email

User Info Response¶

GitLab API returns user data. Here’s what litestar-oauth extracts:

OAuthUserInfo(
    provider="gitlab",
    oauth_id="12345",                        # GitLab user ID
    email="user@example.com",                # User email
    email_verified=True,                     # Based on confirmed_at field
    username="johndoe",                      # GitLab username
    first_name="John",                       # Parsed from name field
    last_name="Doe",                         # Parsed from name field
    avatar_url="https://gitlab.com/uploads/-/system/user/avatar/...",
    profile_url="https://gitlab.com/johndoe",
    raw_data={...},                          # Complete API response
)

Troubleshooting¶

“Invalid redirect URI”: The callback URL must exactly match what’s registered in GitLab, including the protocol (http/https) and any trailing slashes.
“401 Unauthorized” when fetching user info: Check that you’ve requested the read_user scope and that your access token hasn’t expired.
Self-hosted SSL errors: If your self-hosted GitLab uses a self-signed certificate, you may need to configure httpx to trust it or disable verification (not recommended for production).

Next Steps¶

OAuth Providers - Explore other OAuth providers
API Reference - Complete API reference