omniauth-oauth2-generic 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c60894fadcf2f9014bc48732350f0294c8743a60
-  data.tar.gz: 11bba29d2e3fdea5edeb6eebb2679376dafa5838
+  metadata.gz: 2aafc697077de64004d84a22931a24ee7fa00677
+  data.tar.gz: 3cb369bb874ba72282ce959700d0d7a0941a39e3
 SHA512:
-  metadata.gz: cb6e8cee46248d982b1d228e1d0e836b6c52c895b65b7ddb6dd13861150aa63fe20c8c4f8d1c66f2df6eb4704e24300fe9d3b17386d5aabefcc50374b38e5471
-  data.tar.gz: c98f7e1af754afb486fc978b37e1f4916afd93a34108bdf9f3df8561ab01f887ee2518a64bfdeda82afc0ff21f93525b26dead3b0684c4193019d57b34cc8821
+  metadata.gz: 56ad238ca00762a15b982939b98eb3e6b4834318e2b260b437ae55e37c96c7c684856f6f712a11fbc11c17d628c586a940316a13c6dcfa218c4520151a53775b
+  data.tar.gz: 3eb8373c3a07b33bcda9a8c0958c4dac039df7c754fbcef8c884125a011eea14098699a4b7d50c2f25ee922f51f3701a8c6d61ae910fba355b6193862e68c7c1

data/README.md

