Authentication

Previous documentation

• Documentation for 0.9.10.x and 0.9.11.x
• Documentation for Tweetinvi before 0.9.9.x

Overview

Twitter allows developer's application to authenticate any Twitter user. The API gives access to two different mechanisms that we will name URL redirect authentication and PIN-based authentication.

• PIN-Based authentication is better suited for Desktop application
• URL redirect authentication is better suited for Web Application.

IMPORTANT : If you are using authentication on a website please read the Web Application Considerations!

PIN-Based Authentication

The PIN-based authentication process is quite simple.

1. Request Twitter to provide a unique URL that enables a user to authenticate and retrieve a captcha.
2. Ask the user to go to this URL.
3. Twitter will ask the user to authenticate and accept the permissions requested by your Twitter application.
4. If the user accepts, Twitter generates a PIN Code and gives it to the user.
5. With this code, Twitter can now issue a new OAuth Token available from a WebRequest.

Now let's see how Tweetinvi simplifies this process.

// Create a new set of credentials for the application.
var appCredentials = new TwitterCredentials("CONSUMER_KEY", "CONSUMER_SECRET");

// Init the authentication process and store the related `AuthenticationContext`.
var authenticationContext = AuthFlow.InitAuthentication(appCredentials);

// Go to the URL so that Twitter authenticates the user and gives him a PIN code.
Process.Start(authenticationContext.AuthorizationURL);

// Ask the user to enter the pin code given by Twitter
var pinCode = Console.ReadLine();

// With this pin code it is now possible to get the credentials back from Twitter
var userCredentials = AuthFlow.CreateCredentialsFromVerifierCode(pinCode, authenticationContext);

// Use the user credentials in your application
Auth.SetCredentials(userCredentials);

URL Redirect Authentication

The Redirect URL authentication process is also quite a straightforward process.

1. Request Twitter to provide a unique URL that enables a user to authenticate and redirect to a specific URL.
2. Ask the user to go to this URL.
3. Twitter will ask the user to authenticate and accept the permissions requested by your Twitter application.
4. If the user accepts, Twitter will redirect the user to the specified URL and provide some credentials information as URL parameters.
5. With this information, Twitter can now issue a new OAuth Token available from an HttpRequest.

The following example is for ASP.NET developers using MVC. I will separate the process in 2 routes:

• User wants to authenticate with Twitter, he is redirected to twitter.com to authenticate.
• User has successfully authenticated and is redirected back to our website.

private IAuthenticationContext _authenticationContext;

// Step 1 : Redirect user to go on Twitter.com to authenticate
public ActionResult TwitterAuth()
{
    var appCreds = new ConsumerCredentials("CONSUMER_KEY", "CONSUMER_SECRET");

    // Specify the url you want the user to be redirected to
    var redirectURL = "http://" + Request.Url.Authority + "/Home/ValidateTwitterAuth";
    _authenticationContext = AuthFlow.InitAuthentication(appCreds, redirectURL);

    return new RedirectResult(authenticationContext.AuthorizationURL);
}

public ActionResult ValidateTwitterAuth()
{
    // Get some information back from the URL
    var verifierCode = Request.Params.Get("oauth_verifier");

    // Create the user credentials
    var userCreds = AuthFlow.CreateCredentialsFromVerifierCode(verifierCode, _authenticationContext);

    // Do whatever you want with the user now!
    ViewBag.User = Tweetinvi.User.GetAuthenticatedUser(userCreds);
    return View();
}

After being authenticated, Twitter will redirect the user to a URL with the following format :

www.redirect.com?oauth_token={token}&oauth_verifier={verifier}&authorization_id={auth_id}.

As you can see Twitter will provide 3 parameters in the query, oauth_token, oauth_verifier and authorization_id. Please do not use any of these parameters in your callbackURL.

NOTE:

If you cannot store the IAuthentication context you will need to store the AuthenticationContext.Token. It contains your credentials as well as keys required for the process.

var token = new AuthenticationToken()
{
    AuthorizationKey = "<from_db>",
    AuthorizationSecret = "<from_db>",
    ConsumerCredentials = creds
};

// And then instead of passing the AuthenticationContext, just pass the AuthenticationToken
var verifierCode = Request.Params.Get("oauth_verifier");
var userCreds = AuthFlow.CreateCredentialsFromVerifierCode(verifierCode, token );

Web Application Considerations

If you write a web application, it is important that you understand how the applicationCredentials are used and updated by Tweetinvi.

When calling GetAuthorizationURL, Tweetinvi makes a WebRequest to Twitter which returns various information and more importantly the following:

• The Authentication URL
• A key that Tweetinvi stores in the AuthorizationKey property
• A key that Tweetinvi stores in the AuthorizationSecret property

Behind the scene Tweetinvi stores this information within the applicationCredentials and a local credentials store. During the second part of the process Tweetinvi will use these two keys to generate the credentials.

As a result, after being redirected you need to ensure that these two information are preserved. When calling the method CreateCredentialsFromVerifierCode, you need to make sure that these two information are the same as they were after the call to InitAuthentication.

If the authorization key are not set in the credentials, Tweetinvi will attempt to use its cache. If the credentials associated with the authorization_id cannot be found Tweetinvi will throw an Exception.

Localhost issue

You can encounter issues if you attempt to use localhost as the redirect URL. If you encounter such issue please try using http://127.0.0.1/ instead.