In order to connect a mailbox to Context.IO, a user will need to authenticate an account. Context.IO supports connections made in any of the following two ways:
Connecting via OAuth is the best and most reliable way. In fact, some providers, such as Microsoft, require connections be made via OAuth. We currently support OAuth connections for Google and Microsoft accounts.
For non-OAuth accounts, we can connect via IMAP over a secure connection using SSL. You can learn more about both options below.
Connecting via OAuth
Google and Microsoft require users authenticate via OAuth. Context.IO supports OAuth for Google and Microsoft in two ways: by handling your own OAuth, or by using our connect tokens feature.
- Handling your own OAuth: A developer can authenticate via OAuth 2.0 by passing Context.IO their provider consumer key (an API key obtained from Google / Microsoft), as well as a provider refresh token, which is also obtained from the provider. If this option is chosen, the developer must handle their own token refresh.
- Using our connect tokens feature: The Context.IO connect tokens feature is an abstraction on top of OAuth. In other words, it is a feature Context.IO developed to facilitate the OAuth process on behalf of a developer. If a developer chooses this option, all they have to do is create a connect token in order to “kick off” the OAuth process, and we handle the rest (i.e. redirecting the user to authenticate to the correct provider, requesting the right scope). Another benefit to using our connect tokens feature is that we handle token refresh with the providers, so developers don’t have to worry about refreshing OAuth tokens.
Specific types of OAuth accounts supported:
- Google: Gmail and Google Apps
- Microsoft: Outlook.com, Hotmail, MSN
Please note: Outlook over Office365 is not supported via OAuth, as that is an Exchange server, and we do not support native Exchange. To connect to an Outlook Office365 account, you must connect via IMAP (see below).
For providers that do not support OAuth (i.e. not Gmail / Microsoft), we connect securely via IMAP using SSL. Usernames and passwords are stored securely and are encrypted. A developer can use either of the following options to authenticate non-OAuth accounts:
- Passing us credentials at account creation: If this method is chosen, the developer would need to know details such as IMAP server, port, SSL connection, and get the username and password from the end-user. A POST request to the add account / user endpoint would then add the user to Context.IO.
- Using our connect tokens feature: Context.IO connect tokens also facilitate the creation of non-OAuth accounts by “auto-discovering” IMAP connection settings. If a developer chooses this option, Context.IO will attempt to populate the data needed to form a secure IMAP connection based on our auto-discovery data, and all an end-user would have to do is provide their username and password. We also provide a GUI to gather credentials from the end-user, which developers can add their own branding to.
Choosing the right authentication method
- For providers that support OAuth (Google or Microsoft):
- If you all wish to do is simply connect to an account, our Connect Tokens feature is the best and fastest way to accomplish this. If you choose this option, we strongly urge you to add your own provider keys so that when a user checks to see which apps have access to their account, they will see your app and not Context.IO (in fact, Microsoft requires this).
- If you need to do more complicated things with OAuth, such as use a refresh token to authenticate on more than one application (i.e. more than just Context.IO), you should handle your own OAuth. Please note: this is typically an edge case.
- For providers that do not support OAuth:
- Once again, our connect tokens feature is a great way to handle connections for providers that do not support OAuth. This is because the Connect Tokens feature can auto-discover the IMAP settings necessary to make a connection, and all the user would need to provide is their username and password.
- If you do not need to auto-discover IMAP settings (i.e. your application will only connect to the same IMAP providers, and you already know these settings), you could very well simply pass the IMAP server, port, SSL settings, username and password manually to the API via POST request to the add account / user endpoint.
For any questions regarding safety and security surrounding authentication, take a look at our Security FAQ here.