OAuth Docs

OAuth shouldn't be hard, and neither should docs

Quick Links

Quick Start Guide

This site is providing OAuth 2 through oPRO. If this is your first time using OAuth, please visit What is OAuth or follow along with this guide.

Password Exchange

If you are building a client application and have direct access to a user’s credentials including password, you can exchange them for a token. For more information see password exchange docs.

OAuth 2 Flow

Step 1: Register your application

Sign in as a registered user then visit the new client application page. Enter in the name of your application. For this example, we will use foo; you can change this later if you desire. Hit enter and you should see a screen that has your application name along with a client id and a secret. These behave like a username and password for your OAuth application.

Name:       foo
Client id:  3234myClientId5678
Secret:     14321myClientSecret8765

Once you’ve registered an app successfully we can start to build an OAuth application. Don’t continue until you’ve registered a client app.

Step 2: As a user, grant access to your app

Now that you have a client application, you’ll want to give it access to a user account. Open a new browser window and log in with a user account, then give your application permission by visiting the url below (swap out ‘3234myClientId5678’ for your client id and ‘14321myClientSecret8765’ for your client secret)

https://opro-demo.herokuapp.com/oauth/new?client_id=3234myClientId5678&client_secret=14321myClientSecret8765&redirect_uri=%2F

This should land you on a page asking if you would like to grant permission to the application. If not, make sure you’re logged in and you put the correct client id in the url.

Once you grant your application permission, you will be redirected back to the url provided. In this case, we will go back to the home page of this app.

Once redirected to the home page, take a look in the address bar. We should see a code parameter. Copy this for use later:

https://opro-demo.herokuapp.com/?code=4857goldfish827423

In the url above, the code would be 4857goldfish827423. This code can be used to obtain an access token for the user. Once you have a user’s access token, you can perform actions for the user as if they were logged in. If you accidentally close this page, don’t worry– just visit the first url in Step 2 again and the application will show you the code again.

Step 3: Get an access token for a user with curl

We’ll be using Curl to go through the process of getting an access token for our first user. You’ll likely use http client libraries in your actual application, but most systems come with curl, and it is a fairly easy way to get started. If you’ve never used it before, read our curl documentation

(Note in all code examples the $ character indicates we are on the command line, it does not need to be copied)

You’ll want to make sure to replace client_id, client_secret, and code with your values.

$ curl -X POST -d '' 'https://opro-demo.herokuapp.com/oauth/token.json?client_id=3234myClientId5678&client_secret=14321myClientSecret8765&code=4857goldfish827423'

You should get back a response that looks like this:

$ {"access_token":"9693accessTokena7ca570bbaf","refresh_token":"3a3c129ad02b573de78e65af06c293f1","expires_in":null}

If not, double check the previous steps and ensure you are using the correct values in the query. Once you get a successful response, copy the access_token for use later. In this example, it is 9693accessTokena7ca570bbaf. Treat this access_token as if it were the user’s password. It is sensitive information.

Step 4: Use the access token

Now that we’ve gone through all the hard work of getting an access token, you can use it to make authenticated requests to the server. If you include the correct access_token parameter in your query, you’ll be logged in as that user for that request.

Try it out for yourself. Replace the access token below with the one you received and run this curl command:

$ curl "http://opro-demo.herokuapp.com/oauth_tests/show_me_the_money.json?access_token=9693accessTokena7ca570bbaf"

You should see a successful result (again, don’t forget to replace the example access token with yours). Note that all urls will support OAuth authentication.

You can also use a header to pass the OAuth token:

$ curl -H "Authorization: token 9693accessTokena7ca570bbaf" "http://opro-demo.herokuapp.com/oauth_tests/show_me_the_money.json"

Security

Don’t share your client application’s secret or any user’s access_token with unknown or untrusted parties. Always use https when available and don’t write any of these values to your application’s logs.