OAuth2 provider setup - Mint Starter Kit

Overview

OAuth2 provides flexible authentication for identity providers that don’t support OpenID Connect (OIDC). While OIDC is recommended when available, OAuth2 allows you to integrate with providers that only offer OAuth2 endpoints.

When to use OAuth2

Use OAuth2 instead of OIDC when:

Your identity provider doesn’t support OIDC
You need custom user attribute mapping
You’re integrating with legacy authentication systems
Your provider requires non-standard OAuth2 flows

If your provider supports OIDC, use the OIDC configuration instead. OIDC provides standardized user information and better security.

Configuration via admin UI

Navigate to SSO providers

Go to Admin → SSO Providers in your dashboard

Add OAuth2 provider

Click “Add Provider” and select “OAuth2” as the provider type

Enter basic information

Provider name: GitHub
Provider ID: github
Enabled: Yes

Configure OAuth2 settings

Authorization URL: https://github.com/login/oauth/authorize
Token URL: https://github.com/login/oauth/access_token
User info URL: https://api.github.com/user
Client ID: your-client-id
Client secret: your-client-secret
Scopes: user:email

Configure attribute mapping

Map OAuth2 response fields to user attributes

Save and test

Save the configuration and test the login flow

Required configuration fields

Field	Description	Required	Example
Authorization URL	OAuth2 authorization endpoint	Yes	`https://provider.com/oauth/authorize`
Token URL	OAuth2 token exchange endpoint	Yes	`https://provider.com/oauth/token`
User info URL	Endpoint to fetch user profile	Yes	`https://provider.com/api/user`
Client ID	OAuth2 client identifier	Yes	`abc123xyz`
Client secret	OAuth2 client secret	Yes	`secret_abc123`
Scopes	Space-separated OAuth2 scopes	No	`user:email profile`

Provider-specific guides

GitHub

Create OAuth App

Go to GitHub Settings
Click “OAuth Apps” → “New OAuth App”
Fill in application details

Configure callback URL

Authorization callback URL: https://your-domain.com/auth/callback/github

Get credentials

Copy the Client ID and generate a Client secret

Configure in admin UI

Authorization URL: https://github.com/login/oauth/authorize
Token URL: https://github.com/login/oauth/access_token
User info URL: https://api.github.com/user
Client ID: [your-client-id]
Client secret: [your-client-secret]
Scopes: user:email

Configure attribute mapping

{
  "email": "email",
  "name": "name",
  "avatar": "avatar_url",
  "username": "login"
}

GitHub requires the user:email scope to access the user’s email address. Without this scope, email will not be available.

GitLab

Create OAuth application

Go to GitLab → User Settings → Applications
Click “Add new application”
Enter application details

Configure scopes and redirect URI

Redirect URI: https://your-domain.com/auth/callback/gitlab
Scopes: read_user, email

Save and get credentials

Copy the Application ID and Secret

Configure in admin UI

Authorization URL: https://gitlab.com/oauth/authorize
Token URL: https://gitlab.com/oauth/token
User info URL: https://gitlab.com/api/v4/user
Client ID: [application-id]
Client secret: [secret]
Scopes: read_user email

Configure attribute mapping

{
  "email": "email",
  "name": "name",
  "avatar": "avatar_url",
  "username": "username"
}

Slack

Create Slack app

Go to Slack API
Click “Create New App”
Choose “From scratch”
Enter app name and workspace

Configure OAuth & Permissions

Go to “OAuth & Permissions”
Add redirect URL:

https://your-domain.com/auth/callback/slack

Add OAuth scopes

Under “User Token Scopes”, add:

users:read
users:read.email

Get credentials

Go to “Basic Information” and copy:

Client ID
Client Secret

Configure in admin UI

Authorization URL: https://slack.com/oauth/v2/authorize
Token URL: https://slack.com/api/oauth.v2.access
User info URL: https://slack.com/api/users.identity
Client ID: [client-id]
Client secret: [client-secret]
Scopes: users:read users:read.email

Configure attribute mapping

{
  "email": "user.email",
  "name": "user.name",
  "avatar": "user.image_192"
}

Discord

Create Discord application

Go to Discord Developer Portal
Click “New Application”
Enter application name

Configure OAuth2

Go to OAuth2 settings
Add redirect:

https://your-domain.com/auth/callback/discord

Get credentials

Copy the Client ID and Client Secret from the OAuth2 page

Configure in admin UI

Authorization URL: https://discord.com/api/oauth2/authorize
Token URL: https://discord.com/api/oauth2/token
User info URL: https://discord.com/api/users/@me
Client ID: [client-id]
Client secret: [client-secret]
Scopes: identify email

Configure attribute mapping

{
  "email": "email",
  "name": "username",
  "avatar": "avatar",
  "discriminator": "discriminator"
}

Attribute mapping

OAuth2 providers return user information in different formats. Configure attribute mapping to extract user data from the provider’s response.

Common mapping patterns

