What is the difference between 2-legged and 3-legged authentication?
2-legged authentication is handled server to server, and credentials never make it to the client side. This works great for websites or web-based applications. If you’ve ever implemented a web-based oauth flow, you are probably familiar with 2-legged authentication.
In order for your typical 2-legged authentication to work on a mobile device, credentials would have to be hard coded into the app. You obviously know this is not a good idea, and that is why 3-legged authentication was developed.
3-legged authentication assigns a unique token to a user that can be used for authentication so that credentials don’t have to be hard coded into an app.
Do I need 3-legged authentication?
In most cases, 3-legged authentication is not needed. 3-legged authentication is not really necessary for a mobile app, it is just one solution available for user authentication on a mobile device.
Instead of using 3-legged authentication, which can be cumbersome, we recommend you use a proxy server to interface with Context.IO and handle authentication. This way, you don’t have to set-up 3-legged authentication on your end.
This approach can streamline things, especially if you’re going to have both a web-based app and a mobile app. This is also the only way to get webhooks to work for a mobile app. We highly recommend mobile developers stay on 2-legged authentication and just use a proxy server to make calls to Context.IO, and then have their mobile app make requests to the proxy server for data.
What happens after I enable 3-legged authentication on my developer account?
There are several things that will stop working for developers using 3-legged authentication:
Certain parts of the console will no longer work for 3-legged developer accounts. The API explorer will no longer work, and you will not be able to create accounts through the console. We recommend creating a separate test account that is 2-legged if you would like to use the explorer for testing purposes only.
The oauth_providers endpoint will no longer work. If you need to add OAuth providers, you can do so by going to the console and clicking on OAuth access to IMAP to add a new OAuth provider.
All users will need to re-authenticate. Any users already under your dev account will need to be re-authenticated using 3-legged authentication.
So can I no longer use the console after enabling 3-legged authentication on my developer account?
There are some elements of the developer console that will not work for developers with 3-legged authentication enabled. Here is a breakdown of that will continue to work, and what will no longer work for 3-legged developers:
Works for 3-legged devs:
- Checking account status
- Webhooks logs
- Account settings
Will not work for 3-legged devs:
- API explorer
- Oauth providers endpoint
- Adding accounts via the console
The biggest thing is that the API explorer will no longer work for 3-legged devs. We recommend you create a separate 2-legged developer test account if you need to make test calls against the API using the API explorer in our developer console.
How do I turn 3-legged authentication on for my developer account?
In order to enable 3-legged authentication on your developer account, you have to contact us at firstname.lastname@example.org.
Since enabling 3-legged authentication has many implications that we want developers to be aware of before we turn their account into a 3-legged developer account, we did not provide a way for developers to “turn on” this functionality on their own. You have to contact email@example.com to get 3-legged authentication enabled for your account.