g5_authentication_client 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 97c68343930b548666879d796904ea3345cd791b
+  data.tar.gz: 9a41e522f8fd8ab0ded0d797ce29d2292b272dac
+SHA512:
+  metadata.gz: 8ff4eeaa114f7693c555bffc53a360a762897fb3f60e8dccee176eaf64c82af9d9e957e044f482826ecc33df5242a0692878c59a8b552a354c49bffed3c73290
+  data.tar.gz: 1d377a2678b5435e6f11f8003417cb5a25148fe0889f728d23a266160b09fbeb2dbd4356822a83f9531e3d949da9f5818afd39ef9e1887ae2a4b4c3c05ae8687

data/.gitignore

@@ -0,0 +1,9 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+*~
+.DS_Store
+doc/*
+.yardoc
+coverage

data/.rspec

@@ -0,0 +1 @@
+--colour

data/.ruby-gemset

@@ -0,0 +1 @@
+g5_authentication_client

data/.ruby-version

@@ -0,0 +1 @@
+2.1.0

data/CHANGELOG.md

@@ -0,0 +1,39 @@
+## v0.2.0 (2014-03-10)
+
+* First open source release to [RubyGems](http://rubygems.org/)
+
+## v0.1.5 (2014-03-07)
+
+* Add allow_password_credentials flag to determine whether client instances
+* will allow use of username/passwored attributes
+
+## v0.1.4 (2014-03-06)
+
+* Change configure method namespace to g5_auth from g5_authentication_client
+
+## v0.1.1 (2013-11-15)
+
+* Add `G5AuthenticationClient::Client#sign_out_url`. The client should
+  redirect to this target URL in order sign out the current user.
+
+## v0.1.0 (2013-11-05)
+
+* Rename all references to `client_callback_url` to `redirect_uri`.
+  This is in order to maintain consistency with the terminology used
+  in the OAuth 2.0 spec. This is a breaking change for any code written
+  against earlier versions of the client.
+
+## v0.0.3 (2013-09-23)
+
+* Add support for retrieving user data based on current credentials
+* Add `User#password_confirmation`
+* Allow client to configure an OAuth access token directly (thereby
+  bypassing the OAuth authorization flow)
+
+## v0.0.2 (2013-07-13)
+
+* Update dependency on modelish to v0.3.x
+
+## v0.0.1
+
+* Initial release

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in g5_authentication_client.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2014 G5
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,351 @@
+# G5 Authentication Client #
+
+A client library for the g5-authentication service.
+
+## Current version ##
+
+0.2.0
+
+## Requirements ##
+
+* Ruby >= 1.9.3
+
+## Installation ##
+
+In Gemfile:
+
+```ruby
+gem 'g5_authentication_client'
+```
+
+Just rubygems:
+
+```console
+$ gem install g5_authentication_client
+```
+
+## Configuration ##
+
+### Environment variables ###
+
+You can set the default value for several configuration settings via
+environment variable (not all of these will be used concurrently!):
+
+* `G5_AUTH_CLIENT_ID` - the OAuth 2.0 application ID from the auth server
+* `G5_AUTH_CLIENT_SECRET` - the OAuth 2.0 application secret from the auth server
+* `G5_AUTH_REDIRECT_URI` - the OAuth 2.0 redirect URI registered with the auth server
+* `G5_AUTH_ENDPOINT` - the endpoint URL for the G5 auth server
+* `G5_AUTH_USERNAME` - the username for the end user to authenticate as
+* `G5_AUTH_PASSWORD` - the password for the end user to authenticate as
+* `G5_AUTH_ACCESS_TOKEN` - a valid OAuth 2.0 access token (note that tokens do expire)
+
+### Module-level config ###
+
+Any settings that are configured on the `G5AuthenticationClient` module will
+apply to all instances of `G5AuthenticationClient::Client`, unless that setting
+is overridden at the client level.
+
+```ruby
+G5AuthenticationClient.configure do |config|
+  config.client_id = 'blah'
+  config.client_secret = 'blah'
+  config.redirect_uri = 'blah'
+  config.endpoint = 'blah'
+  config.debug = true
+  config.logger = Rails.logger
+
+  # It would be unusual to configure non-client credentials at the module
+  # level, but it is possible. You would only need to configure one of the
+  # following:
+
+  # If you already have an OAuth access token
+  config.access_token = 'blah'
+
+  # For the OAuth authorization code grant type
+  config.authorization_code = 'blah'
+
+  # For the resource owner password credentials grant type
+  config.username = 'blah'
+  config.password = 'blah'
+end
+```
+
+### Client-level config ###
+
+To override a setting for a particular instance of `G5AuthenticationClient::Client`
+without affecting any other instances, you can pass the configuration option
+into the initializer:
+
+```ruby
+G5AuthenticationClient.configure do |config|
+  config.endpoint = 'https://dev-auth.g5search.com'
+end
+
+client = G5AuthenticationClient::Client.new(endpoint: 'http://localhost:3000')
+client.endpoint
+# => "http://localhost:3000"
+
+client = G5AuthenticationClient::Client.new
+client.endpoint
+# => "https://dev-auth.g5search.com"
+```
+
+## Usage ##
+
+### Retrieving user information ###
+
+Assuming you have a valid access token, set up your client instance:
+
+```ruby
+auth_client = G5AuthenticationClient::Client.new(access_token: 'my_token')
+```
+
+You can retrieve information for the user associated with the access token:
+
+```ruby
+current_user = auth_client.me
+# => #<G5AuthenticationClient::User email="my.user@test.host" id=1>
+```
+
+You can also retrieve informatino about any other user by ID:
+
+```ruby
+user = auth_client.get_user(42)
+# => #<G5AuthenticationClient::User email="another.user@test.host" id=42>
+```
+
+### Retrieving token information ###
+
+You can retrieve information specific to the current access token, including
+scopes and expiration time:
+
+```ruby
+auth_client = G5AuthenticationClient::Client.new(access_token: 'my_access_token')
+token_info = auth_client.token_info
+# => #<G5AuthenticationClient::TokenInfo application_uid={"uid"=>"my_application_id"} expires_in_seconds=5183805 resource_owner_id=1 scopes=[]>
+```
+
+To retrieve the token value itself:
+
+```ruby
+auth_client.get_access_token
+# => "my_access_token"
+```
+
+### Creating a user ###
+
+To create a user, you need their email and password. You can either pass in
+these credentials as an option hash:
+
+```ruby
+auth_client = G5AuthenticationClient::Client.new(access_token: 'my_access_token')
+user = auth_client.create_user(email: 'new.user@test.host',
+                               password: 'testing',
+                               password_confirmation: 'testing')
+# => #<G5AuthenticationClient::User email="new.user@test.host" id=123>
+```
+
+Or you can pass in an instance of `G5AuthenticationClient::User`:
+
+```ruby
+user = G5AuthenticationClient::User.new(email: 'new.user@test.host',
+                                        password: 'testing',
+                                        password_confirmation: 'testing')
+auth_client.create_user(user)
+```
+
+### Updating a user ###
+
+To update an existing user, you'll need the user ID and the new credentials:
+
+```ruby
+auth_client = G5AuthenticationClient::Client.new(access_token: 'my_access_token')
+auth_client.update_user(id: 42,
+                        email: 'updated.email@test.host',
+                        password: 'updated_secret',
+                        password_confirmation: 'updated_secret')
+```
+
+You can also pass in a `G5AuthenticationClient::User` instance instead:
+
+```ruby
+user = auth_client.create_user(email: 'new.user@test.host',
+                               password: 'secret',
+                               password_confirmation: 'secret')
+user.email = 'updated.email@test.host'
+auth_client.update_user(user)
+```
+
+### Deleting a user ###
+
+To delete a user, you need the user ID:
+
+```ruby
+auth_client = G5AuthenticationClient::Client.new(access_token: 'my_access_token')
+auth_client.delete_user(42)
+```
+
+### Sign-out URL ###
+
+In order to sign out of the G5 auth service from a web browser, your client
+application must redirect to the auth server's sign-out URL. You can
+pass in a redirect URL for the auth server to redirect back to after the
+sign-out process is complete.
+
+```ruby
+auth_client = G5AuthenticationClient::Client.new
+auth_client.sign_out_url('https://myapp.host/callback')
+# => "https://auth.g5search.com/users/sign_out?redirect_url=https%3A%2F%2Fmyapp.host%2Fcallback"
+```
+
+## Examples ##
+
+These examples assume that you have already registered your client application
+and at least one end user on the auth server.
+
+### Authorization grant ####
+
+You will need the following credentials:
+
+* Client ID
+* Client secret
+* Redirect URI
+* Authorization code
+
+The client ID, client secret, and redirect URI will be the same for any request
+your application may make, so you will probably want to configure these either
+via environment variables or at the module level:
+
+```ruby
+G5AuthenticationClient.configure do |config|
+  config.client_id = 'my-client-id'
+  config.client_secret = 'my-client-secret'
+  config.redirect_uri = 'https://test.host/callback'
+end
+```
+
+Each authorization code can only be used once, so it's best configured on the
+client instance:
+
+```ruby
+auth_client = G5AuthenticationClient::Client.new(authorization_code: 'my_one_time_use_code')
+```
+
+You can now execute actions against the auth service using that client:
+
+```ruby
+auth_client.me
+# => #<G5AuthenticationClient::User email="another.user@test.host" id=42>
+```
+
+Or you can retrieve an access token in order to authenticate to another G5
+service:
+
+```ruby
+auth_client.get_access_token
+# => "my-g5-access-token-value-abc123"
+```
+
+### Resource owner password credentials grant ###
+
+This grant type is only available to highly trusted client applications that
+do not require explicit authorization by the end user.
+
+You will need the following credentials:
+
+* Client ID
+* Client secret
+* Redirect URI
+* Username
+* Password
+
+Your client credentials will always be the same for every request, so use
+module-level configuration or environment variables for those:
+
+```bash
+export G5_AUTH_CLIENT_ID='my-client-id'
+export G5_AUTH_CLIENT_SECRET='my-client-secret'
+export G5_AUTH_REDIRECT_URI='https://test.host/callback'
+```
+
+If you want to use a different username and password per request, then you
+should configure these on each client instance:
+
+```ruby
+auth_client = G5AuthenticationClient::Client.new(username: 'user1@test.host', password: 'secret1')
+auth_client.me
+# => #<G5AuthenticationClient::User email="user1@test.host" id=1>
+
+auth_client = G5AuthenticationClient::Client.new(username: 'user2@test.host', password: 'secret2')
+auth_client.me
+# => #<G5AuthenticationClient::User email="user2@test.host" id=2>
+```
+
+However, if you want to use the same user credentials for all requests,
+you can set them using environment variables:
+
+```bash
+export G5_AUTH_USERNAME='user1@test.host'
+export G5_AUTH_PASSWORD='secret1'
+```
+
+Now every client instance will authenticate as the same user by default:
+
+```ruby
+G5AuthenticationClient::Client.new.me
+# => #<G5AuthenticationClient::User email="user1@test.host" id=1>
+
+G5AuthenticationClient::Client.new.me
+# => #<G5AuthenticationClient::User email="user1@test.host" id=1>
+```
+
+## Authors ##
+
+* Rob Revels / [@sleverbor](https://github.com/sleverbor)
+* Maeve Revels / [@maeve](https://github.com/maeve)
+
+## Contributing ##
+
+1. Fork it
+2. Get it running
+3. Create your feature branch (`git checkout -b my-new-feature`)
+4. Write your code and **specs**
+5. Commit your changes (`git commit -am 'Add some feature'`)
+6. Push to the branch (`git push origin my-new-feature`)
+7. Create new Pull Request
+
+If you find bugs, have feature requests or questions, please
+[file an issue](https://github.com/G5/g5_authentication_client/issues).
+
+### Running the specs ###
+
+All you have to do is execute rspec through bundler:
+
+```console
+$ bundle exec rspec spec
+```
+
+## License ##
+
+Copyright (c) 2014 G5
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,14 @@
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+namespace :doc do
+  require 'yard'
+  YARD::Rake::YardocTask.new do |task|
+    task.files = ['README.md', 'lib/**/*.rb']
+    task.options = ['--markup', 'markdown']
+  end
+end

