Creating an OAuth Signature

Creating an OAuth Signature

OAuth is complicated, so we’ve created this guide to help you out. We’ve tried to simplify it, but if you get stuck, there are a lot of other good resources out there on the internet. A great place to start is the Getting Started guide on the OAuth website.

Creating an OAuth Signature

You’ll need to sign every call you make to the Vimeo API. The point of signing calls is so that we can verify that each request actually comes from your application. There are four main parts when signing a call:

  • The Base String

    This is the HTTP method, plus the base URL, plus all of your request parameters.

  • The Consumer Key

    This is a public string that is unique to your application.

  • The Consumer Secret

    This is a secret that you’ll pass to a cryptographic function in order to get your signature.

  • The Signature

    This is a mix of the above information, passed through a cryptographic function. It allows us to make sure that your application is actually the source of the API call.

Encoding

You’ll need to percent encode all of your parameters when creating your signature. These “reserved” characters must be converted into their hexadecimal values and preceded by a % character. The rest of the characters are “unreserved” and must not be encoded.

The reserved characters are:

!   *   '   (   )   ;   :   @   &   =   +   $   ,   /   ?   %   #   [   ]

These are the percent-encoded values of the above characters:

%21 %2A %27 %28 %29 %3B %3A %40 %26 %3D %2B %24 %2C %2F %3F %25 %23 %5B %5D

Unreserved characters include upper- and lower-case letters A through Z, numbers 0 through 0, and the dash, underscore, period, and tilde.

Be careful with URL encoding functions built into languages, they may not encode all of the reserved characters, or may encode unreserved characters.

OAuth Parameters

These are the OAuth parameters that must be included in your base string. You’ll also need to include any API parameters that you pass.

  • oauth_consumer_key

    Your application’s API key

  • oauth_nonce

    A randomly-generated string that is unique to each API call. This, along with the timestamp, is used to prevent replay attacks.

  • oauth_signature_method

    The cryptographic method used to sign the call. Vimeo only supports HMAC-SHA1.

  • oauth_timestamp

    The number of seconds that have elapsed since midnight, January 1, 1970, also known as UNIX time. Make sure this timestamp is within 10 minutes of the actual time, or the request will fail.

  • oauth_version

    You don’t need to include this, but if you do, it must be 1.0. It’s a good idea to include it anyway, because the OAuth spec may change in the future.

Creating the Base String

The base string includes three elements, separated by ampersands:

  • HTTP Method

    Will either be GET or POST, depending on the method used to make the call.

  • URL

    This is the base URL for the API call, percent-encoded. Include the port if it is other than 80 for HTTP or 443 for HTTPS.

  • HTTP Request Parameter String

    Concatenated list of all parameters sent, including OAuth parameters and API parameters. It should be in alphabetical order and concatenated together with ampersand separators. You should percent-encode your parameters before concatenating them, and then percent-encode the entire string.

After concatenating the three parts of the base string, you’ll have something like this (but without line breaks):

GET&
http%3A%2F%2Fvimeo.com%2Fapi%2Frest%2Fv2%2F&
method%3Dvimeo.people.getInfo
%26oauth_consumer_key%3DYourConsumerKey
%26oauth_nonce%3Dabcdefghijk
%26oauth_signature_method%3DHMAC-SHA1
%26oauth_timestamp%3D1234567890
%26oauth_version%3D1.0
%26user_id%3Dbrad

Creating the Key

The next step is to create the key that we’ll pass into the cryptographic function to generate our signature.

Most OAuth requests will include both your Consumer Secret and a Token Secret. When you have both, the key will look like this:

YourConsumerSecret&TokenSecret

If you don’t have a token yet, the key will look like this:

YourConsumerSecret&

Make sure you include the ampersand at the end!

Generate the signature

Now we’ll take both strings that we made, the base string and the key, and pass it into our hash function to get our signature. In PHP, it looks like this:

hash_hmac('SHA1', base_string, key, true)

The function will return a 20-character ASCII string. Because many of the characters in the string can’t be sent in a URL, we need to get a base-64 encoded version of our string. In PHP we can use the base64_encode() function to do this. The final step in preparing the signature is to make sure that it is percent-encoded.

Making an OAuth Request

There are three ways to pass oauth parameters to the API: through the OAuth Authorization header, POST body, or GET variables. The easiest way to pass OAuth parameters is as part of the URL, but you can use any of the three methods. See the Parameters section of the OAuth spec for more information.

