OAuth 1a

The OAuth 1a method is recommended for servers that are not behind https. Note that OAuth 1a access tokens do not expire.

OAuth 1a can be a complicated method due to the need to generate a signature for the request. If anything is off with the signature, the request will not be validated.

Step One – Obtain a Request Token

The first step is to obtain a request token that will be used when directing the user to the authorization page.

Make a POST to the request token endpoint /oauth/v1/request_token:

POST /oauth/v1/request_token
AUTHORIZATION:
OAuth oauth_callback=“https%3A%2F%2Fyour-callback-uri.com”,
oauth_consumer_key=“CONSUMER_KEY”,
oauth_nonce=“UNIQUE_STRING”,
oauth_signature=“GENERATED_REQUEST_SIGNATURE”,
oauth_signature_method=“HMAC-SHA1”,
oauth_timestamp=“1318467427”,
oauth_version=“1.0”

(note that the header has been wrapped for legibility)

Review “Generating the Authorization Header” on the specifics of generating the OAuth header.

The response will be a query string:

oauth_token=REQUEST_TOKEN&oauth_token_secret=REQUEST_TOKEN_SECRET&oauth_expires_in=3600

Parse the string and use the parameters in the next step as indicated.

These must be preserved in some kind of persistent storage as they will be used when obtaining the access token.

Note that the refresh token is only good for the number of seconds specified in oauth_expires_in.

Step Two – Authorization

Now redirect the user to the authorization endpoint oauth/v1/authorize with the request token as part of the URL’s query.

If the callback is something different than what is configured in Be1First, url encode it and include in the query as oauth_callback.

/oauth/v1/authorize?oauth_token=REQUEST_TOKEN&oauth_callback=https%3A%2F%2Fyour-callback-uri.com

The user will login and Be1First will redirect back to the either the consumer’s configured callback or to the oauth_callback included in the query.

The callback will include oauth_token and oauth_verifier in the URL’s query.

Compare the oauth_token in the query with that obtained in step two to ensure they are the same and prevent cross-site request forgery.

oauth_verifier will need to be part of the header generated in step three.

Step Three – Obtain an Access Token

Generate the Authorization header and make a POST to the access token endpoint /oauth/v1/access_token.

When generating the header, the oauth_token_secret returned in step two should be used as the TOKEN_SECRET in the composite key.

oauth_verifier from step two should be part of the Authorization header generated.

POST /oauth/v1/access_token
Authorization:

OAuth oauth_callback=“https%3A%2F%2Fyour-callback-uri.com”,
oauth_consumer_key=“CONSUMER_KEY”,
oauth_nonce=“UNIQUE_STRING”,
oauth_signature=“GENERATED_REQUEST_SIGNATURE”,
oauth_signature_method=“HMAC-SHA1”,
oauth_timestamp=“1318467427”,
oauth_verifier=“OAUTH_VERIFIER_FROM_STEP_TWO”
oauth_version=“1.0”

(note that the header has been wrapped for legibility)

The response should include a query string with the access token:

oauth_token=ACCESS_TOKEN&oauth_token_secret=ACCESS_TOKEN_SECRET

AltosMail’s OAuth 1a access tokens do not expire but the user can deauthorize them. If the access token is invalid, a `401` response will be returned.

The oauth_token can be included in the authorize header and the oauth_token_secret should be used as the TOKEN_SECRET in the composite key when signing API requests.