diff --git a/README.md b/README.md index 5174b6a..9fd2a5d 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [github_actions_status]: https://github.com/dlindahl/omniauth-cas/actions/workflows/ci.yml/badge.svg [releases]: https://github.com/dlindahl/omniauth-cas/releases -This is a OmniAuth 1.0 compatible port of the previously available +This is an OmniAuth 2.0 compatible port of the previously available [OmniAuth CAS strategy][old_omniauth_cas] that was bundled with OmniAuth 0.3. * [View the documentation][document_up] @@ -16,15 +16,21 @@ This is a OmniAuth 1.0 compatible port of the previously available Add this line to your application's Gemfile: - gem 'omniauth-cas' +```ruby +gem 'omniauth-cas' +``` And then execute: - $ bundle +```bash +bundle +``` Or install it yourself as: - $ gem install omniauth-cas +```bash +gem install omniauth-cas +``` ## Usage @@ -42,50 +48,45 @@ end OmniAuth CAS requires at least one of the following two configuration options: - * `url` - Defines the URL of your CAS server (i.e. `http://example.org:8080`) - * `host` - Defines the host of your CAS server (i.e. `example.org`). +* `url` - Defines the URL of your CAS server (i.e. `http://example.org:8080`) +* `host` - Defines the host of your CAS server (i.e. `example.org`). #### Optional Other configuration options: - * `port` - The port to use for your configured CAS `host`. Optional if using `url`. - * `ssl` - TRUE to connect to your CAS server over SSL. Optional if using `url`. - * `service_validate_url` - The URL to use to validate a user. Defaults to `'/serviceValidate'`. - * `callback_url` - The URL custom URL path which CAS uses to call back to the service. Defaults to `/users/auth/cas/callback`. - * `logout_url` - The URL to use to logout a user. Defaults to `'/logout'`. - * `login_url` - Defines the URL used to prompt users for their login information. Defaults to `/login` If no `host` is configured, the host application's domain will be used. - * `uid_field` - The user data attribute to use as your user's unique identifier. Defaults to `'user'` (which usually contains the user's login name). - * `ca_path` - Optional when `ssl` is `true`. Sets path of a CA certification directory. See [Net::HTTP][net_http] for more details. - * `disable_ssl_verification` - Optional when `ssl` is true. Disables verification. - * `merge_multivalued_attributes` - When set to `true` returns attributes with multiple values as arrays. Defaults to `false` and returns the last value as a string. - * `on_single_sign_out` - Optional. Callback used when a [CAS 3.1 Single Sign Out][sso] - request is received. - * `fetch_raw_info` - Optional. Callback used to return additional "raw" user - info from other sources. - - ```ruby - provider :cas, - fetch_raw_info: Proc.new { |strategy, opts, ticket, user_info, rawxml| - return {} if user_info.empty? || rawxml.nil? # Auth failed - - extra_info = ExternalService.get(user_info[:user]).attributes - extra_info.merge!({'roles' => rawxml.xpath('//cas:roles').map(&:text)}) - extra_info - } - ``` +* `port` - The port to use for your configured CAS `host`. Optional if using `url`. +* `ssl` - TRUE to connect to your CAS server over SSL. Optional if using `url`. +* `service_validate_url` - The URL to use to validate a user. Defaults to `'/serviceValidate'`. +* `callback_url` - The URL custom URL path which CAS uses to call back to the service. Defaults to `/users/auth/cas/callback`. +* `logout_url` - The URL to use to logout a user. Defaults to `'/logout'`. +* `login_url` - Defines the URL used to prompt users for their login information. Defaults to `/login` If no `host` is configured, the host application's domain will be used. +* `uid_field` - The user data attribute to use as your user's unique identifier. Defaults to `'user'` (which usually contains the user's login name). +* `ca_path` - Optional when `ssl` is `true`. Sets path of a CA certification directory. See [Net::HTTP][net_http] for more details. +* `disable_ssl_verification` - Optional when `ssl` is true. Disables verification. +* `on_single_sign_out` - Optional. Callback used when a [CAS 3.1 Single Sign Out][sso] + request is received. +* `fetch_raw_info` - Optional. Callback used to return additional "raw" user + info from other sources. + +```ruby +provider :cas, + fetch_raw_info: lambda { |strategy, options, ticket, user_info| + ExternalService.get(user_info[:user]).attributes + } +``` Configurable options for values returned by CAS: - * `uid_key` - The user ID data attribute to use as your user's unique identifier. Defaults to `'user'` (which usually contains the user's login name). - * `name_key` - The data attribute containing user first and last name. Defaults to `'name'`. - * `email_key` - The data attribute containing user email address. Defaults to `'email'`. - * `nickname_key` - The data attribute containing user's nickname. Defaults to `'user'`. - * `first_name_key` - The data attribute containing user first name. Defaults to `'first_name'`. - * `last_name_key` - The data attribute containing user last name. Defaults to `'last_name'`. - * `location_key` - The data attribute containing user location/address. Defaults to `'location'`. - * `image_key` - The data attribute containing user image/picture. Defaults to `'image'`. - * `phone_key` - The data attribute containing user contact phone number. Defaults to `'phone'`. +* `uid_key` - The user ID data attribute to use as your user's unique identifier. Defaults to `'user'` (which usually contains the user's login name). +* `name_key` - The data attribute containing user first and last name. Defaults to `'name'`. +* `email_key` - The data attribute containing user email address. Defaults to `'email'`. +* `nickname_key` - The data attribute containing user's nickname. Defaults to `'user'`. +* `first_name_key` - The data attribute containing user first name. Defaults to `'first_name'`. +* `last_name_key` - The data attribute containing user last name. Defaults to `'last_name'`. +* `location_key` - The data attribute containing user location/address. Defaults to `'location'`. +* `image_key` - The data attribute containing user image/picture. Defaults to `'image'`. +* `phone_key` - The data attribute containing user contact phone number. Defaults to `'phone'`. ## Migrating from OmniAuth 0.3 @@ -99,9 +100,9 @@ Your new settings should look similar to this: ```ruby provider :cas, - host: 'cas.example.com', - login_url: '/cas/login', - service_validate_url: '/cas/serviceValidate' + host: 'cas.example.com', + login_url: '/cas/login', + service_validate_url: '/cas/serviceValidate' ``` If you encounter problems wih SSL certificates you may want to set the `ca_path` parameter or activate `disable_ssl_verification` (not recommended). @@ -118,9 +119,9 @@ If you encounter problems wih SSL certificates you may want to set the `ca_path` Special thanks go out to the following people - * Phillip Aldridge (@iterateNZ) and JB Barth (@jbbarth) for helping out with Issue #3 - * Elber Ribeiro (@dynaum) for Ubuntu SSL configuration support - * @rbq for README updates and OmniAuth 0.3 migration guide +* Phillip Aldridge (@iterateNZ) and JB Barth (@jbbarth) for helping out with Issue #3 +* Elber Ribeiro (@dynaum) for Ubuntu SSL configuration support +* @rbq for README updates and OmniAuth 0.3 migration guide [old_omniauth_cas]: https://github.com/intridea/omniauth/blob/0-3-stable/oa-enterprise/lib/omniauth/strategies/cas.rb [document_up]: https://dlindahl.github.io/omniauth-cas/ diff --git a/lib/omniauth/cas/version.rb b/lib/omniauth/cas/version.rb index 1910c93..004beb7 100644 --- a/lib/omniauth/cas/version.rb +++ b/lib/omniauth/cas/version.rb @@ -1,5 +1,5 @@ module Omniauth module Cas - VERSION = '2.0.0' + VERSION = '2.0.1' end end