ZERO to HERO The LinkedIn
OAuth Dance

Using the LinkedIn API is
easy... If you’re lord of the dance.

The OAuth Dance

OAuth is an open authorization
standard for APIs that does away with logins and passwords to grant authorization to a third-party. Some familiarity with OAuth is assumed, going forward. http://oauth.net/core/1.0a

Will any old OAuth library
work with LinkedIn? LinkedIn uses OAuth 1.0a and requires HTTP Header-based Authorization. Some OAuth libraries don’t yet support OAuth 1.0a, or are built with lenient OAuth implementations in mind. LinkedIn’s OAuth is strict.Your library might not be up to snuff.

You might have to get
your hands dirty.

Quick Glossary That Won’t Be
So Quick Because This Stuff Actually Takes Time to Learn oauth_callback - This is either a URL or “oob” and denotes where to direct a user on your server following the “authorize” step. out of band - A form of OAuth where no URL callback is used and an oauth_verifier challenge is presented instead requestToken - a token issued to you as a result of asking for it. Re-used in the authorize step accessToken - a token issued to you at the end of the cycle. Represents a LinkedIn member and authorizes you to access resources on their behalf authorize - After getting a request token, you send the user to a signed authorize URL where they grant access to your application token secret - a string returned on the requestToken and accessToken steps, used in conjunction with your consumer secret when signing certain requests. consumer key - Your API key. consumer secret - Your API secret. Used in the signing of all requests. oauth_nonce - A random string, unique in every request. oauth_timestamp - Epoch time in seconds, synced within 5 minutes of LinkedIn’s clock oauth_token - Specified in many contexts, either the request token or access token. oauth_verifier - A returned to you when your oauth_callback is invoked, or hand-entered by a user in the out-of-band flow.

All OAuth-based requests are very
similar.You’re identifying a resource that you want to make a request to, you’re building a string that describes the request and your credentials for making it, and then you’re signing that string using a set of secrets. It’s like addressing an envelope where the address and stamp not only describe the destination but also the contents. The OAuth 1.0a Request Cycle

1) You ask for a
request token and specify your callback 2) You direct the user to our authorization screen 3) You either receive a callback at a URL you specified, or the member enters a PIN code (out-of-band authentication) 4) You ask for an access token 5) You make API calls! The OAuth 1.0a Request Cycle

Building a requestToken request requires
the following: HTTP Method, Request URI, oauth_callback, oauth_consumer_key, oauth_nonce, oauth_signature_method, oauth_timestamp, and oauth_version. Getting a Request Token

First build your string to
sign. We’ll use these values for this example. HTTP Method POST Request URI https://api.linkedin.com/uas/oauth/requestToken oauth_callback http://linkedin.realitytechnicians.com:3000/oauth_consumers/taylor_singletary/callback oauth_consumer_key dTgSkaRKZjEnS1vAUu6e7-aYC00UilBTwnXHpLH7NyL2e-klzBC1a4TKCnSgClWV oauth_nonce 24FZIeB9tNGlnV9p7nnP1yelQbTNFjU7R5qs8u0tk oauth_signature_method HMAC-SHA1 oauth_timestamp 1260811626 oauth_version 1.0 Getting a Request Token

First build your string to
sign. These parameters get sorted alphabetically, each value is URL escaped, and than concatenated into a single string. POST&https%3A%2F%2Fapi.linkedin.com%2Fuas%2Foauth %2FrequestToken&oauth_callback%3Dhttp%253A%252F %252Flinkedin.realitytechnicians.com %253A3000%252Foauth_consumers %252Ftaylor_singletary%252Fcallback %26oauth_consumer_key%3DdTgSkaRKZjEnS1vAUu6e7- aYC00UilBTwnXHpLH7NyL2e-klzBC1a4TKCnSgClWV %26oauth_nonce %3D24FZIeB9tNGlnV9p7nnP1yelQbTNFjU7R5qs8u0tk %26oauth_signature_method%3DHMAC- SHA1%26oauth_timestamp %3D1260811626%26oauth_version%3D1.0 Getting a Request Token

