Authenticating the User with XOAUTH

What is XOAUTH?

XOAUTH is an experimental authentication method utilizing the OAuth protocol to provide access to SMTP and IMAP based accounts, it is currently used by Google's Gmail and Yahoo!
Details on OAuth can be found on the OAUTH Community Site.
Equinox does include classes which will simplify the usage of this authentication mechanism significantly.
In this sample we will show you how to use Equinox to connect to Gmail using a 3-legged XOAUTH authentication.
It is worth mentioning that this method will, in all likelihood, not work for providers other than Gmail without alteration;
Although the steps to take will be identical to other providers, several parameters used in the following sample code are Google specific and won't work with other providers.
To implement this mechanic for other providers it is essential to adapt the code to their requirements.

How does OAuth work?

To keep things simple OAuth enables a website and/or application to access his's or her's secured data without the need to give away the password.
Usually when we create an account inside our favorite email client, messenger or facebook application we have to type in our credentials to allow the application access to our data.
Once done the application knows our credentials, which is undesirable, since we don't know to whom they are going to sell them and at what price. OAuth addresses this issue.
To authenticate with Gmail using the 3-legged authentication we need to take 4 steps.
  • [OAuth] Request an unauthorized request token
  • [OAuth] Authorize the request token
  • [OAuth] Exchange the authorized request token for an access token
  • [XOAuth] Authenticate to the server using the access token

Implementing the Authorization Procedure using the 3L approach

Before we can access the necessary classes we need to add the following namespace.

using Crystalbyte.Equinox.Security.Authentication;
Since XOAUTH is a mechanic that cannot be handled by the client automatically the client will trigger the ManualSaslAuthenticationRequired event.
Once inside the handler the following code will complete the Gmail authentication procedure.

if (!client.Capability.Items.Contains("AUTH=XOAUTH")) {
	return;
}

// we need only the email address, no password is necessary
var email = credential.UserName;

// request the request token
var token = new OAuthRequest()
	.WithAnonymousConsumer()
	.WithEndpoint("https://www.google.com/accounts/OAuthGetRequestToken")
	.WithParameter("scope", "https://mail.google.com/") // Gmail specific
	.WithParameter(OAuthParameters.OAuthCallback, "oob")
	.WithParameter("xoauth_displayname", "Crystalbyte Equinox") // Gmail specific
	.WithSignatureMethod(OAuthSignatureMethods.HmacSha1)
	.Sign()
	.RequestToken();

// authorize the request token
var authUrl = new OAuthRequest()
	.WithEndpoint("https://www.google.com/accounts/OAuthAuthorizeToken")
	.WithToken(token)
	.GetAuthorizationUri();

// we need to start the browser using the requested url
Process.Start(authUrl.AbsoluteUri);

var verificationKey = // .. the key will be displayed on the Google Authentication Page, if the user confirms the access

// exchange authorized request token for access token
var accessToken = new OAuthRequest()
	.WithAnonymousConsumer()
	.WithEndpoint("https://www.google.com/accounts/OAuthGetAccessToken")
	.WithParameter(OAuthParameters.OAuthVerifier, verificationCode)
	.WithSignatureMethod(OAuthSignatureMethods.HmacSha1)
	.WithToken(token)
	.Sign()
	.RequestToken();

// create XOAUTH authentication key from access token
var xOUrl = string.Format("https://mail.google.com/mail/b/{0}/imap/", email);
var key = new OAuthRequest()
	.WithAnonymousConsumer()
	.WithEndpoint(xOUrl)
	.WithSignatureMethod(OAuthSignatureMethods.HmacSha1)
	.WithToken(accessToken)
	.Sign()
	.CreateXOAuthKey();

client.AuthenticateXOAuth(key);

Last edited Jul 2, 2011 at 6:33 PM by Krasshirsch, version 11

Comments

No comments yet.