Module egg_mode::auth[−][src]

Expand description

Types and methods used to authenticate calls to Twitter.

Authenticating Requests With Twitter

egg-mode uses a Token type to represent successfully authenticating with Twitter. The process of obtaining a Token is somewhat complicated, and there are a few distinct routes you can take to get one. Which route you take depends on whether you want to only access public data versus wanting to act on behalf of a specific user, and whether you can open a web browser and/or redirect web requests to and from Twitter. Twitter’s Authentication Overview has the complete information.

Regardless of which route you take, you need to register with Twitter’s Developer site and set up an app to get a set of keys that represent your code interacting with the Twitter service. These are called the “consumer key” and “consumer secret”, and you can store them in a KeyPair to start the authentication process with egg-mode. At an HTTP request level, these keys are sent with every API call regardless of how you choose to authenticate. (There are other keys given when you register an app, but those will be mentioned below when talking about Access tokens.)

There are two kinds of Tokens used within egg-mode, representing the two major ways to interact with the Twitter API: Bearer tokens, for accessing public information on Twitter from the point of view of your app itself, and Access tokens, for performing actions or requesting data on behalf of a specific user.

Bearer Tokens

The simplest kind of Token you can get is called a “Bearer token”. Bearer tokens are for when you want to perform requests on behalf of your app itself, instead of a specific user. Bearer tokens are the API equivalent of viewing Twitter from a logged-out session. Anything that’s already public can be viewed, but things like protected users or the home timeline can’t be accessed with bearer tokens. On the other hand, because you don’t need to authenticate a user, obtaining a bearer token is relatively simple.

If a Bearer token will work for your purposes, use the following steps to get a Token:

  1. With the consumer key and secret from Twitter, ask Twitter for the current Bearer token for your application.

And… that’s it! This Bearer token can be cached and saved for future use. It will not expire until you ask Twitter to invalidate the token for you. Otherwise, this token can be used the same way as access tokens below, but with the restrictions mentioned earlier.

Example (Bearer Token)

let con_token = egg_mode::KeyPair::new("consumer key", "consumer secret");
let token = egg_mode::auth::bearer_token(&con_token).await.unwrap();

// token can be given to *most* egg_mode methods that ask for a token
// for restrictions, see docs for bearer_token

Access Tokens

Access tokens are for when you want to perform your requests on behalf of a specific user. This could be for something like posting to their account, sending and receiving direct messages for them, viewing protected accounts they follow, and other actions that only make sense from the perspective from a specific user. Because of the two-fold nature of making sure your requests are signed from your specific app and from that specific user, the authentication process for access tokens is relatively complicated.

The process to get an access token for a specific user (with this library) has three basic steps:

  1. Log your request with Twitter by getting a request token.
  2. Direct the user to grant permission to your application by sending them to an authenticate or authorize URL, depending on the nature of your app.
  3. Convert the verifier given by the permission request into an access token.

Before you get too deep into the authentication process, it helps to know a couple things about the app you’re writing:

  • Is your app in an environment where directing users to and from a web page is easy? (e.g. a website, or a mobile app)
  • Are you using Twitter authentication as a substitute for user accounts in your own application, instead of wanting to interact with their Twitter account?

Depending on your answer to the first question, you may need to use “PIN-Based Authorization”, where the user completes the authentication/authorization process in a separate window and receives a numeric PIN in response that your app can use to complete the authentication process. The alternative to that is the standard OAuth flow, where a web browser is directed to Twitter to complete the login and authorization, then redirected back to your app to receive the access token proper. The way to signal one method or another is by the callback parameter to the access token request.

The second question informs where you send the user to authorize your app. Using the “Sign In With Twitter” flow, your app could be able to transparently request another access token without the user needing to accept the connection every time. This is ideal for websites where a “Sign In With Twitter” button could replace a regular login button, using a user’s Twitter account in place for regular username/password credentials. To be able to use the “Sign In With Twitter” flow, you must first enable it for your app on Twitter’s Application Manager. Then, for Step 2 of the authentication process, send the user to an authenticate URL. If you don’t need or want to use the “Sign In With Twitter” process, send the user to an authorize URL instead.

The primary difference between the different URLs for Step 2 is that an authenticate URL allows the above behavior, whereas an authorize URL does not require the extra setting in the app manager and always requires the user to re-authorize the app every time they’re sent through the authentication process. Since access tokens can be cached and reused indefinitely until the app’s access is revoked, you only really need to send the user through the authentication process once.

The end result of Step 2 is that your app receives a “verifier” to vouch for the user’s acceptance of your app. With PIN-Based Authorization, the user receives a PIN from Twitter that acts as the verifier. With “Sign In With Twitter” and its counterpart, “3-Legged Authorization”, the verifier is given as a query parameter to the callback URL given back in Step 1. With this verifier and the original request token, you can combine them with your app’s consumer token to get the access token that opens up the rest of the Twitter API.

Example (Access Token)

For “PIN-Based Authorization”:

let con_token = egg_mode::KeyPair::new("consumer key", "consumer secret");
// "oob" is needed for PIN-based auth; see docs for `request_token` for more info
let request_token = egg_mode::auth::request_token(&con_token, "oob").await.unwrap();
let auth_url = egg_mode::auth::authorize_url(&request_token);

// give auth_url to the user, they can sign in to Twitter and accept your app's permissions.
// they'll receive a PIN in return, they need to give this to your application

let verifier = "123456"; //read the PIN from the user here

// note this consumes con_token; if you want to sign in multiple accounts, clone it here
let (token, user_id, screen_name) =
    egg_mode::auth::access_token(con_token, &request_token, verifier).await.unwrap();

// token can be given to any egg_mode method that asks for a token
// user_id and screen_name refer to the user who signed in

WARNING: The consumer token and preset access token mentioned below are as privileged as passwords! If your consumer key pair leaks or is visible to the public, anyone can impersonate your app! If you use a fixed token for your app, it’s recommended to set them in separate files and use include_str!() (from the standard library), or save them in an environment file and use a library like dotenv to load them in, so you can safely exclude them from source control.

Shortcut: Pre-Generated Access Token

If you only want to sign in as yourself, there’s a shortcut you can use to get an Access token. When you sign up for an app and get your consumer token, a second key/secret pair are given to you. This “access token” and “access token secret” act as authorization to access your own account with your own code, and can be used to directly construct an egg-mode Token:

let con_token = egg_mode::KeyPair::new("consumer key", "consumer secret");
let access_token = egg_mode::KeyPair::new("access token key", "access token secret");
let token = egg_mode::Token::Access {
    consumer: con_token,
    access: access_token,
};

// token can be given to any egg_mode method that asks for a token

For more information on the individual steps of the authentication process, see the documentation for the functions in this module.

Structs

KeyPair

A key/secret pair representing the app that is sending a request or an authorization from a user.

Enums

Token

A token that can be used to sign requests to Twitter.

Functions

access_token

With the given OAuth tokens and verifier, ask Twitter for an access KeyPair that can be used to sign further requests to the Twitter API.

authenticate_url

With the given request KeyPair, return a URL to redirect a user to so they can accept or reject an authorization request.

authorize_url

With the given request KeyPair, return a URL that a user can access to accept or reject an authorization request.

bearer_token

With the given consumer KeyPair, request the current Bearer token to perform Application-only authentication.

invalidate_bearer

Invalidate the given Bearer token using the given consumer KeyPair. Upon success, the future returned by this function yields the Token that was just invalidated.

request_token

With the given consumer KeyPair, ask Twitter for a request KeyPair that can be used to request access to the user’s account.

verify_tokens

If the given tokens are valid, return the user information for the authenticated user.