Create your Authorization HTTP Header
& Issue the Request Now we sign this string using our consumer secret and create an HTTP Authorization header,. The signature should be placed in the oauth_signature value. Authorization: OAuth oauth_nonce="24FZIeB9tNGlnV9p7nnP1yelQbTNFjU7R5qs 8u0tk", oauth_callback="http%3A%2F %2Flinkedin.realitytechnicians.com %3A3000%2Foauth_consumers%2Ftaylor_singletary %2Fcallback", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1260811626", oauth_consumer_key="dTgSkaRKZjEnS1vAUu6e7- aYC00UilBTwnXHpLH7NyL2e-klzBC1a4TKCnSgClWV", oauth_signature="Ws%2B%2FH%2FonYnsZXyZwyEhgL %2Bboq8s%3D", oauth_version="1.0" Getting a Request Token

Evaluate the requestToken response Now
we issue this request to the requestToken endpoint, and if all is successful, you’ll get something like the following URL encoded response: oauth_token=f7868c3a-7336-4662- a6d1-3219fb4650d1&oauth_token_secret=45e0ccd0-0c5 d-431e-831a-63f10552338a&oauth_callback_confirmed =true The oauth_token field is now your request token, and the oauth_token_secret will be used for signing your request for an access token. oauth_callback_confirmed just gives you confirmation that we recognized your oauth_callback parameter. You’ll want to “hold on” to the oauth_token and oauth_token_secret until you’ve completed the access token step. Getting a Request Token

Build your authorization URL Now
that we have a request token, we can build the URL to authorize the user. We’ll then redirect the user to this URL so they can grant your application access. An authorization URL is simply this end point: https://api.linkedin.com/uas/oauth/authorize with a query parameter tacked on called oauth_token. The value for this parameter is equal to the request token you received in the previous step. With this same example, you’d direct the user to this URL: https://api.linkedin.com/uas/oauth/authorize? oauth_token=f7868c3a-7336-4662-a6d1-3219fb4650d1 The user needs to land on this page within 5 minutes of your request token cycle. You should not pass an oauth_callback parameter to this page (you already did that in the request token step). Authorizing the member

Send the user to LinkedIn’s
Authorization Page The user will then be sent to our authorization page. When completed the user will either be sent back to your oauth_callback URL or presented with a series of digits they’ll be instructed to hand-enter into your application (if you are performing out-of-band authentication). Authorizing the member

OAuth Callback vs. Out of
Band After authorizing your application, the After authorizing your application, the user will be sent to the URL you specified member is presented with a PIN code. as the oauth_callback. Your callback will receive In your application, you an oauth_token and should now present a UI oauth_token_secret; these allowing the user to are the same as your hand-enter the PIN request tokens. code. You’ll also receive an After receiving the PIN oauth_verifier parameter, code, you’ll be using it which you will need to for the accessToken step attach as part of your as the oauth_verifier. accessToken request in the next step.

Exchanging a request token for
an access token.

Prepare your signing secret Regardless
of whether you used out-of-band authentication or not, you’ll now be equipped with a request token, an oauth_token_secret, and an oauth_verifier. You’re now going to exchange that request token for an access token, imbued with the permission of the LinkedIn member to act on their behalf. In LinkedIn’s strict OAuth implementation, a request for an access token must be signed using both your consumer secret and the oauth_token_secret you received as when retrieving your request token. Many existing OAuth libraries do not properly incorporate the oauth_token_secret in this step. Your signing key will be in the format of: url_escape(consumer_secret)&url_escape(oauth_token_secret) Getting an Access Token

