This article provides troubleshooting information for OAuth 2.0-based SSO connections.
- Higher Logic Vanilla (Vanilla) provides a standard OAuth 2 addon for most OAuth 2.0-based SSO, but also offers customizations as a service. Most of this article assumes the standard OAuth 2 addon, but much of the advice also applies to custom OAuth addons.
⚠️ IMPORTANT: This article is intended for a more technical audience who may have implemented an OAuth 2.0 server and who understands the basics of the HTTP protocol such as headers, cookies, requests, responses, etc.
The basic OAuth 2.0 flow
Vanilla does not support implicit grant flow, which is often used for single-page applications that leverage JavaScript. Vanilla's OAuth 2 is primarily an authorization code grant or browser-based flow, meaning it's meant to take place in your web browser.
📝 NOTE: OAuth 2.0 offers several workflows within the browser, but Vanilla offers the server flow, often referred to as the three-legged flow. This is the flow you should be familiar with if you want to integrate Vanilla with your OAuth 2.0 server.
You should be fine if you use the default setup, but you may want to implement SSO in a non-standard way, like within a web view of a mobile app. When doing so, it's important to remember that you're still implementing a browser-based flow, and all the requests have to be handled in the same way as a browser. To help with this, below are the three legs of the OAuth 2.0 flow.
Leg 1: Vanilla redirects to your authenticate URL
OAuth kicks off by redirecting to the authenticate URL that is configured in your Dashboard. Keep the following in mind if you're implementing your own OAuth server.
- Do not skip this step. Some people may just link to their own authenticate URL or just link back to their community without letting Vanilla kick off the authentication process. Doing so will lead to errors.
- Remember the cookies. The redirect step also sets cookies. If you're calling the redirect endpoint in a non-standard way, you must store the cookies and they must be set on future requests.
- Redirects are unique. Each redirect generates a different state token, so you can't just run a sample redirect and then hard-code the redirect URL into your app.
Leg 2: Your authenticate endpoint redirects to Vanilla
After the user has successfully signed in to your server, you'll redirect back to Vanilla. At this point, things are more straightforward. Just remember the following:
- Remember the state parameter. A state query-string parameter is passed along with the authenticate redirect in the first leg of the OAuth flow. For more information on the state parameter requirement, see OAuth specification.
- Remember the authentication code. Your server will issue an authentication code in the code query-string parameter. If your redirect doesn't include this parameter, then you probably aren't implementing a three-legged flow that Vanilla supports.
Leg 3: Vanilla requests an access token and user profile
This final leg of the authentication happens on the server, so you won't see it in the browser. Most errors that occur are surfaced in this leg, even though they're caused in the first two legs.
Misconfiguring the OAuth2 addon in the Dashboard could be the source of some errors. If, when trying to log in, you encounter a form with an error message that says "UniqueID was not found," this means either your authentication provider did not send a UniqueID or you have not mapped your community to find it.
For information on how to map your response to our system, see Mapping User Profile Values.
Inspect the UserInfo payload
If you have Event Logging enabled (contact Vanilla Support if you don't), you can inspect logged events, such as errors and responses, that occur during the SSO process. In the Dashboard, navigate to Settings > Technical > Audit Log. In the Filters panel on the right, click the Action dropdown and choose Oauth 2 Debug to see all the OAuth 2.0 events.
To see what data is being passed in the payload of the User Profile, click on OAuth2 – OAuth2 getProfile API call and view the Raw Profile JSON object.
Perform a test SSO connection.
Below are some of the error messages you may see as standard user error messages on the /entry/connect/oauth2 page when your OAuth integration is misconfigured or your server does not behave in a standard way.
The next section lists common error messages and what they mean.
Common error messages
If you have Event Logging enabled (contact Vanilla Support if you don't), you can inspect logged events such as errors and responses that occur during the SSO process. In the Dashboard, navigate to Settings > Technical > Event Log and filter on "sso_logging" to see all the OAuth2 events.
Below are some of the error messages you may see when your OAuth integration is misconfigured or your server does not behave in a standard way.
"UniqueID is required"
This could be one of three things:
- Most likely, there is no connection data sent in the connection response. Your user has somehow been redirected to or landed on the
/entry/connect/oauth2 page outside of the OAuth2-SSO workflow. This page is always looking for a connection response, and when it doesn't find one, it reports the first error: UniqueID is required. This is most likely the case if it's prompting you for Email and Username and Password. - The name of the UniqueID is not correctly mapped in your OAuth2 addon in the Dashboard. To verify what SSO User Info payload is being sent, refer to Inspect the UserInfo payload above.
- Your server did not send a unique ID (ssoID or often the userID for the user on your system) with the connection request.
"Whoops!"
This is our generic error page. Any time the OAuth2 Entry endpoint ( /entry/oauth2 ) receives an error in the GET response from your OAuth server, we serve an error page with the value of the error code and "Whoops!" as the title. You should recognize these codes from your system.
Below are other error pages with messages that we generate with the title "Whoops!".
"The code parameter is either not set or empty"
This means that your server did not supply a code parameter during leg 2 of the authentication. The code is required, and you'll need to troubleshoot why you aren't sending this parameter.
"The OAuth server did not return a valid response"
This means that your server did not respond properly during leg 3 of the authentication. You should check your server logs to see if you have any errors during access token requests.
"The OAuth server did not return an access token"
This means that your server responded during leg 3 of the authentication, but it did not respond with an access token. Your server is required to either respond with an error or an access token, and if you get this error, your server responded with a non-compliant response.
"State token not found"
Your server responded with a valid access code in leg 2 but did not respond with the state token that Vanilla sent you in leg 1. You must respond with the same state token that Vanilla sent you and not throw it away.
"Invalid/expired state token"
The state token you supplied was invalid. There are a few common reasons why this happens:
- You aren't sending the same state token that Vanilla sent you, but rather a hard-coded value. Make sure you send the exact state parameter back to Vanilla.
- You aren't setting the cookies that Vanilla sets during leg 1 of the authentication.
HTTP error communicating code: [HTTP Status Code]
This error is the response from your authentication server when your community tries to make an API call to request the user's profile information.
- If the code is 404, check what URL you have entered in the OAuth2 addon in the Dashboard for Profile URL.
- Otherwise, the problem is on the end of the authentication server. One possible culprit could be that when we make the API call to to exchange, the Access Token for the users profile we are sending it as a GET parameter instead of a Bearer Token or vice-versa. Check which method your Authentication Provider requires. Either way is configurable in our Dashboard Settings.
Request server says: [message]
Like above, this error is the response from your authentication server when your community tries to make an API call to request the user's profile information, except your authentication server sent back a message.
FAQ
Why am I prompted to log in to my Authentication Server even though I am already logged in?
One of four options is passed to your Sign In page as the "prompt" directive. That tells your sign-in page how it should behave, depending on whether you're already logged in.
- Should it always present a log in screen?
- Should it never present a log in screen?
- Should it always prompt you to give consent to passing data from your application to vanilla?
This is configurable.
Login will always present a login screen, even if you're already logged in.
How do I link from my application to seamlessly log users in to my community?
The URL that your users should land on that will automatically initiate a login if the user does not have a session on the community:
- If you have only one OAuth 2.0 client configured, the URL is:
https://[your-community-domain]/entry/oauth2-redirect
- If you have multiple OAuth 2.0 clients configured, the URL is:
https://[your-forum-domain]/entry/oauth2-redirect?cient_id=[ClientID]
Why am I asked for my user name or email when connecting over SSO?
This means you're either not passing a Display Name or Email in your SSO profile or you do not have it correctly mapped. These two pieces of data are essential for creating a user in your Vanilla community, and you will be prompted to add them if they're not part of the SSO profile response the first time you connect.
If you're passing these in the profile and still getting prompted, check that they are mapped correctly.
This tells us that you are sending the email address of the user as email in the profile.
Why am I being asked for the password when I connect over SSO?
This is happening because a user with the same email address as the one being passed over in the SSO profile exists in the community. Perhaps you've registered on the community without SSO and now you're connecting with SSO; if this is the case, put in the community password, i.e., the one you created when you created the account.
If you're importing users as part of the migration, your users will get this prompt but will have no way of knowing their password (because passwords can't be migrated). In this case, as long as you're sure that the person with the email address on your authentication provider is the same person with that email address on the community, you can ask us to set your community to "AutoConnect," which means they'll automatically be linked to this community account without having to input a password. For more info, see Auto-Connect.
Summary
If you use Vanilla's OAuth 2 addon with a standard setup then you shouldn't encounter any problems. However, if you opt for a non-standard setup it's important that you understand the OAuth 2 flow which makes heavy use of redirects and uses most parts of the HTTP protocol. Make sure you understand the entire process when implementing a custom workflow.
Additional reading
