OAuth Tools

This page is devoted to explaining and assisting you in successfully designing OAuth-enabled applications. It's a weird idea, but it allows us to have access to some powerful API calls and thus make some more interesting and useful applications.

"You keep saying the word OAuth..."

Possibly the most important concept to understand with OAuth is that when you make API calls, you're not representing your application anymore. You're representing the user. In this way, your application is just a middleman, interpreting a user's input and acting on their behalf. For example, if I made an application to add class schedules to a user's google calendar account, I first require the user to grant me permission to do this on their behalf. This is done in a back-and-forth exchange between your application and the 'identity server' (Duke). The entire process is not unlike shibboleth, except at the end you receive an access token that can be used to make calls on behalf of the user that has just authenticated you. OAuth has several special terms that it uses to keep things clear. Your application is called 'the client'. The user is known as the 'resource owner', as it is their data and identity you are requesting to use. The API is the 'Resource Server', as that's where data resides. The server you authenticate with called the 'identity provider', giving you access to the user's identity and ownership information. This server isn't necessarily the same as the Resource Server, but it often times is. It is also important to understand that OAuth relies entirely on SSL (HTTPS) for security. If you're not familiar with SSL, I'd recommend taking a quick refresher on Wikipedia. If you need help setting up SSL on your server, I'd take a look at the SSL Tutorial.

"You still didn't say how to use it!"

Lucky for us, many stacks (languages and their environments) have libraries or packages available to simplify the use of OAuth in that language. It's a great idea to make use of the big ones, because it is likely that other people have already done the work for us in building and testing them. They should make our jobs a lot easier. Before we get started, we need to go register our application with the Resource Provider (Duke). This will give us a client ID and client secret. They act as a username and password for our account. There are two major use-cases of OAuth. You can use it on a back-end server (like your webserver), where you can keep your code secret from your users, or you can use OAuth on a front-end platform, like a phone app. In the second case, you can't keep anything (passwords) secret from your users. Let's take a look at our Schedule->Calendar example on a back-end server:

We know that we need the user's permission to access their calendar data, so we construct an OAuth URL. We pass it the following GET variables: our client ID (telling them which application this is), a scope (saying what permissions we want), a redirect url (saying where to send the user back when they are done authenticating), and 'response_type=code', saying that we want an auth code in return. This should look something like https://oauth.duke.edu/auth?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=SCOPE. When a user wants to log in, we redirect them to this address. The user will do their thing, and the server will send them back to your REDIRECT_URI with a GET variable code=AUTH_CODE Now we exchange this AUTH_CODE for an access token by making a post request to https://oauth.duke.edu/token with the following variables: grant_type=authorization_code (saying we are giving an authorization code), code=AUTH_CODE (the auth code itself), redirect_uri=REDIRECT_URI, client_id=CLIENT_ID (who we are), and client_secret=CLIENT_SECRET (proving who we are). The server then should reply with an access token (in JSON most likely) like this: {"access_token": "RsT5OjbzRn430zqMLgV3Ia"}. Now you've got an access token to append to your API calls! hooray...