data/g5_authentication_client.gemspec

@@ -0,0 +1,34 @@
+$:.push File.expand_path("../lib", __FILE__)
+require "g5_authentication_client/version"
+
+Gem::Specification.new do |s|
+  s.name        = "g5_authentication_client"
+  s.version     = G5AuthenticationClient::VERSION
+  s.authors     = ["Rob Revels", "Maeve Revels"]
+  s.email       = ["rob.revels@getg5.com", "maeve.revels@getg5.com"]
+  s.homepage    = "https://github.com/G5/g5_authentication_client"
+  s.summary     = "Client for the G5 Auth service"
+  s.description = "Client for the G5 Auth service"
+
+  s.rubyforge_project = "g5_authentication_client"
+
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+
+  s.require_paths = ["lib"]
+
+  s.add_dependency('modelish', '~> 0.3')
+  s.add_dependency('configlet', '~> 2.1')
+  s.add_dependency('oauth2')
+  s.add_dependency('addressable')
+
+  s.add_development_dependency('rake')
+  s.add_development_dependency('rspec')
+  s.add_development_dependency('webmock')
+  s.add_development_dependency('fakefs')
+  s.add_development_dependency('simplecov')
+  s.add_development_dependency('codeclimate-test-reporter')
+  s.add_development_dependency('yard')
+  s.add_development_dependency('rdiscount')
+  s.add_development_dependency('vcr')
+end