Now build your string to
sign. We’ll use these values for this example. Your oauth_token is your requestToken. HTTP Method POST Request URI https://api.linkedin.com/uas/oauth/accessToken oauth_consumer_key dTgSkaRKZjEnS1vAUu6e7-aYC00UilBTwnXHpLH7NyL2e-klzBC1a4TKCnSgClWV oauth_nonce WqKwyyrjQLgpaeJIB6MWKKmDOIpxKBrz0lLabSO3UI oauth_signature_method HMAC-SHA1 oauth_timestamp 1260811635 oauth_token f7868c3a-7336-4662-a6d1-3219fb4650d1 oauth_verifier 75553 oauth_version 1.0 Getting an Access Token

Now build your string to
sign. These parameters get sorted alphabetically, each value is URL escaped, and than concatenated into a single string. POST&https%3A%2F%2Fapi.linkedin.com%2Fuas%2Foauth %2FaccessToken&oauth_consumer_key %3DdTgSkaRKZjEnS1vAUu6e7-aYC00UilBTwnXHpLH7NyL2e- klzBC1a4TKCnSgClWV%26oauth_nonce %3DWqKwyyrjQLgpaeJIB6MWKKmDOIpxKBrz0lLabSO3UI %26oauth_signature_method%3DHMAC- SHA1%26oauth_timestamp%3D1260811635%26oauth_token %3Df7868c3a-7336-4662- a6d1-3219fb4650d1%26oauth_verifier %3D75553%26oauth_version%3D1.0 Getting an Access Token

Create your Authorization HTTP Header
& Issue the Request Now we sign this string using the secret we constructed from our consumer secret and oauth_token_secret, then create an HTTP Authorization header, including the signature as the oauth_signature value, and oauth_nonce, oauth_callback, oauth_signature_method, oauth_timestamp, oauth_consumer_key, oauth_token, oauth_verifier, and oauth_version. Authorization: OAuth oauth_nonce="WqKwyyrjQLgpaeJIB6MWKKmDOIpxKBrz0lLabSO3 UI", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1260811635", oauth_consumer_key="dTgSkaRKZjEnS1vAUu6e7- aYC00UilBTwnXHpLH7NyL2e-klzBC1a4TKCnSgClWV", oauth_token="f7868c3a-7336-4662-a6d1-3219fb4650d1", oauth_verifier="75553", oauth_signature="gp3C1jCOgRyN106UIe0FLTzOmu8%3D", oauth_version="1.0" Getting an Access Token

Evaluate the accessToken response Now
we issue this request to the accessToken endpoint, and if all is successful, you’ll get something like the following URL encoded response: oauth_token=fb74aed1- eb7d-4f3f-855c-137000243df8&oauth_token_secret=4e7f56 2d-04b1-4488-8162-95a2454ae9a8 The oauth_token field is now your access token, and the oauth_token_secret will be used for signing all requests on behalf of the member. You’ll want to “hold on” to the oauth_token and oauth_token_secret for as long as you want to act on the member’s behalf. A LinkedIn member may specify that an access token is valid only for a certain period of time (or forever), but can revoke access on LinkedIn.com at any time. Getting an Access Token

You’ve acquired an access token!
But don’t hang up your dancing shoes yet.

LinkedIn is about people. LinkedIn
is about you.

Making API resource requests is
very similar to other operations. You’ll need your access token, oauth_token_secret, and your API keys to continue. We’re going to ask for our own profile from LinkedIn’s people resource. In LinkedIn resource URLs, the tilde (“~”) character represents the member associated with your access token. LinkedIn’s API works best when you explicitly tell it what you are looking for, so we’re asking for the member’s id, first name, last name, and their headline only. The resource URL for this request would be: When URL encoding this resource in the following OAuth signing steps, you’ll want to ensure that the tilde character does not become escaped. The field selectors are not query parameters, but part of the path of the URI itself. Requesting your own profile

