This article offers some advice with troubleshooting OAuth 2 SSO connections. 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 the standard OAuth 2 addon, but much of the advice here also applies to custom OAuth addons too.
This article is intended for a more technical audience that may have implemented an OAuth 2.0 server and understands the basics of the HTTP protocol such as headers, cookies, requests, responses, etc.
The Basic OAuth 2.0 Flow
If you use the default setup, you shouldn't run in to any problems, but sometimes 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 are still implementing a browser-based flow and all the requests that need to be handled in the same way as a browser. To help you with this, here is an overview of the three legs of the OAuth 2 flow.
Leg 1: Vanilla redirects to your authenticate URL
OAuth kicks off by redirecting to your authenticate URL that you configured in your dashboard. Here are a few things to make sure you remember if you are 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 are 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 back to Vanilla
Once the user has successfully signed in to your server you'll redirect back to Vanilla. When you get this far things are more straightforward. Just remember the following:
- Remember the state parameter. There is a
state query string parameter that is passed along with the authenticate redirect in the first leg of the OAuth flow. For more information on the state parameter requirement, check out the 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 chances are you 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 happening in the browser. Most errors that happen are surfaced in this leg even though they are 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 forum to find it. For more information on how to map your response to our system please see: Mapping User Profile Values.
The next section lists common error messages and what they mean.
Common Error Messages
If you have Event Logging enabled (contact your Customer Success Manager if you do not), you can inspect logged events such as errors and responses that occur during the SSO process. Click on Event Log in under Technical in the left hand menu of the Dashboard 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
/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 is prompting you for Email, Username and Password as well.
- The name of the UniqueID is not correctly mapped in your OAuth2 Addon in the Dashboard.
- Your server either did not send a unique ID (ssoID, or often the userID for the user on your system) with the connection request.
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 then 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 couple of common reasons why this happens:
- You aren't sending the same state token that Vanilla sent you, but rather some hard-coded value. Make sure you send the exact same 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 forum 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 forum tries to make an API call to request the user's profile information, except your authentication server sent back a message.
Frequently Asked Questions
Why am I prompted to log into 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 if you are 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 are already logged in.
How do I link from my application to login users in seamlessly to my forum?
The URL that your users should fall onto that will automatically initiate a login if the user does not have a session on the forum should be
https://[your-forum-domain]/enter/oauth2/oauth2-redirect if you only have one OAuth2 client configured. If you have multiple it will need to be
Why am I asked for my User Name or Email when connecting over SSO?
This means you are 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 on your Vanilla forum and you will be prompted to add them if they are not part of the SSO profile response the first time you connect. If you are passing these in the profile and still getting prompted, check that they are mapped correctly.
This tells us 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 on the forum. Perhaps you have registered on the forum without SSO and now you are connecting with SSO; if this is the case, put in the forum password: the one you created when you created the account on the forum. If you are importing users as part of the migration your users will get this prompt but will have no way of knowing their password (since passwords can't be migrated). In this case, as long as you are sure that the person with the email address on your authentication provider is the same person with that email address on the forum, you can ask us to set your forum to "AutoConnect" which means they will automatically be linked to this forum account without having to put in a password. For more, please see this section on Auto-Connect.
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.