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
Vanilla does not support what is referred to as implicit grant flow, often used for single page applications leveraging Javascript. Vanilla's OAuth 2 is primarily an authorization code grant or browser-based flow. That means that it is meant to take place in your web browser. OAuth 2 offers several different workflows within the browser, but Vanilla offers the server flow, often referred to as the three legged flow. This is the flow you should familiarize yourself with if you want to integrate Vanilla with your OAuth server.
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
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.
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.
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.
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.
Further Reading