@@ -2,11 +2,16 @@
 
 By [Internet Exposure](https://www.iexposure.com/)
 
-[![build](http://gitlab.iexposure.com/satorix/omniauth-oauth2-generic/badges/master/build.svg)](http://gitlab.iexposure.com/satorix/omniauth-oauth2-generic/pipelines)
-[![coverage](http://gitlab.iexposure.com/satorix/omniauth-oauth2-generic/badges/master/coverage.svg)](http://gitlab.iexposure.com/satorix/omniauth-oauth2-generic/pipelines)
-
 This gem provides an OmniAuth strategy for authenticating with an OAuth2 service using the authorization grant flow.
 
+Most OmniAuth gems are written either as abstractions ([omniauth-oauth2](https://github.com/intridea/omniauth-oauth2)) or for a specific provider ([omniauth-github](https://github.com/intridea/omniauth-github)), but this one is designed to be configurable enough to work with any basic OAuth2 provider.  The primary differences between OAuth2 provider strategies in OmniAuth are:
+ 
+ 1. The server's domain
+ 2. The URL paths used to authorize, request tokens and get user info
+ 3. The structure of the returned user information
+
+These are all [configurable options](#configuration-options) in this gem.  There my be certain requirements/features of some providers not covered by this gem's options, but it was designed primarily so that if you are implementing your own OAuth2 provider for your service, you don't need to write an OmniAuth strategy as long as it is compatible with the basic options provided by this gem. 
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -29,11 +34,35 @@ Include this gem in your client app [as you would any OmniAuth strategy](https:/
         site: 'https://your_oauth_server', # including port if necessary
         user_info_url: '/api/path/to/fetch/current_user/info'
       },
-      name: 'Satorix' # optional - alternate name for the strategy (appears in URLs)
+      name: 'Satorix' # optional - custom name for the strategy (appears in URLs)
   end
 ```
 
-**Gitlab Config Example:**
+Now if you visit `http://yourserver/auth/oauth2_generic` (or `/auth/Satorix` for the custom name example), you should be directed to log in with your OAuth2 server.
+
+## Configuration Options
+
+Details about the available configuration options are provided as comments in [the OAuth2Generic class](lib/omniauth/strategies/oauth2_generic.rb).
+
+Configuration options for this gem are:
+
+* **client_options** - A Hash containing options for configuring the OAuth client to point to the right URLs
+* **user_response_structure** - A Hash containing paths to various attributes of the user in the response that your OAuth server returns from the `user_info_url` specified in the `client_options`.
+  * **root_path** - An Array containing each key in the path to the node that contains the user attributes (i.e. `['data', 'attributes']` for a JsonAPI-formatted response)
+  * **id_path** - A String containing the name, or Array containing the keys in the path to the node that contains the user's ID (i.e. `['data', 'id']` for a JsonAPI-formatted response). Default: `'id'` (string values are assumed to be relative to the `root_path`)
+  * **attributes** - A Hash containing [standard Omniauth user attributes](https://github.com/omniauth/omniauth/wiki/auth-hash-schema#schema-10-and-later) and the names/paths to them in the response, if not the standard names (this hash defaults to looking for the standard names under the specified `root_path`)
+  
+    **Note:** The entire raw response will also be returned in the `['extra']['raw_info']` field of the OmniAuth auth hash, regardless of the value of this option.
+* **redirect_url** - The URL the client will be directed to after authentication. Defaults to `http://yourserver/auth/oauth2_generic/callback`
+
+  **Note:** Your OAuth server may restrict redirects to a specific list of URLs.
+* **name** - A String.  If set, this changes the name of the strategy used in the URLs and sometimes other places (the login button in Gitlab, for instance)
+  
+The hash options have default values for all keys, and your provided configuration is merged into the default, so you do not have to re-specify nested default options (although you will need to provide at least `site` and `user_info_url` in `client_options`, unless you want to use the default/example gitlab.com configuration). 
+
+
+### Gitlab Config Example
+As this gem was written to enable custom authentication in Gitlab, here is an example of how you would configure it in a Gitlab configuration file:
 
 ```ruby
 # /etc/gitlab/gitlab.rb
@@ -50,6 +79,10 @@ gitlab_rails['omniauth_providers'] = [
         'site' => 'https://your_oauth_server', # including port if necessary
         'user_info_url' => '/api/path/to/fetch/current_user/info'
       },
+      user_response_structure: {
+        root_path: ['data', 'user'], # i.e. if attributes are returned in JsonAPI format (in a 'user' node nested under a 'data' node)
+        attributes: { nickname: 'username' } # if the nickname attribute of a user is called 'username'
+      },
       # optionally, you can add the following two lines to "white label" the display name
       # of this strategy (appears in urls and Gitlab login buttons)
       # If you do this, you must also replace oauth2_generic, everywhere it appears above, with the new name. 
@@ -58,26 +91,4 @@ gitlab_rails['omniauth_providers'] = [
     }
   }
 ]
-````
-
-Now if you visit `http://yourserver/auth/oauth2_generic` (or `/auth/Satorix` for the custom name example), you should be directed to log in with your OAuth2 server.
-
-## Configuration Options
-
-Details about the available configuration options are provided as comments in [the OAuth2Generic class](lib/omniauth/strategies/oauth2_generic.rb).
-
-Configuration options for this gem are:
-
-* **client_options** - A Hash containing options for configuring the OAuth client to point to the right URLs
-* **user_response_structure** - A Hash containing paths to various attributes of the user in the response that your OAuth server returns from the `user_info_url` specified in the `client_options`.
-  * **root_path** - An Array containing each key in the path to the node that contains the user attributes (i.e. `['data', 'attributes']` for a JsonAPI-formatted response)
-  * **id_path** - A String containing the name, or Array containing the keys in the path to the node that contains the user's ID (i.e. `['data', 'id']` for a JsonAPI-formatted response). Default: `'id'` (string values are assumed to be relative to the `root_path`)
-  * **attributes** - A Hash containing [standard Omniauth user attributes](https://github.com/omniauth/omniauth/wiki/auth-hash-schema#schema-10-and-later) and the names/paths to them in the response, if not the standard names (this hash defaults to looking for the standard names under the specified `root_path`)
-  
-    **Note:** The entire raw response will also be returned in the `['extra']['raw_info']` field of the OmniAuth auth hash, regardless of the value of this option.
-* **redirect_url** - The URL the client will be directed to after authentication. Defaults to `http://yourserver/auth/oauth2_generic/callback`
-
-  **Note:** Your OAuth server may restrict redirects to a specific list of URLs.
-* **name** - A String.  If set, this changes the name of the strategy used in the URLs and sometimes other places (the login button in Gitlab, for instance)
-  
-The hash options have default values for all keys, and your provided configuration is merged into the default, so you do not have to re-specify nested default options (although you will need to provide at least `site` and `user_info_url` in `client_options`, unless you want to use the default/example gitlab.com configuration). 
+````

data/lib/omniauth-oauth2-generic/version.rb

@@ -1,5 +1,5 @@
 module Omniauth
   module OAuth2Generic
-    VERSION = "0.2.2"
+    VERSION = "0.2.3"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omniauth-oauth2-generic
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - Joe Marty
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-01-16 00:00:00.000000000 Z
+date: 2017-11-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: omniauth-oauth2
@@ -135,7 +135,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: Generic, Configurable OmniAuth Strategy for OAuth2 providers