🎲 omniauth-dice is an internal authentication strategy that authenticates via a user's X509 certificate DN
Ruby
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
certs
config
lib
spec
.codeclimate.yml
.coveralls.yml
.gitignore
.rubocop.yml
.rubocop_todo.yml
.travis.yml
.yardopts
Gemfile
LICENSE.txt
README.md
Rakefile
omniauth-dice.gemspec

README.md

Omniauth::Dice Gem Version

Travis CI Dependency Status Test Coverage Code Climate Inline docs

DN Interoperable Conversion Expert

omniauth-dice is an internal authentication strategy that authenticates via a user's X509 certificate DN string to an Enterprise CAS server via REST.

Installation

Add this line to your application's Gemfile:

gem 'omniauth-dice', '~> 0.2.3'

And then execute:

$ bundle

Or install it yourself with:

$ gem install omniauth-dice

Usage

Setup your OmniAuth::Dice builder like so:

Ruby on Rails (3.0+):

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :dice, {
    cas_server:          'https://example.org',
    authentication_path: '/users',
    primary_visa:        'EQUESTRIA',
    dnc_options: { :transformation => 'downcase' }, # see `dnc` gem for all options
    ssl_config: {
        ca_file:     '/path/to/your/CA.all.pem',
        client_cert: '/path/to/server/cert.pem',
        client_key:  '/path/to/server/key.np.key'
    }
  }
end

Rack / Sinatra:

use OmniAuth::Strategies::Dice, {
  cas_server:          'https://example.org:3000',
  authentication_path: '/dn',
  format_header:       'application/xml', # default is 'application/json'
  format:              'xml', # default is 'json'
  primary_visa:        'EQUESTRIA', # Optional
  dnc_options: { transformation: 'downcase' }, # see `dnc` gem for all options
  ssl_config: {
      ca_file:     '/path/to/your/CA.all.pem',
      client_cert: '/path/to/server/cert.pem',
      client_key:  '/path/to/server/key.np.key'
  }
}

Full configuration options are as follows:

  • cas_server [String] Required base URL for CAS server
  • authentication_path [String] URL path for endpoint, e.g. '/users'
  • custom_callback_url [String] Use a fully custom URL for callback endpoint
    This option overrides the use_callback_url option setting!
  • use_callback_url [Boolean] Use full URL vs path for callback endpoint
    This is especially useful if your app runs as a sub-URI example.org/app_name
  • return_field [String] Optional path to append after DN string
  • ssl_config [Hash] Configuration hash for Faraday SSL options
  • format_header [String] 'application/json', 'application/xml', etc
    Defaults to 'application/json'
  • format [String] 'json', 'xml', etc.
    Defaults to 'json'
  • client_cert_header [String] ENV string to access user's X509 cert
    Defaults to 'HTTP_SSL_CLIENT_CERT'
  • subject_dn_header [String] ENV string to access user's subject_dn
    Defaults to 'HTTP_SSLC_LIENT_S_DN'
  • issuer_dn_header [String] ENV string to access user's issuer_dn
    Defaults to 'HTTP_SSL_CLIENT_I_DN'
  • name_format [Symbol] Format for auth_hash['info']['name']
    Defaults to attempting DN common name -> full name -> first & last name
    Valid options are: :cn, :full_name, :first_last_name to override

auth_hash Results

The session's omniauth['auth'] hash will resond with the following structure:

{
  "provider"=>"dice",
  "uid"=>"cn=steven haddox,ou=rails,ou=ruby,ou=a,o=developer,c=us",
  "info"=>{
    "dn"=>"cn=steven haddox,ou=rails,ou=ruby,ou=a,o=developer,c=us",
    "email"=>"steven.haddox@example.org",
    "name"=>"steven haddox",
    "primary_visa?"=>false,
    "likely_npe?"=>false
    # ...<other fields dynamically inserted>...
  },
  "extra"=>{
    "raw_info"=>{
      # ...parsed response from CAS server...
    }
  }
}

The provider, uid, info, and extra fields follow omniauth best practices but there are a few computed fields from omniauth-dice worth being aware of:

  • likely_npe?: [Boolean] This field tries to detect if the client
    certificate / DN comes from a non-person entity (e.g., server) or a person.
  • primary_visa?: [Boolean] If the CAS server responds with an array of
    visas, this attribute will indicate if a specific visa is present.
  • name: [String] Returns the client's name as configured or uses defaults.

SSL Client Certificate Notes

Faraday (the HTTP library used by OmniAuth) can accept certificate paths:

  client_cert: 'path/to/server/cert.pem',
  client_key:  'path/to/server/key.np.pem'

Or it also works with actual certificates (such as to pass a passphrase in):

  client_cert: File.read('path/to/server/cert.pem').to_cert,
  client_key:  OpenSSL::PKey::RSA.new(File.read('path/to/server/key.pem'), 'PASSW0RD')

Contributing

  1. Fork it ( https://github.com/[my-github-username]/omniauth-dice/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Add specs!
  4. Commit your changes (git commit -am 'Add some feature')
  5. Push to the branch (git push origin my-new-feature)
  6. Create a new Pull Request