🎲 omniauth-dice is an internal authentication strategy that authenticates via a user's X509 certificate DN
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


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.


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


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'

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:

  "uid"=>"cn=steven haddox,ou=rails,ou=ruby,ou=a,o=developer,c=us",
    "dn"=>"cn=steven haddox,ou=rails,ou=ruby,ou=a,o=developer,c=us",
    "name"=>"steven haddox",
    # ...<other fields dynamically inserted>...
      # ...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')


  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