opro/opro

## Quick Start Guide

This site is providing OAuth 2 through [oPRO](http://github.com/schneems/opro). If this is your first time using OAuth, please visit [What is OAuth](<%= oauth_doc_path(:oauth) %>) or follow along with this guide.

<% if ::Opro.password_exchange_enabled? %>

## 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_doc_path(:password_exchange) %>).

<% end %>

# OAuth 2 Flow


## Step 1: Register your application

Sign in as a registered user then visit the [new client application page](<%= new_oauth_client_app_path %>). 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](<%= new_oauth_client_app_path %>).  Also be aware that the client app is associated to the user that created it for purposes of administration.


## 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)

    <%= oauth_new_url(:protocol => @protocol, :redirect_uri => "/", :client_id => "3234myClientId5678") %>


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:

    <%= root_url(:protocol => @protocol) + "?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](<%= oauth_doc_path(: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](<%= oauth_doc_path(:curl) %>)

(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 '' '<%= oauth_token_url(
                                :protocol      => @protocol,
                                :client_id     => "3234myClientId5678",
                                :client_secret => "14321myClientSecret8765",
                                :code          => "4857goldfish827423",
                                :format        => "json") %>'


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 "<%= oauth_test_url(:show_me_the_money, :access_token => '9693accessTokena7ca570bbaf', :format => 'json') %>"



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" "<%= oauth_test_url(:show_me_the_money, :format => '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.