oxd-ruby 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3c927e7af3f706adb71804447f38b290df3cb5b1
-  data.tar.gz: cf118779fe069f932110fc38477e990adddd6fb1
+  metadata.gz: a6f9d21c4d5fd1f1e0e893595e97985749bd94e8
+  data.tar.gz: 4fba31e51faf898d93a42180e74786ecf50598e1
 SHA512:
-  metadata.gz: a8b71232f3ecb9c829eba9511ecf6232f7ba9429e18e1afc7f69b62b79aad9ad173e949baa2a3286c21e586f98f7c5b42e38a6408829fcd5371f6cd41f16d2f2
-  data.tar.gz: 116fc42fff057ff8840ecc90493fd1abf4bd978dfc9c065592d7f29a53b6d53801e39fd32646a897a786109d8dc8287cb5c18ba8d167c894bd9d3d66c2018858
+  metadata.gz: bba06880ed389a598e3a6aae0561af20741416875fe017e8643ab3b2078ac784d56cc560a2ac7e3276febb880d092bdb54afa3cdc8742e3c2fa8594a023a90cd
+  data.tar.gz: 8ab4c90bdf20239d69c9c3e7b5d63bfc7d16b524e87c54d029a53b0b3c6627cf6430b2b92b8b47e8636be0353dd63cb0bfc570e39f5ee584c721e15f87cdd1e6

data/CHANGELOG.md

@@ -1,6 +1,19 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+## [0.1.9] - 2017-10-17
+### Added
+- support for oxd-to-https
+- Introduced UMA 2 support
+- `setup_client` command
+- `get_client_token` command
+- `get_access_token_by_refresh_token` command
+- `uma_rp_get_claims_gathering_url` UMA - RP command
+
+### Removed
+- `uma_rp_authorize_rpt` UMA command
+- `uma_rp_get_gat` UMA command
+
 ## [0.1.8] - 2017-05-16
 ### Added
 - support for oxd-to-http

data/README.md

@@ -1,7 +1,7 @@
 # Oxd Ruby
 [![Gem Version](https://badge.fury.io/rb/oxd-ruby.png)](https://badge.fury.io/rb/oxd-ruby)
 
-Ruby Client Library for the [Gluu oxD Server RP - v2.4.4 to v3.0.1](https://www.gluu.org/docs-oxd/).
+Ruby Client Library for the [Gluu oxD Server RP - v3.1.1](https://gluu.org/docs/oxd/3.1.1).
 
 **oxdruby** is a thin wrapper around the communication protocol of oxD server. This can be used to access the OpenID connect & UMA Authorization end points of the Gluu Server via the oxD RP. This library provides the function calls required by a website to access user information from a OpenID Connect Provider (OP) by using the OxD as the Relying Party (RP).
 
@@ -9,22 +9,21 @@ Ruby Client Library for the [Gluu oxD Server RP - v2.4.4 to v3.0.1](https://www.
 
 > You are now on the `master` branch. If you want to use `oxd-ruby` for production use, switch to the branch of the matching version as the `oxd-server` you are installing.
 
-[oxD RP](https://www.gluu.org/docs-oxd/) has complete information about the Code Authorization flow and the various details about oxD RP configuration. This document provides only documentation about the oxd-ruby library.
+[oxD RP](https://gluu.org/docs/oxd/3.1.1) has complete information about the Code Authorization flow and the various details about oxD RP configuration. This document provides only documentation about the oxd-ruby library.
 
 ### Prerequisites
 
-* Install `gluu-oxd-server`
+* A valid OpenID Connect Provider (OP), like the Gluu Server or Google.
+* An active installation of the oxd-server running on the same server as the client application.
+* An active installation of the oxd-https-extension if oxd-https-extension connection is used. In this case, client applications can be on different servers but will be able to access oxd-https-extension.
 
-Oxd-server needs to be running on your machine to connect with OP.
-
-* Enable SSL on your website otherwise this library will not work.
 
 ### Installation
 
 To install gem, add this line to your application's Gemfile:
 
 ```ruby
-gem 'oxd-ruby', '~> 0.1.8'
+gem 'oxd-ruby', '~> 0.1.9'
 ```
 
 Run bundle command to install it:
@@ -32,22 +31,57 @@ Run bundle command to install it:
 ```bash
 $ bundle install
 ```
+#### Important Links
+
+- See the [API docs](https://gluu.org/docs/oxd/3.1.1/libraries/ruby/) for in-depth information about the various functions and their parameters.
+- See the code of a [sample Ruby on Rails app](https://github.com/GluuFederation/oxd-ruby/tree/master/demosite) built using oxd-ruby.
 
 ### Configuring
+
 After you installed oxd-ruby, you need to run the generator command to generate the configuration file:
 
 ```bash
 $ rails generate oxd:config
 ```
 
-The generator will install `oxd_config.rb` initializer file in `config/initializers` directory which conatins all the global configuration options for oxd-ruby plguin.
-The following configurations must be set in config file before the plugin can be used.
+The generator will install `oxd_config.rb` initializer file in `config/initializers` directory which conatins all the global configuration options for oxd-ruby plguin. The generated configuration file looks like this: 
+
+```ruby
+config.oxd_host_ip = '127.0.0.1'
+config.oxd_host_port = 8099
+config.op_host = "https://your.openid.provider.com"
+config.client_id = "<client_id of OpenId provider>"
+config.client_secret = "<client_secret of OpenId provider>"
+config.client_name = "Gluu Oxd Sample Client"
+config.authorization_redirect_uri = "https://domain.example.com/callback"
+config.logout_redirect_uri = "https://domain.example.com/callback2"
+config.post_logout_redirect_uri = "https://domain.example.com/logout"
+config.scope = ["openid","profile", "email", "uma_protection","uma_authorization"]
+config.grant_types = []
+config.application_type = "web"
+config.response_types = ["code"]
+config.acr_values = ["basic"]
+config.client_jwks_uri = ""
+config.client_token_endpoint_auth_method = ""
+config.client_request_uris = []
+config.contacts = ["example-email@gmail.com"]
+config.client_logout_uris = ['https://domain.example.com/logout']
+config.oxd_host = "https://127.0.0.1:8443" set if you are using oxd-https extension
+config.connection_type = "local" if you are using oxd-server without oxd-https extension otherwise "web"
+config.dynamic_registration	= true if the op_host supports dynamic registration otherwise 'false'
+```
+The following configuration must be set in config file before the gem can be used:
 
-1. config.oxd_host_ip
-2. config.oxd_host_port
-3. config.op_host
-4. config.authorization_redirect_uri
+- config.oxd_host_ip
+- config.oxd_host_port
+- config.op_host
+- config.authorization_redirect_uri
+- config.client_id
+- config.client_secret
+- config.connection_type
+- config.oxd_host
 
+**Note :** client_id and client_secret must be set if your OpenID provider does not support dynamic registration, otherwise can be left blank.
 
 ## Usage
 
@@ -61,39 +95,75 @@ protected
 	def set_oxd_commands_instance
 		@oxd_command = Oxd::ClientOxdCommands.new
 		@uma_command = Oxd::UMACommands.new
+		@oxdConfig = @oxd_command.oxdConfig
 	end
 ```
 
-The `ClientOxdCommands` class of the library provides all the methods required for the website to communicate with the oxD RP through sockets.
+The `ClientOxdCommands` class of the library provides all the methods required for the website to communicate with the oxD RP through sockets. The `oxdConfig` method returns Oxd Configuration object.
 The `UMACommands` class provides commands for UMA Resource Server(UMA RS) and UMA Requesting Party(UMA RP) protocol.
 
+### Setup Client
+
+In order to use an OpenID Connect Provider (OP) for login, you need to setup your client application at the OP. During setup oxd will dynamically register the OpenID Connect client and save its configuration. Upon successful setup a unique identifier will be issued by the oxd server by assigning a specific oxd id. Along with oxd Id oxd server will also return client Id and client secret. This client Id and client secret can be used for `get_client_token` method. The Setup Client method is a one time task to configure a client in the oxd server and OP.
+
+**Note:** If your OpenID Connect Provider does not support dynamic registration (like Google), you will need to obtain a ClientID and Client Secret which can be set in `oxd_config.rb` initializer file.
+
+```ruby
+@oxd_command.setup_client
+```
+
+### Get Client Token
+
+The `get_client_token` method is used to get a token which is sent as `protection_access_token` for other methods when the `protect_commands_with_access_token` is enabled in oxd-server.
+
+> `get_client_token` command must be invoked to use following methods when the `protect_commands_with_access_token` is enabled in oxd-server.
+
+```ruby
+@oxd_command.get_client_token
+```
+
 ### Website Registration
 
-The website can be registered with the OpenId Provider using the `@oxd_command.register_site` call.
+In order to use an OpenID Connect Provider (OP) for login, you need to register your client application at the OP. During registration oxd will dynamically register the OpenID Connect client and save its configuration. Upon successful registration a unique identifier will be issued by the oxd server. The Register Site method is a one time task to configure a client in the oxd server and OP.
+
+**Note:** If your OpenID Connect Provider does not support dynamic registration (like Google), you will need to obtain a ClientID and Client Secret which can be set in `oxd_config.rb` initializer file.
+
+```ruby
+@oxd_command.register_site
+```
 
 ### Get Authorization URL
 
-The first step is to generate an authorization url which the user can visit to authorize your application to use the information from the OpenId Provider.
+The `get_authorization_url` method returns the OpenID Connect Provider authentication URL to which the client application must redirect the user to authorize the release of personal data. The response URL includes state value, which can be used to obtain tokens required for authentication. This state value is used 
+to maintain state between the request and the callback.
 
 ```ruby
 authorization_url = @oxd_command.get_authorization_url
 ```
-Using the above url the website can redirect the user for authentication at the OpenId Provider.
+Using the above url the website can redirect the user for authentication at the OpenId Provider. 
 
 ### Get access token
 
-The website needs to parse the information from the callback url and pass it on to get the access token for fetching user information.
+Upon successful login, the login result will return code and state. `get_tokens_by_code` uses code and state to retrieve token which can be used to access user claims.
 
 ```ruby
 code = params[:code]
 state = params[:state]
 access_token = @oxd_command.get_tokens_by_code( code,state )
 ```
-The values for code are parsed from the callback url query parameters.
+The values for code and state are parsed from the callback url query parameters.
+
+### Get Access Token by Refresh Token
+
+The `get_access_token_by_refresh_token` method is used to get a fresh access token and refresh token by using the refresh token which is obtained from `get_tokens_by_code` method.
+
+```ruby
+access_token = @oxd_command.get_access_token_by_refresh_token
+```
 
 ### Get user claims
 
-Claims (user information fields) made availble by the OpenId Provider can be fetched using the access token obtained above.
+Once the user has been authenticated by the OpenID Connect Provider, the `get_user_info` method returns Claims (Like First Name, Last Name, emailId, etc.) about the authenticated end user. Claims (user information fields) made availble by the OpenId Provider can be fetched using the access token obtained above.
 
 ```ruby
 user = @oxd_command.get_user_info(access_token)
@@ -112,7 +182,7 @@ The availability of various claims are completely dependent on the OpenId Provid
 
 ### Logging out
 
-Once the required work is done the user can be logged out of the system.
+Once the required work is done the user can be logged out of the system. `get_logout_uri` method returns the OpenID Connect Provider logout url.
 
 ```ruby
 logout_uri = @oxd_command.get_logout_uri(state, session_state)
@@ -123,6 +193,8 @@ You can then redirect the user to obtained url to perform logout.
 
 ### UMA Protect resources
 
+`uma_rs_protect` method is used for protecting resource with UMA Resource server. Resource server need to construct the command which will protect the resource. The command will contain api path, http methods (POST,GET, PUT) and scopes. Scopes can be mapped with authorization policy (uma_rpt_policies). If no authorization policy mapped, `uma_rs_check_access` method will always return access as granted.
+
 To protect resources with UMA Resource server, you need to add resources to library using `uma_add_resource(path, *conditions)` method. Then you can call following method to register resources for protection with UMA RS.
 
 ```ruby
@@ -136,27 +208,31 @@ To check wether you have access to a particular resource on UMA Resource Sevrer
 ```ruby
 @uma_command.uma_rs_check_access(path, http_method)
 ```
-You must first get RPT before calling this method.
 
 ### Get Requesting Party Token(RPT)
 To gain access to protected resources at the UMA resource server, you must first obtain RPT.
 
-```ruby
-@uma_command.uma_rp_get_rpt(force_new)
-```
+**Method parameters:**
 
-### Authorize RPT
-You must first call `uma_rp_get_rpt` and `uma_rs_check_access` methods before authorizing RPT. If you have already obtained the RPT, use `uma_rp_authorize_rpt` method provided by oxd-ruby library to authorize it.
+- claim_token: (Optional)
+- claim_token_format: (Optional)
+- pct: (Optional)
+- rpt: (Optional)
+- scope: (Optional)
+- state: (Optional) state that is returned from uma_rp_get_claims_gathering_url method
 
 ```ruby
-@uma_command.uma_rp_authorize_rpt
+@uma_command.uma_rp_get_rpt
 ```
 
-### Get Gluu Access Token(GAT)
-To obtain GAT(Gluu Access Token) call following method with scopes as parameter.
+### UMA RP - Get Claims-Gathering URL
+
+**Method parameters:**
+
+- claims_redirect_uri: (Required)
 
 ```ruby
-@uma_command.uma_rp_get_gat(scopes)
+@uma_command.uma_rp_get_claims_gathering_url
 ```
 
 ## Logs

data/demosite/Gemfile

@@ -33,7 +33,8 @@ gem "twitter-bootstrap-rails"
 # Use Capistrano for deployment
 # gem 'capistrano-rails', group: :development
 
-gem 'oxd-ruby', '~> 0.1.8'
+#gem 'oxd-ruby', '~> 0.1.9'
+gem 'oxd-ruby', path: '/var/www/oxd-ruby-3.1.1'
 
 group :development, :test do
   # Call 'byebug' anywhere in the code to stop execution and get a debugger console

data/demosite/Gemfile.lock

@@ -0,0 +1,197 @@
+PATH
+  remote: /var/www/oxd-ruby-3.1.1
+  specs:
+    oxd-ruby (0.1.9)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actionmailer (4.2.6)
+      actionpack (= 4.2.6)
+      actionview (= 4.2.6)
+      activejob (= 4.2.6)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
+    actionpack (4.2.6)
+      actionview (= 4.2.6)
+      activesupport (= 4.2.6)
+      rack (~> 1.6)
+      rack-test (~> 0.6.2)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (4.2.6)
+      activesupport (= 4.2.6)
+      builder (~> 3.1)
+      erubis (~> 2.7.0)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    activejob (4.2.6)
+      activesupport (= 4.2.6)
+      globalid (>= 0.3.0)
+    activemodel (4.2.6)
+      activesupport (= 4.2.6)
+      builder (~> 3.1)
+    activerecord (4.2.6)
+      activemodel (= 4.2.6)
+      activesupport (= 4.2.6)
+      arel (~> 6.0)
+    activesupport (4.2.6)
+      i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    arel (6.0.4)
+    binding_of_caller (0.7.2)
+      debug_inspector (>= 0.0.1)
+    builder (3.2.3)
+    byebug (9.1.0)
+    coffee-rails (4.1.1)
+      coffee-script (>= 2.2.0)
+      railties (>= 4.0.0, < 5.1.x)
+    coffee-script (2.4.1)
+      coffee-script-source
+      execjs
+    coffee-script-source (1.12.2)
+    commonjs (0.2.7)
+    concurrent-ruby (1.0.5)
+    crass (1.0.2)
+    debug_inspector (0.0.3)
+    erubis (2.7.0)
+    execjs (2.7.0)
+    ffi (1.9.18)
+    globalid (0.4.0)
+      activesupport (>= 4.2.0)
+    grease (0.3.1)
+    i18n (0.8.6)
+    jbuilder (2.7.0)
+      activesupport (>= 4.2.0)
+      multi_json (>= 1.2)
+    jquery-rails (4.3.1)
+      rails-dom-testing (>= 1, < 3)
+      railties (>= 4.2.0)
+      thor (>= 0.14, < 2.0)
+    json (1.8.6)
+    less (2.6.0)
+      commonjs (~> 0.2.7)
+    less-rails (3.0.0)
+      actionpack (>= 4.0)
+      grease
+      less (~> 2.6.0)
+      sprockets (> 2, < 4)
+      tilt
+    loofah (2.1.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    mail (2.6.6)
+      mime-types (>= 1.16, < 4)
+    mime-types (3.1)
+      mime-types-data (~> 3.2015)
+    mime-types-data (3.2016.0521)
+    mini_portile2 (2.3.0)
+    minitest (5.10.3)
+    multi_json (1.12.2)
+    nokogiri (1.8.1)
+      mini_portile2 (~> 2.3.0)
+    passenger (5.1.8)
+      rack
+      rake (>= 0.8.1)
+    rack (1.6.8)
+    rack-test (0.6.3)
+      rack (>= 1.0)
+    rails (4.2.6)
+      actionmailer (= 4.2.6)
+      actionpack (= 4.2.6)
+      actionview (= 4.2.6)
+      activejob (= 4.2.6)
+      activemodel (= 4.2.6)
+      activerecord (= 4.2.6)
+      activesupport (= 4.2.6)
+      bundler (>= 1.3.0, < 2.0)
+      railties (= 4.2.6)
+      sprockets-rails
+    rails-deprecated_sanitizer (1.0.3)
+      activesupport (>= 4.2.0.alpha)
+    rails-dom-testing (1.0.8)
+      activesupport (>= 4.2.0.beta, < 5.0)
+      nokogiri (~> 1.6)
+      rails-deprecated_sanitizer (>= 1.0.1)
+    rails-html-sanitizer (1.0.3)
+      loofah (~> 2.0)
+    railties (4.2.6)
+      actionpack (= 4.2.6)
+      activesupport (= 4.2.6)
+      rake (>= 0.8.7)
+      thor (>= 0.18.1, < 2.0)
+    rake (12.1.0)
+    rb-fsevent (0.10.2)
+    rb-inotify (0.9.10)
+      ffi (>= 0.5.0, < 2)
+    rdoc (4.3.0)
+    sass (3.5.2)
+      sass-listen (~> 4.0.0)
+    sass-listen (4.0.0)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+    sass-rails (5.0.6)
+      railties (>= 4.0.0, < 6)
+      sass (~> 3.1)
+      sprockets (>= 2.8, < 4.0)
+      sprockets-rails (>= 2.0, < 4.0)
+      tilt (>= 1.1, < 3)
+    sdoc (0.4.2)
+      json (~> 1.7, >= 1.7.7)
+      rdoc (~> 4.0)
+    spring (2.0.2)
+      activesupport (>= 4.2)
+    sprockets (3.7.1)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.2.1)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    sqlite3 (1.3.13)
+    thor (0.20.0)
+    thread_safe (0.3.6)
+    tilt (2.0.8)
+    turbolinks (5.0.1)
+      turbolinks-source (~> 5)
+    turbolinks-source (5.0.3)
+    twitter-bootstrap-rails (3.2.2)
+      actionpack (>= 3.1)
+      execjs (>= 2.2.2, >= 2.2)
+      less-rails (>= 2.5.0)
+      railties (>= 3.1)
+    tzinfo (1.2.3)
+      thread_safe (~> 0.1)
+    uglifier (3.2.0)
+      execjs (>= 0.3.0, < 3)
+    web-console (2.3.0)
+      activemodel (>= 4.0)
+      binding_of_caller (>= 0.7.2)
+      railties (>= 4.0)
+      sprockets-rails (>= 2.0, < 4.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  byebug
+  coffee-rails (~> 4.1.0)
+  jbuilder (~> 2.0)
+  jquery-rails
+  oxd-ruby!
+  passenger
+  rails (= 4.2.6)
+  sass-rails (~> 5.0)
+  sdoc (~> 0.4.0)
+  spring
+  sqlite3
+  turbolinks
+  twitter-bootstrap-rails
+  uglifier (>= 1.3.0)
+  web-console (~> 2.0)
+
+BUNDLED WITH
+   1.14.4