Provider Field	Application Field	Description
`email`	Email	User’s email address
`name`	Full name	User’s display name
`given_name`	First name	User’s first name
`family_name`	Last name	User’s last name
`picture` or `avatar_url`	Avatar URL	User’s profile picture
`login` or `username`	Username	User’s username

Nested attributes

For nested JSON responses, use dot notation:

{
  "email": "user.email",
  "name": "user.profile.name",
  "avatar": "user.profile.image.url"
}

Array attributes

For array values, specify the index:

{
  "email": "emails[0].value"
}

OAuth2 scopes

Scopes determine what user information your application can access. Common scopes include:

Scope	Description	Providers
`email`	Access to user’s email address	Most providers
`profile`	Access to basic profile information	Most providers
`user:email`	Access to email (GitHub-specific)	GitHub
`read_user`	Read user information	GitLab
`identify`	Basic user information	Discord
`users:read`	Read user data	Slack

Only request the scopes you need. Requesting excessive permissions may cause users to deny authorization.

Redirect URI format

The redirect URI (callback URL) follows this pattern:

https://[your-domain]/auth/callback/[provider-id]

Examples:

https://app.example.com/auth/callback/github
https://app.example.com/auth/callback/gitlab
https://app.example.com/auth/callback/slack

Token handling

Access tokens

OAuth2 access tokens are used to authenticate API requests to the provider. The application:

Exchanges the authorization code for an access token
Uses the access token to fetch user information
Stores the token for future API calls (optional)

Refresh tokens

Some providers issue refresh tokens for long-lived access. Configure the offline_access or equivalent scope to request refresh tokens.

Token expiration

Access tokens typically expire after a short period (1 hour to 24 hours). The application handles token refresh automatically when refresh tokens are available.

Troubleshooting

Invalid redirect URI

Problem: Provider rejects the redirect URI Solution:

Verify the redirect URI exactly matches in both systems
Check for trailing slashes or protocol mismatches
Ensure the provider ID in the URL matches your configuration
Some providers require exact URL matching (including query parameters)

Missing email address

Problem: User email is not populated after login Solution:

Verify you’re requesting the correct scope for email access
Check that the user has a verified email in their provider account
Review the user info response in audit logs
Update attribute mapping to match the provider’s response format

Scope not granted

Problem: Provider doesn’t grant requested scopes Solution:

Verify the scopes are valid for your provider
Check that your OAuth application is approved for the requested scopes
Some scopes require additional provider configuration or approval
Review provider documentation for scope requirements

User info endpoint fails

Problem: Cannot fetch user information after authentication Solution:

Verify the user info URL is correct
Check that the access token is being sent correctly
Review the provider’s API documentation for authentication requirements
Some providers require specific headers (e.g., Accept: application/json)

Security best practices

Use HTTPS only

Always use HTTPS for redirect URIs. OAuth2 over HTTP is insecure.

Validate state parameter

The application automatically validates the state parameter to prevent CSRF attacks.

Rotate client secrets

Regularly rotate your client secrets and update them in the admin UI.

Limit scopes

Only request the scopes necessary for your application’s functionality.

Secure token storage

Access tokens are encrypted in the database. Never log or expose tokens in client-side code.

Advanced configuration

Custom headers

Some providers require custom headers for the user info request. Contact support if you need to configure custom headers.

Token endpoint authentication

The application supports multiple token endpoint authentication methods:

client_secret_post (default): Send credentials in request body
client_secret_basic: Send credentials in Authorization header

PKCE support

Proof Key for Code Exchange (PKCE) is automatically enabled for enhanced security on supported providers.

Next steps

OIDC setup

Use OIDC for providers that support it

Role mapping

Configure automatic role assignment

User management

Manage users and their connected accounts

Audit logging

Monitor OAuth2 authentication events

Getting started

App features

Development

Authentication

Third party providers

Knowledge Base

​Overview

​When to use OAuth2

​Configuration via admin UI

​Required configuration fields

​Provider-specific guides

​GitHub

​GitLab

​Slack

​Discord

​Attribute mapping

​Common mapping patterns

​Nested attributes

​Array attributes

​OAuth2 scopes

​Redirect URI format

​Token handling

​Access tokens

​Refresh tokens

​Token expiration

​Troubleshooting

​Invalid redirect URI

​Missing email address

​Scope not granted

​User info endpoint fails

​Security best practices

​Advanced configuration

​Custom headers

​Token endpoint authentication

​PKCE support

​Next steps

OIDC setup

Role mapping

User management

Audit logging

Overview

When to use OAuth2

Configuration via admin UI

Required configuration fields

Provider-specific guides

GitHub

GitLab

Slack

Discord

Attribute mapping

Common mapping patterns

Nested attributes

Array attributes

OAuth2 scopes

Redirect URI format

Token handling

Access tokens

Refresh tokens

Token expiration

Troubleshooting

Invalid redirect URI

Missing email address

Scope not granted

User info endpoint fails

Security best practices

Advanced configuration

Custom headers

Token endpoint authentication

PKCE support

Next steps