opro 0.3.2 → 0.3.3

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.3.3
+
+- [#8] Fix Doc urls (@robe5)
+
 ## 0.3.2
 
 - Attempt to find user based on params[:username] from client in devise default find_user_for_auth

data/VERSION

@@ -1 +1 @@
-0.3.2
+0.3.3

data/app/controllers/opro/oauth/docs_controller.rb

@@ -8,9 +8,11 @@ class Opro::Oauth::DocsController < OproController
   helper_method :render_doc
 
   def index
+    @protocol = protocol
   end
 
   def show
+    @protocol = protocol
     @doc = params[:id]
   end
 
@@ -23,6 +25,10 @@ class Opro::Oauth::DocsController < OproController
 
   private
 
+  def protocol
+    Rails.env.production? ? "https" : "http"
+  end
+
   def parse_erb(str)
     ERB.new(str).result(binding)
   end

data/app/views/opro/oauth/docs/markdown/curl.md.erb

@@ -1,6 +1,6 @@
 # Curl
 
-[Curl](http://curl.haxx.se/) is a command line tool for transfering data with a url syntax. Most systems should have curl installed. Open up terminal on OS X or command prompt on windows and type in `curl`. There are parts of the OAuth process that were not intended for direct human interaction such as exchanging the code from the Provider for an access_token. Because of this, it can be easier to use `curl` to talk to a server directly instead of using a web browser.
+[Curl](http://curl.haxx.se/) is a command line tool for transferring data with a url syntax. Most systems should have curl installed. Open up terminal on OS X or command prompt on windows and type in `curl`. There are parts of the OAuth process that were not intended for direct human interaction such as exchanging the code from the Provider for an access_token. Because of this, it can be easier to use `curl` to talk to a server directly instead of using a web browser.
 
 ## What is it good for?
 
@@ -39,17 +39,13 @@ You can ask for the headers of a request by adding the `-I` flag to a curl comma
 
 You can set a request header by using `-H` for example if you wanted to send an access_token in a header you could issue this request (assuming your access token is '9693accessTokena7ca570bbaf')
 
-    $ curl -H "Authorization: token 9693accessTokena7ca570bbaf" "http://localhost:3000/oauth_test/show_me_the_money"
+    $ curl -H "Authorization: token 9693accessTokena7ca570bbaf" "<%= oauth_test_url(:show_me_the_money, :protocol => @protocol)%>"
 
 
 ### HTTP Verb
 
-You can specify the type of request you make in curl (GET, POST, PUT, DELETE, etc.) by specifying `-X`. For example if you wanted to POST to the /products url at localhost:3000/products you could do so like this:
-
-    $ curl -X POST http://localhost:3000
-
-
-
+You can specify the type of request you make in curl (GET, POST, PUT, DELETE, etc.) by using `-X`. For example if you wanted to POST to the /products url at localhost:3000/products you could do so like this:
 
+    $ curl -X POST <%= root_url %>
 
 

data/app/views/opro/oauth/docs/markdown/oauth.md.erb

@@ -1,9 +1,9 @@
-## Opro Oauth
+## OAuth 2
 
 OAuth comes in a few different flavors, the implementation of OAuth comes from [Version 22 of the OAuth 2.0 protocol](http://tools.ietf.org/html/draft-ietf-oauth-v2-22) and is heavily influenced by [Facebook's Server Side OAuth Authentication](http://developers.facebook.com/docs/authentication/server-side/) and [Github's API](http://developer.github.com/v3/oauth/).
 
 
-## What is It?
+## What is OAuth?
 
 OAuth is a secure way to grant authorization without having to transfer passwords to third parties. If you've used an iPhone or Android app to access Twitter or Facebook you've likely used OAuth.
 
@@ -24,7 +24,7 @@ Client and server side web applications can use this type of authorization to ad
 
 ## Alternatives
 
-OAuth is simple in concept, but can be tricky to implement right. Many services also support basic auth. With basic auth you send a user's username and password along with every request. While this is fairly simple it means that the client application has access to your password, which is not very secure.
+OAuth is simple in concept, but can be tricky to implement right. Many services also support basic auth. With basic auth you send a user's username and password along with every request. While this is fairly simple it means that the client application store your password, which is not very secure.
 
 
 ## Clients

data/app/views/opro/oauth/docs/markdown/password_exchange.md.erb

@@ -5,22 +5,29 @@
 
 If you're building a mobile (iPhone, Android, etc.) app it can be easier to exchange a user's password and email/username for an access token then to send your user throught the traditional OAuth flow.
 
-## Get Started
 
-First obtain a client app id and secret, if you don't have them see the [Quick Start Guide](/oauth_docs/quick_start) and return here. For this example we will use this data:
+## Step 1: Register your Application
 
-    Name:       foo
-    client id:  3234myClientId5678
-    Secret:     14321myClientSecret8765
+Sign in as a registered user then visit the [new client application page](/oauth_client_apps/new). Enter in the name of your application for this example we can 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.
 
-Note you will need to replace the client id and secret with your actual client id and secret.
+
+    Name:           foo
+    client id:      3234myClientId5678
+    client 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](/oauth_client_apps/new).
+
+**Note:** Replace the client id and secret with your actual client id and secret.
 
 Once you have your id and secret, you can ask the user of your application to provide you with their username and password. For the purposes of this we will be using the example email address of `foo@example.com` and password of `p4ssw0rd`.
 
-Once you have the email/username and password of your user on the mobile device, you can then send all of this information to the server with your client id & secret. Don't forget to url encode any special characters like `@`, and always transmit this sensitive data using secure https:
+**Note:** Replace the email and password with a real user's credentials.
+
 
+Once you have the email/username and password of a user, you can exchange this information for a token by sending the server your client\_id & client\_secret along with username and password. Don't forget to url encode any special characters like `@`, and always transmit this sensitive data using a secure protocol (such as https):
 
-    <%= "#{request.base_url.gsub('http://', 'https://')}/oauth/token?" %>email=foo%40example.com&password=p4ssw0rd&client_id=3234myClientId5678&client_secret=14321myClientSecret8765
+    <%= oauth_token_url(:protocol => @protocol, :email => "foo@example.com", :password => "p4ssw0rd", :client_id => "3234myClientId5678", :client_secret => "14321myClientSecret8765" ) %>
 
 The response should be json with an access_token:
 

data/app/views/opro/oauth/docs/markdown/permissions.md.erb

@@ -3,24 +3,26 @@
 
 # Permissions
 
-Permissions give the user a way to control the scope of access that a client application has to their data. This is similar to how Facebook will ask users what actions an app can take on their part.
+Permissions give the user a way to control the scope of access that a client application has to their data. This is similar to how Facebook will ask users what actions an application can take on their behalf.
 
 
 <% if ::Opro.request_permissions.present? && ::Opro.request_permissions.map(&:to_s).include?("write") %>
 
 ## Write Access
 
-To perform any type of request other than a GET ([HTTP Request methods](http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods)), your application must have `write` access to the user. You can specify this scope (see Request Scope below) or by default all permissions will be requested.
+To perform any type of request other than a [GET](http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods) request, your application must have `write` access from the user. Your application can request this permission with `scope` (see Request Scope below). By default all permissions will be requested.
 
 <% end %>
 
 ## Request Scope
 
-As a client app you can request specific scopes while you are authing a user, if no scope is specified all permissions will be requested.
+As a client application you can request specific scopes while you are authorizing a user, if no scope is specified all permissions will be requested. This is an example of an application with client id of `3234myClientId5678` specifying that they want `write` access for their app:
 
-      <%= "#{request.base_url}/oauth/authorize?" %>scope[]=write&#... %>
 
-While authorizing your app a user can choose to accept or deny individual permissions.
+    <%= oauth_authorize_url(:client_id => "3234myClientId5678", :protocol => @protocol) + "&scope[]=write" %>
+
+
+While authorizing your application a user can choose to grant or reject individual permissions.
 
 
 ## Available Permissions/Scopes

data/app/views/opro/oauth/docs/markdown/quick_start.md.erb

@@ -1,11 +1,21 @@
 ## Quick Start Guide
 
-This site is providing OAuth 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.
+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](/oauth_client_applications/new). Enter in the name of your application for this example we can 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.
+Sign in as a registered user then visit the [new client application page](/oauth_client_apps/new). Enter in the name of your application for this example we can 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
@@ -13,14 +23,15 @@ Sign in as a registered user then visit the [new client application page](/oauth
     Secret:     14321myClientSecret8765
 
 
-Once you've registered an app successfully we can start to build an OAuth application
+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](/oauth_client_apps/new).
 
 
 ## Step 2: As a User Grant access to your App
 
-Now that you have a client id, you'll want to give it access to a  user account. Open a new browser window with your currently logged in account, then give your application permission by visiting the url below (please swap out '3234myClientId5678' for your client id)
+Now that you have a client application, you'll want to give it access to a user account. Open a new browser window with your currently logged in account, then give your application permission by visiting the url below (swap out '3234myClientId5678' for your client id and '14321myClientSecret8765' for your client secret)
+
+    <%= oauth_authorize_url(:protocol => @protocol, :redirect_uri => "/", :client_id => "3234myClientId5678", :client_secret => "14321myClientSecret8765" ) %>
 
-    <%= "#{request.base_url}/oauth/authorize?" %>client_id=3234myClientId5678&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.
 
@@ -28,44 +39,49 @@ Once you grant your application permission, you will be redirected back to the u
 
 Once redirected to the home page, take a look in the address bar, we should see a `code` parameter. Copy this for use later:
 
-    <%= "#{request.base_url}" %>?code=4857goldfish827423
+    <%= 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 first url and we'll show you the code again.
 
 
-## Step 3: Get AccessToken for User with Curl
+## 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 for our first user, you'll likely use http client libraries in your actual applications, 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 coppied)
 
+You'll want to make sure to replace `client_id`, `client_secret`, and `code` with your values.
 
-    $ curl '<%= "#{request.base_url}/oauth/token?" %>?client_id=3234myClientId5678&client_secret=14321myClientSecret8765&code=4857goldfish827423'
 
-You'll want to make sure to replace `client_id`, `client_secret`, and `code` with your values.
+    $ curl '<%= oauth_token_url(:protocol      => @protocol,
+                                :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. Copy the `access_token` we'll use it for the rest of our application, in this example it is `9693accessTokena7ca570bbaf`. Treat this access_token as if it were the user's password. It is sensitive information.
+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 we've gone through all the hard work of getting this token, you can use it to make authenticated requests to the server. You'll just need to include the correct `access_token` parameter in your query and you'll be logged in as that user for that request.
+Now we've gone through all the hard work of getting an access token, you can use it to make authenticated requests to the server. You'll need to include the correct `access_token` parameter in your query and 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, then you can run this curl command:
 
-Try it out for yourself open up a browser and go to
+    $ curl "<%= oauth_tests_url(:show_me_the_money, :access_token => '9693accessTokena7ca570bbaf') %>"
 
-    <%= "#{request.base_url}/oauth_test/show_me_the_money?access_token=9693accessTokena7ca570bbaf" %>
 
 
-You should see a successful result ( again don't forget to replace the example access token with yours ). Not all urls will support OAuth authentication.
+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
 
-    <%= %Q{ curl -H "Authorization: token 9693accessTokena7ca570bbaf" "#{request.base_url}/oauth_test/show_me_the_money" } %>
+    $ curl -H "Authorization: token 9693accessTokena7ca570bbaf" "<%= oauth_tests_url(:show_me_the_money) %>"
 
 
 ## Security

data/app/views/opro/oauth/docs/markdown/refresh_tokens.md.erb

@@ -9,7 +9,11 @@ Refresh tokens can be used to refresh an expiring `access_token`. When you recei
 If a token has expired or you simply wish to receive a new `access_token` you can send your `refresh_token` along with your `app_id` and `app_secret` to `/oauth/token` and your access_token will be refreshed.
 
 
-    $ curl '<%= "#{request.base_url}/oauth/token?" %>?client_id=3234myClientId5678&client_secret=14321myClientSecret8765&refresh_token=4857goldfish827423'
+
+    $ curl '<%= oauth_token_url(:protocol      => @protocol,
+                                :client_id     => "3234myClientId5678",
+                                :client_secret => "14321myClientSecret8765",
+                                :refresh_token => "4857goldfish827423") %>'
 
 You'll want to make sure to replace `client_id`, `client_secret`, and `refresh_token` with your values.
 

data/opro.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "opro"
-  s.version = "0.3.2"
+  s.version = "0.3.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["schneems"]
-  s.date = "2012-07-30"
+  s.date = "2012-08-01"
   s.description = " Enable OAuth clients (iphone, android, web sites, etc.) to access and use your Rails application, what you do with it is up to you"
   s.email = "richard.schneeman@gmail.com"
   s.extra_rdoc_files = [

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opro
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-30 00:00:00.000000000Z
+date: 2012-08-01 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70102804767380 !ruby/object:Gem::Requirement
+  requirement: &70221194337460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: 3.1.0
   type: :runtime
   prerelease: false
-  version_requirements: *70102804767380
+  version_requirements: *70221194337460
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &70102804769580 !ruby/object:Gem::Requirement
+  requirement: &70221194339080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: 3.1.0
   type: :runtime
   prerelease: false
-  version_requirements: *70102804769580
+  version_requirements: *70221194339080
 - !ruby/object:Gem::Dependency
   name: bluecloth
-  requirement: &70102804771760 !ruby/object:Gem::Requirement
+  requirement: &70221194340700 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70102804771760
+  version_requirements: *70221194340700
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &70102804773620 !ruby/object:Gem::Requirement
+  requirement: &70221194342280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70102804773620
+  version_requirements: *70221194342280
 - !ruby/object:Gem::Dependency
   name: timecop
-  requirement: &70102804781920 !ruby/object:Gem::Requirement
+  requirement: &70221194351740 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70102804781920
+  version_requirements: *70221194351740
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &70102804789160 !ruby/object:Gem::Requirement
+  requirement: &70221194350540 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -76,10 +76,10 @@ dependencies:
         version: 1.6.4
   type: :development
   prerelease: false
-  version_requirements: *70102804789160
+  version_requirements: *70221194350540
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &70102804788560 !ruby/object:Gem::Requirement
+  requirement: &70221194349660 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,10 +87,10 @@ dependencies:
         version: 1.1.3
   type: :development
   prerelease: false
-  version_requirements: *70102804788560
+  version_requirements: *70221194349660
 - !ruby/object:Gem::Dependency
   name: capybara
-  requirement: &70102804787900 !ruby/object:Gem::Requirement
+  requirement: &70221194348900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -98,10 +98,10 @@ dependencies:
         version: 0.4.0
   type: :development
   prerelease: false
-  version_requirements: *70102804787900
+  version_requirements: *70221194348900
 - !ruby/object:Gem::Dependency
   name: sqlite3
-  requirement: &70102804787420 !ruby/object:Gem::Requirement
+  requirement: &70221194348160 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -109,10 +109,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70102804787420
+  version_requirements: *70221194348160
 - !ruby/object:Gem::Dependency
   name: launchy
-  requirement: &70102804786900 !ruby/object:Gem::Requirement
+  requirement: &70221194347460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -120,10 +120,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70102804786900
+  version_requirements: *70221194347460
 - !ruby/object:Gem::Dependency
   name: devise
-  requirement: &70102804786420 !ruby/object:Gem::Requirement
+  requirement: &70221194346840 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -131,10 +131,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70102804786420
+  version_requirements: *70221194346840
 - !ruby/object:Gem::Dependency
   name: rcov
-  requirement: &70102804785940 !ruby/object:Gem::Requirement
+  requirement: &70221194346340 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -142,10 +142,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70102804785940
+  version_requirements: *70221194346340
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &70102804785460 !ruby/object:Gem::Requirement
+  requirement: &70221194345800 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -153,7 +153,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70102804785460
+  version_requirements: *70221194345800
 description: ! ' Enable OAuth clients (iphone, android, web sites, etc.) to access
   and use your Rails application, what you do with it is up to you'
 email: richard.schneeman@gmail.com
@@ -280,7 +280,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2934563165059774319
+      hash: 2666856507921880303
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: