omniauth--omniauth/oa-enterprise

= 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.

== SAML

Use the SAML strategy as a middleware in your application:

    require 'omniauth/enterprise'
    use OmniAuth::Strategies::SAML, 
        :assertion_consumer_service_url => "consumer_service_url",
        :issuer                         => "issuer",
        :idp_sso_target_url             => "idp_sso_target_url",
        :idp_cert_fingerprint           => "E7:91:B2:E1:...",
        :name_identifier_format         => "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"

:assertion_consumer_service_url 
  The URL at which the SAML assertion should be received. 

:issuer
  The name of your application. Some identity providers might need this to establish the 
  identity of the service provider requesting the login.

:idp_sso_target_url
  The URL to which the authentication request should be sent. This would be on the identity provider.

:idp_cert_fingerprint
  The certificate fingerprint, e.g. "90:CC:16:F0:8D:A6:D1:C6:BB:27:2D:BA:93:80:1A:1F:16:8E:4E:08".
  This is provided from the identity provider when setting up the relationship.

:name_identifier_format
  Describes the format of the username required by this application. 
  If you need the email address, use "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress". 
  See http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf section 8.3 for 
  other options. Note that the identity provider might not support all options.  


== 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