Authenticating a User

Note: This process is designed for web applications, but can also be used by desktop applications.

You may hear this process called “3-Legged OAuth” elsewhere. Here’s how it goes:

  1. Your application sends a request with your consumer key, and signed with your consumer secret, for a something called a request token. If we verify your application correctly, we’ll send you back a request token and a token secret.
  2. You’ll then create a link for the user to click on with the request token.
  3. When the user gets to Vimeo, they’ll be prompted to allow your application access to their account. If they click yes, we’ll send them back to your application, along with a verifier.
  4. You’ll then use the request token, verifier, and token secret to make another call to us to get an access token. The access token is what you’ll use to access the user’s information on Vimeo.

Let’s get started!

Register an application

To use the Advanced API, you’ll need to register your application with Vimeo. When you register, you’ll receive a Consumer Key and Consumer Secret, which you’ll need to sign your API requests. You can register a new application, if you haven’t done so already.

Remember, do not share your secret with anyone!

Get an Unauthorized Request Token

The first part of authorization is to get a Request Token. This token will be used to obtain an Access Token once the user authorizes your application. It’s called “unauthorized” because the user hasn’t given their permission yet. You’ll only have to include the OAuth parameters for this call, so your base string should look like this:

GET&http%3A%2F%2Fvimeo.com%2Foauth%2Frequest_token&
oauth_callback%3Doob
%26oauth_consumer_key%3DYourConsumerKey
%26oauth_nonce%3Dabcdefghijk
%26oauth_signature_method%3DHMAC-SHA1
%26oauth_timestamp%3D1234567890
%26oauth_version%3D1.0

If you want to use the callback specified in your application settings, set oauth_callback to “oob”.

Then sign your request (this request doesn’t include a token, so your signature key will be YourConsumerSecret&) and call the following URL:

http://vimeo.com/oauth/request_token

Passing this as the Authorization header:

Authorization: OAuth realm="",
oauth_callback="oob",
oauth_consumer_key="YourConsumerKey",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1234567890",
oauth_nonce="abcdefghijk",
oauth_version="1.0",
oauth_signature="YourSignature"

The result will be something like this:

oauth_token=YourToken&oauth_token_secret=YourTokenSecret&oauth_callback_confirmed=true

Make sure to store both of these values, you’ll need the secret for step 4.

Forward the user to the Authorization URL

Next, you’ll need to send the user to the authorization url to log in to Vimeo and approve access for your application. You’ll need to include two parameters: the oauth_token you got from the last step and the permission level. Valid permission levels are read, write, delete.

http://vimeo.com/oauth/authorize?oauth_token=YourToken&permission=read

There’s no need to sign this call because each request token is specifically associated with one application.

When the user signs in successfully, we’ll redirect back to your application’s callback URL, along with the oauth_token and an oauth_verifier.

http://yourserver.com/your_callback?oauth_token=YourAuthorizedToken&oauth_verifier=YourVerifier

If your application does not have a callback, the verifier will be displayed to the user and they’ll be instructed to return to your application and enter the verifier.

Exchange Request Token for an Access Token

When your callback receives the authorized request token, you’re ready to exchange the request token for an access token that will let you act on behalf of the user. This call needs to be signed, so your signature base should look something like this:

GET&http%3A%2F%2Fvimeo.com%2Foauth%2Faccess_token&
oauth_consumer_key%3DYourConsumerKey
%26oauth_nonce%3Dabcdefghijk
%26oauth_signature_method%3DHMAC-SHA1
%26oauth_timestamp%3D1234567890
%26oauth_token%3DYourAuthorizedToken
%26oauth_verifier%3DYourVerifier
%26oauth_version%3D1.0

Then sign your request and call the following URL:

http://vimeo.com/oauth/access_token

Passing this as the Authorization header:

Authorization: OAuth realm="",
oauth_consumer_key="YourConsumerKey",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1234567890",
oauth_nonce="abcdefghijk",
oauth_token="YourAuthorizedToken",
oauth_verifier="YourVerifier", oauth_version="1.0",
oauth_signature="YourSignature"

You’ll get back something like this:

oauth_token=YourAuthorizedOauthToken&oauth_token_secret=YourAuthorizedTokenSecret

You should now store both of those values as you’ll need them to make calls to the API. The token and secret are valid until the user revokes access to your application, so make sure to store them in a safe place.

Leave a Reply

Leave a Reply