omniauth--omniauth/oa-enterprise/README.rdoc

= OmniAuth::Enterprise

OmniAuth strategies for use in your intranet.

== Installation

To get just enterprise functionality:

    gem install oa-enterprise
    
For the full auth suite:

    gem install omniauth

== CAS

Use the CAS strategy as a middleware in your application:

    require 'omniauth/enterprise'
    
    use OmniAuth::Strategies::CAS, :server => 'http://cas.mycompany.com/cas'
    
Then simply direct users to '/auth/cas' to have them sign in via your company's CAS server.
See OmniAuth::Strategies::CAS::Configuration for more configuration options.

== LDAP

Use the LDAP strategy as a middleware in your application:

    require 'omniauth/enterprise'
    use OmniAuth::Strategies::LDAP, 
        :title => "My LDAP", 
        :host => '10.101.10.1',
        :port => 389,
        :method => :plain,
        :base => 'dc=intridea, dc=com',
        :uid => 'sAMAccountName',
        :name_proc => Proc.new {|name| name.gsub(/@.*$/,'')}
        :bind_dn => 'default_bind_dn'
        :password => 'password'

All of the listed options are required, with the exception of :name_proc, :bind_dn, and :password
Allowed values of :method are: :plain, :ssl, :tls.

:bind_dn and :password are used to perform the initial binding if user lookup is
needed. If the user lookup returns result, the DN attribute from the result set is used
to perform the final binding. This is needed only when the LDAP server requires 
DN to be used for binding and you may only want user to using email or username
in the login form.

:uid is the LDAP attribute name for the user name in the login form. typically
AD would be 'sAMAccountName' or 'UserPrincipalName', while OpenLDAP is 'uid'.
You can also use 'dn', if your user choose the put in the dn in the login form
(but usually is too long for user to remember or know).

:name_proc allows you to match the user name entered with the format of the
:uid attributes. For example, value of 'sAMAccountName' in AD contains only the
windows user name. If your user prefers use email to login, a name_proc as
above will trim the email string down to just the windows name. In summary,
:name_proc helps you to fill the gap between the authentication and user lookup
process.
 
:try_sasl and :sasl_mechanisms are optional. Use them to initialize a SASL
connection to server. Allowed values are 'DIGEST-MD5' and 'GSS-SPNEGO'. If you
are not familiar with these authentication methods, please just avoid them.

Direct users to '/auth/ldap' to have them authenticated via your
company's LDAP server.
    
== Multiple Strategies

If you're using multiple strategies together, use OmniAuth's Builder. That's
what it's there for:

    require 'omniauth/enterprise'
    require 'omniauth/oauth'  # for Campfire
    require 'openid/store/filesystem'
    
    use OmniAuth::Builder do
      provider :cas, :server => 'http://cas.mycompany.com/cas'
      provider :campfire
    end