OAuth2 is a widely-used authorization standard that allows your users to sign into your Vanilla community using credentials managed by your organization's identity provider. It's similar to how "Sign in with Google" works on many websites: users authenticate with a trusted provider and are granted access to your community without needing a separate password.
Vanilla's OAuth2 addon also supports OpenID Connect (OIDC), which is a layer built on top of OAuth2 that standardizes how user identity information is shared.
Is OAuth2 right for your community?
OAuth2 is likely the right choice if:
- Your IT team has mentioned "OAuth" or "OIDC" as your organization's standard
- You're integrating with a custom-built identity system or application
- Your identity provider doesn't support SAML but does support OAuth2/OIDC
- You need to connect to a system like Auth0, Okta (via OAuth), Azure AD (via OAuth), or a custom authentication server
If you're unsure which SSO method your organization uses, ask your IT team: "Do we use OAuth2 or OpenID Connect for single sign-on with third-party applications?"
Before you begin
You'll need to coordinate with your IT team to complete this setup. Here's what to gather before you start.
The information exchange
OAuth2 configuration requires information to flow both directions between you and your IT team.
What your IT team will need from you first
Your IT team will need to register your Vanilla community as an authorized application in their identity provider. They'll ask for a Redirect URI (also called a Callback URL).
Your redirect URI will be:
https://[your-community-domain]/entry/oauth2
Replace [your-community-domain] with your actual community URL (for example: community.yourcompany.com).
What your IT team will provide to you
Once they've registered your application, ask them for:
- Client ID: A unique identifier for your application (sometimes called "Application ID")
- Client Secret: A confidential key used to authenticate your application (keep this secure)
- Authorize URL: The URL where users are sent to log in (sometimes called "Authorization Endpoint")
- Token URL: The URL used to exchange authorization codes for access tokens (sometimes called "Token Endpoint")
- Profile URL: The URL used to retrieve user profile information (sometimes called "UserInfo Endpoint") — required if not using OIDC discovery
If your IT team uses OpenID Connect (OIDC)
They may be able to provide a Discovery URL (also called "Well-Known URL" or "OIDC Discovery Endpoint") that looks like:
https://[identity-provider]/.well-known/openid-configuration
This document contains the Authorize URL, Token URL, and Profile URL, which can simplify configuration.
User attributes
By default, your identity provider should send at minimum:
- Email address
- Display name (or first name and last name)
- A unique user identifier
If your organization wants to pass additional information (like department, job title, or profile photo), let your IT team know which attributes they should include. You'll map these in the Vanilla Dashboard later.
Vanilla's OAuth2 addon supports dot notation for mapping nested user data. For example, if your identity provider returns:
json
{ "contact": { "email": "user@company .com" }}
You can map the email field as contact.email.
Step-by-step setup in Vanilla
Step 1: Verify the OAuth2 SSO addon is enabled
- Sign in to your Vanilla community as an Administrator.
- Access the Dashboard.
- Navigate to Settings > Addons.
- Look for OAuth2 SSO in the list and make sure it's toggled On.
NOTE: If you don't see the OAuth2 SSO addon, or it's not enabled, contact your Vanilla primary contact or Vanilla Support. The addon needs to be provisioned for your community before you can configure it.
Step 2: Access OAuth2 settings
- Access the Dashboard.
- Navigate to Settings > OAuth2 SSO.
(or go directly to: https://[your-community-domain]/oauth2-settings) - Click Add Connection to create a new OAuth2 configuration.
Step 3: Configure your connection
Complete the following fields using the information from your IT team:
- Client ID: Paste the Client ID provided by your IT team.
- Connection Name: A display name for this connection. This will appear on the sign-in button.
- Example:
Sign in with Corporate SSO or Company Login
- Client Secret: Paste the Client Secret provided by your IT team. This is confidential; treat it like a password.
- Authorize URL: Paste the Authorize URL (Authorization Endpoint) provided by your IT team.
- Example:
https://login.yourcompany.com/oauth2/authorize
- Token URL: Paste the Token URL (Token Endpoint) provided by your IT team.
- Example:
https://login.yourcompany.com/oauth2/token
- Profile URL: Paste the Profile URL (UserInfo Endpoint) provided by your IT team. This is where Vanilla retrieves user information after authentication.
- Example:
https://login.yourcompany.com/oauth2/userinfo
Step 4: Configure attribute mapping
Your identity provider may use different names for user attributes than Vanilla expects. Map them in the Attribute Mapping section.
Common mappings include:
Vanilla expects | Your IDP might send |
|---|
UniqueID
| sub, id, userId, employeeId
|
Email
| email, mail, emailAddress
|
Name
| name, displayName, fullName
|
Photo
| picture, avatar, photoUrl
|
Roles
| groups, roles, memberOf
|
For nested data, use dot notation. For example, if the email is returned as { "contact": { "email": "..." } }, map it as contact.email.
Your IT team can provide the exact attribute names their system sends, or you can find them by examining a sample response from their userinfo endpoint.
Step 5: Configure additional options
- Visible on Sign In page: Toggle this On if you want users to see a button for this connection on the sign-in page. Toggle Off if you want this connection to be available but not displayed (for example, if you're using it as the default and don't need a button).
- Set as Default: Check this if you want this to be the primary sign-in method. When set as default, clicking "Sign In" will immediately redirect users to this provider.
Step 6: Save and toggle the connection on
- Click Save.
- Toggle the connection On.
Test your configuration
Test sign-in URL
Once configured, your OAuth2 sign-in URL will be:
https://[your-community-domain]/entry/oauth2-redirect?client_id=[ClientID]
For example, if your Client ID is vanilla-community-app:
https://community.yourcompany.com/entry/oauth2-redirect?client_id=vanilla-community-app
How to test
- Open a private/incognito browser window (to avoid using an existing session).
- Navigate to your community.
- Click Sign In.
- You should see a button with your Connection Name (e.g., "Sign in with Corporate SSO").
- Click the button. You should be redirected to your identity provider.
- Sign in with your credentials.
- You should be redirected back to your community and signed in.
What success looks like
- You're redirected to your identity provider's login page
- After authenticating, you're asked to grant permissions (if your IDP shows a consent screen)
- You return to the community signed in
- Your display name and email appear correctly in your profile
Troubleshooting common issues
"I click Sign In but nothing happens" or the button doesn't appear
The connection may not be fully configured or toggled on. Verify:
- The connection is toggled On in the OAuth2 settings
- All required fields are filled in (Client ID, Secret, Authorize URL, Token URL, Profile URL)
- "Visible on Sign In page" is toggled On (if you expect to see a button)
"Invalid client" or "client_id not found" error
The Client ID may be incorrect or the application may not be registered properly in your identity provider. Verify:
- The Client ID matches exactly what your IT team provided (no extra spaces)
- Your IT team has finished registering the application on their end
- The Redirect URI they configured matches
https://[your-community-domain]/entry/oauth2
"Invalid redirect URI" or "redirect_uri mismatch" error
Your IT team needs to add your exact Redirect URI to their allowed list. Send them:
https://[your-community-domain]/entry/oauth2
The URL must match exactly, including https:// and no trailing slash.
Users are created but names or emails are wrong/missing
Check your attribute mapping. The attributes being sent may not match what Vanilla is expecting. Ask your IT team for a sample of the user data their system returns, then update your mappings accordingly.
"I'm stuck in a redirect loop"
This usually means the authentication succeeded but something went wrong creating the user session. Common causes:
- The Profile URL is incorrect or not returning user data
- Required attributes (like
email or unique ID) are missing from the response - Contact Vanilla support with details about when this happens
"Access denied" or "unauthorized" error
This could mean:
- The Client Secret is incorrect
- The user doesn't have permission to access this application in your identity provider
- Ask your IT team to verify the user is authorized and the credentials are correct
Information for your IT team
You can copy this section and send it to your IT team to help them configure your identity provider.
OAuth2/OIDC Configuration Request for Vanilla Community
We're setting up OAuth2 single sign-on for our Vanilla community. Please register our application in your identity provider with the following settings:
Application Details:
- Application Name: Vanilla Community (or your preferred name)
- Redirect URI / Callback URL:
https://[your-community-domain]/entry/oauth2 - Application Type: Web application (confidential client)
What we need from you:
Once registered, please provide:
- Client ID (Application ID)
- Client Secret
- Authorize URL (Authorization Endpoint)
- Token URL (Token Endpoint)
- Profile URL (UserInfo Endpoint)
Or, if you use OpenID Connect:
- OIDC Discovery URL (
.well-known/openid-configuration) - Client ID
- Client Secret
Required Scopes: Please ensure the application has access to scopes that include:
openid (if using OIDC)emailprofile
User Attributes we expect:
email — User's email addressname — User's display namesub or unique identifier — A persistent ID for the user
Optional Attributes (if applicable):
picture — URL to user's profile photogroups or roles — For role-based access
Let us know the exact attribute names your system returns so we can configure our attribute mapping.
Glossary
- OAuth2 (Open Authorization 2.0): An authorization framework that allows applications to obtain limited access to user accounts on a third-party service.
- OpenID Connect (OIDC): An authentication layer built on top of OAuth2 that provides standardized user identity information.
- Client ID: A public identifier for your application, assigned by the identity provider when you register the application.
- Client Secret: A confidential key known only to your application and the identity provider, used to authenticate your application.
- Authorize URL (Authorization Endpoint): The URL where users are redirected to authenticate with the identity provider.
- Token URL (Token Endpoint): The URL where your application exchanges an authorization code for an access token.
- Profile URL (UserInfo Endpoint): The URL where your application retrieves user profile information using the access token.
- Redirect URI (Callback URL): The URL where the identity provider sends users after they authenticate. Must match exactly what's registered.
- Discovery URL (Well-Known Endpoint): An OIDC endpoint that provides configuration information including all the necessary URLs for integration.
- Scopes: Permissions that define what user information your application can access (e.g., email, profile).
- Just-In-Time (JIT) Provisioning: Automatically creating a user account in Vanilla the first time they sign in via SSO.
Need help?
If you encounter issues not covered here, contact Vanilla support with:
- Your community URL
- The SSO method you're configuring (OAuth2)
- A description of what happens when you try to sign in
- Any error messages you see (screenshots are helpful)