data/lib/g5_authentication_client/client.rb

@@ -0,0 +1,177 @@
+require 'addressable/uri'
+
+module G5AuthenticationClient
+  # G5AuthenticationClient::Client can be used to authenticate with the G5 OAuth 2
+  # authorization server.  It can also be used to create G5 users.
+  class Client
+    # Mutators for configuration options
+    attr_writer *G5AuthenticationClient::VALID_CONFIG_OPTIONS
+    # Accessors for configuration options
+    G5AuthenticationClient::VALID_CONFIG_OPTIONS.each do |opt|
+      define_method(opt) { get_value(opt) }
+    end
+
+    # @!attribute [rw] allow_password_credentials
+    #   @return [String] 'true' if the client is using the
+    #   username and password attributes
+
+    # @!attribute [rw] endpoint
+    #   @return [String] the g5-authentication service endpoint URL
+
+    # @!attribute [rw] username
+    #   @return [String] the username for authentication
+
+    # @!attribute [rw] password
+    #   @return [String] the password for authentication
+
+    # @!attribute [rw] debug
+    #   @return [String] 'true' if debug logging is enabled
+
+    # @!attribute [rw] logger
+    #   @return [Logger] custom logger instance
+
+    # @!attribute [rw] client_id
+    #   @return [String] client id for this application
+
+    # @!attribute [rw] client_secret
+    #   @return [String] client secret for this application
+
+    # @!attribute [rw] redirect_uri
+    #   @return [String] callback url for application
+
+    # @!attribute [rw] authorization_code
+    #   @return [String] code provided by authorization server
+
+    # @!attribute [rw] access_token
+    #   @return [String] access token value provided by authorization server
+
+    def debug?
+      self.debug.to_s == 'true'
+    end
+
+    # Initializes the client.
+    #
+    # @param [Hash] options
+    # @option options [true,false] :debug true enabled debug logging (defaults to false)
+    # @option options [Logger] :logger a custom logger instance (defaults to STDOUT)
+    # @option options [String] :username The username for authenticating
+    # @option options [String] :password The password for authenticating
+    # @option options [String] :endpoint The authentication endpoint
+    # @option options [String] :client_id The client id for this application
+    # @option options [String] :client_secret The client secret for this application
+    # @option options [String] :redirect_uri The client callback url for this application.
+    # @option options [String] :authorization_code The authentication code from the authorization server.
+    # @option options [String] :allow_password_credentials The client will use username and password if true.
+    def initialize(options={})
+      options.each { |k,v| self.send("#{k}=", v) if self.respond_to?("#{k}=") }
+    end
+
+    # Tells whether a client instance will use the username/password credentials
+    # @return [Boolean] whether the client will use username/password
+    def allow_password_credentials?
+      allow_password_credentials=='true' && !username.nil? && !password.nil?
+    end
+
+    # Retrieves the access token as a string
+    # @return [String] the access token value
+    def get_access_token
+      oauth_access_token.token
+    end
+
+    # Retrieves an attribute's value. If the attribute has not been set
+    # on this object, it is retrieved from the global configuration.
+    #
+    # @see G5AuthenticationClient.configure
+    # 
+    # @param [Symbol] attribute the name of the attribute
+    # @return [String] the value of the attribute
+    def get_value(attribute)
+      instance_variable_get("@#{attribute}") || G5AuthenticationClient.send(attribute)
+    end
+
+    # Create a user from the options
+    # @param [Hash] options
+    # @option options [String] :email The new user's email address
+    # @option options [String] :password The new user's password
+    # @option options [String] :password_confirmation The new user's password confirmation string
+    # @return [G5AuthenticationClient::User]
+    def create_user(options={})
+      user=User.new(options)
+      user.validate_for_create!
+      response=oauth_access_token.post('/v1/users', params: {user: user.to_hash})
+      User.new(response.parsed)
+    end
+
+    # Update an existing user
+    # @param [Hash] options
+    # @option options [String] :email The new user's email address
+    # @option options [String] :password The new user's password
+    # @option options [String] :password_confirmation The new user's password confirmation string
+    # @return [G5AuthenticationClient::User]
+    def update_user(options={})
+      user=User.new(options)
+      user.validate!
+      response=oauth_access_token.put("/v1/users/#{user.id}", params: {user: user.to_hash})
+      User.new(response.parsed)
+    end
+
+    # Get a user
+    # @param [Integer] id the user ID in the remote service
+    # @return [G5AuthenticationClient::User]
+    def get_user(id)
+      response=oauth_access_token.get("/v1/users/#{id}")
+      User.new(response.parsed)
+    end
+
+    # Delete a user
+    # @param [Integer] id the user ID in the remote service
+    # @return [G5AuthenticationClient::User]
+    def delete_user(id)
+      response=oauth_access_token.delete("/v1/users/#{id}")
+      User.new(response.parsed)
+    end
+
+    # Get the current user based on configured credentials
+    # @return [G5AuthenticationClient::User]
+    def me
+      response = oauth_access_token.get('/v1/me')
+      User.new(response.parsed)
+    end
+
+    # Get the access token info for the currently active token
+    # @return [G5AuthenticationClient::TokenInfo]
+    def token_info
+      response = oauth_access_token.get('/oauth/token/info')
+      TokenInfo.new(response.parsed)
+    end
+
+    # Return the URL for signing out of the auth server.
+    # Clients should redirect to this URL to globally sign out.
+    #
+    # @param [String] redirect_url the URL that the auth server should redirect back to after sign out
+    # @return [String] the auth server endpoint for signing out
+    def sign_out_url(redirect_url=nil)
+      auth_server_url = Addressable::URI.parse(endpoint)
+      auth_server_url.path = '/users/sign_out'
+      auth_server_url.query_values = {redirect_url: redirect_url} if redirect_url
+      auth_server_url.to_s
+    end
+
+    private
+    def oauth_client
+      OAuth2::Client.new(client_id, client_secret, site: endpoint)
+    end
+
+    def oauth_access_token
+      @oauth_access_token ||= if access_token
+        OAuth2::AccessToken.new(oauth_client, access_token)
+      elsif authorization_code
+        oauth_client.auth_code.get_token(authorization_code, redirect_uri: redirect_uri)
+      elsif allow_password_credentials?
+        oauth_client.password.get_token(username,password)
+      else
+        raise "Insufficient credentials for access token.  Supply a username/password or authentication code"
+      end
+    end
+  end
+end