Start by building your string
to sign. We’ll use these values for this example. Your oauth_token is your access token. HTTP Method GET Request URI https://api.linkedin.com/v1/people/~:(id,first-name,last-name,headline) oauth_consumer_key dTgSkaRKZjEnS1vAUu6e7-aYC00UilBTwnXHpLH7NyL2e-klzBC1a4TKCnSgClWV oauth_nonce Tv4o9eX4Dmui9uW5otBVweTI28O0YmIWPnRhu0XhmY oauth_signature_method HMAC-SHA1 oauth_timestamp 1260915816 oauth_token fb74aed1-eb7d-4f3f-855c-137000243df8 oauth_version 1.0 Requesting your own profile

Start by building your signature
base string. These parameters get sorted alphabetically, each value is URL escaped, and than concatenated into a single string. GET&https%3A%2F%2Fapi.linkedin.com%2Fv1%2Fpeople%2F~ %3A%28id%2Cfirst-name%2Clast-name%2Cheadline %29&oauth_consumer_key%3DdTgSkaRKZjEnS1vAUu6e7- aYC00UilBTwnXHpLH7NyL2e-klzBC1a4TKCnSgClWV %26oauth_nonce %3DTv4o9eX4Dmui9uW5otBVweTI28O0YmIWPnRhu0XhmY %26oauth_signature_method%3DHMAC- SHA1%26oauth_timestamp%3D1260915816%26oauth_token %3Dfb74aed1- eb7d-4f3f-855c-137000243df8%26oauth_version%3D1.0 Requesting your own profile

Create your Authorization HTTP Header
& Issue the Request Now we sign this string using our consumer secret in conjunction with your access token’s oauth_token_secret (just like in our previous steps) and create an HTTP Authorization header,. The signature should be included as the oauth_signature value. Authorization: OAuth oauth_nonce="Tv4o9eX4Dmui9uW5otBVweTI28O0YmIWPnRhu0Xh mY", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1260915816", oauth_consumer_key="dTgSkaRKZjEnS1vAUu6e7- aYC00UilBTwnXHpLH7NyL2e-klzBC1a4TKCnSgClWV", oauth_token="fb74aed1-eb7d-4f3f-855c-137000243df8", oauth_signature="4imDw81fRdCI%2FBBoo0vwix5giVo%3D", oauth_version="1.0" Requesting your own profile

Evaluate the XML response Now
we issue this request to the people resource, and if all is successful, you’ll get something like the following XML response, with your own profile values in place of my own. <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <person> <id>esIpa2xh0v</id> <first-name>Taylor</first-name> <last-name>Singletary</last-name> <headline>Technical Evangelist at LinkedIn</headline> </person> If the access token is invalid, or your signature was not properly calculated, you will receive a 401 Unauthorized error. There is always interesting debugging information in the XML body of a failed request and the HTTP headers we return to you. Maybe your timestamp was off by a few minutes? Maybe your signature was invalid? Maybe the access token is no longer valid? Requesting your own profile

Troubleshooting

OAuth is complicated, and there
are a number of things that go wrong. Here are some tips. Every error response we send you will contain an XML body describing the error, including a timestamp representing API server time. Some OAuth-based requests will also return an oauth_problem HTTP header. Make sure that your server’s system clock is in sync with ours. oauth_callback should only be provided on the requestToken step. oauth_verifier is required in the accessToken step. PUT & POST operations typically have XML Content-Types. Your OAuth library should exclude the request body in signature calculations as a result. For the access token step, remember that the request token’s oauth_token_secret must be used as part of your signing key. Likewise, for API resource requests, your access token’s oauth_token_secret must be used as part of your signing key. At this time, LinkedIn only supports HTTP header-based OAuth. Make sure that you are passing your OAuth credentials as an Authorization HTTP header, not as query parameters attached to the request. Troubleshooting

Working with LinkedIn’s OAuth OAuth
Authentication Common Issues with OAuth Authentication General OAuth OAuth 1.0a Spec Beginner’s Guide to OAuth Client Libraries & Community Code Ruby PHP Java .NET Further Reading

I hope you had the
time of your life mastering the OAuth dance. Thanks to all the great people in the LinkedIn Developer Community!