README.md
# Omniauth::Dice [](http://badge.fury.io/rb/omniauth-dice)
[](https://travis-ci.org/stevenhaddox/omniauth-dice) [](https://gemnasium.com/stevenhaddox/omniauth-dice) [](https://codeclimate.com/github/stevenhaddox/omniauth-dice/coverage) [](https://codeclimate.com/github/stevenhaddox/omniauth-dice) [](http://inch-ci.org/github/stevenhaddox/omniauth-dice)
# **D**N **I**nteroperable **C**onversion **E**xpert
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+):
```ruby
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:
```ruby
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