Custom omniauth provider configurations

These are user-provided configurations that have been reported to work.

Please report successful configurations and probably share a few insights or provide warnings for common errors or pitfalls.

You can use the following template:

## Foo Auth Solution
Gem name: `omniauth-foo`
Configuration example:
```yaml
- { name: 'foo', ...}
```
Common errors/pitfalls:
* ...

Examples

##Non-Working PAM Configuration Authentication via PAM isn't officially supported (https://github.com/gitlabhq/gitlabhq/issues/2126)

###Install Process

• Have the libpam0g-dev package installed
• Create the PAM module for rpam's use (http://rpam.rubyforge.org/): cp /etc/pam.d/login /etc/pam.d/rpam
• NB:The canonical omniauth-pam gem is horrendously out of date (not including the fix in https://github.com/nickcharlton/omniauth-pam/commit/eb58d8f95a2cc03156f908cf488ce3591e74c1cd)
• Add gem 'omniauth-pam', :git => 'git://github.com/nickcharlton/omniauth-pam.git' to Gemfile and do a bundle update
• NB: The rpam gem omniauth-pam includes is actually rpam-ruby19 - not the obsolete rpam gem
• NB:Adding PAM to the gitlab.yml with - { name: 'PAM' } won't work
• Add config.omniauth :PAM to the config/initalizers/devise.rb file
• The link to use PAM will now appear on the login page

For some reason all providers are expected to accept app_id, and app_secret. A temporary fix for this to get PAM working. Use this in config/initalizers/devise.rb.

  Gitlab.config.omniauth.providers.each do |provider|
    if provider.has_key? 'app_id'
      case provider['args']
      when Array
        # An Array from the configuration will be expanded.
        config.omniauth provider['name'].to_sym, provider['app_id'], provider['app_secret'], *provider['args']
      when Hash
        # A Hash from the configuration will be passed as is.
        config.omniauth provider['name'].to_sym, provider['app_id'], provider['app_secret'], provider['args']
      else
        config.omniauth provider['name'].to_sym, provider['app_id'], provider['app_secret']
      end
    else
      case provider['args']
      when Array
        # An Array from the configuration will be expanded.
        config.omniauth provider['name'].to_sym, *provider['args']
      when Hash
        # A Hash from the configuration will be passed as is.
        config.omniauth provider['name'].to_sym, provider['args']
      else
        config.omniauth provider['name'].to_sym
      end
    end
  end

After this you will get much further. This helps alot if you are planning to use FreeRadius or TACACS+ or something else. It won't work well with local accounts.

But this is as far as I was able to get - https://github.com/canweriotnow/rpam-ruby19/issues/5 is a blocker.

The readme for rpam-ruby19 notes that "Users whould be aware that on systems using shadow passwords, authentication of users other than the current user will fail unless either a) the authenticating Ruby code is executed as root or, b) /sbin/unix_chkpwd is suid root (or sgid shadow)."

But their soluton (chmod 2755 /sbin/unix_chkpwd) doesn't work on a current Ubuntu system. Thus, the user executing unix_chkpwd via PAM can only check their own password and no other.

Working kerberos Configuration

Authentication via kerberos isn't officially supported.

Install Process

• Have the libkrb5-dev package installed

• Add gem 'omniauth-kerberos', '0.2.0' to Gemfile and do a bundle update (bundle install --without development test mysql --no-deployment)

• Adding kerberos to the gitlab.yml with - { name: 'kerberos' } is necessary, but insufficient : the next step is essential

• Add to the config/initializers/devise.rb file

  ```ruby
  config.omniauth :kerberos,
    :title => 'Super auth kerberos qui roxe du poney'
  ```
  

• Add icons for the new provider into the vendor/assets/images/authbuttons directory, you can find some more popular ones over here

• Restart GitLab

• The link to use kerberos backend will now appear on the login page :-)

Working CAS Configuration

Authentication via CAS isn't officially supported. You must satisfy the following requirements before this will work.

• Your CAS setup must be using CAS 2.0 protocol. omniauth-cas does not support SAML validation.
• Your CAS protocol must expose at a minimum: First name, Last name, UID, and email.

Install Process

• Add gem 'omniauth-cas' to Gemfile and do a bundle update (bundle install --without development test mysql --no-deployment)

• Add CAS to the gitlab.yml with - { name: 'cas' } under providers:

• Add to the config/initializers/devise.rb file

  ```ruby
  config.omniauth :cas, url: 'https://sso.example.com/', disable_ssl_verification: false
  ```
  

• Restart GitLab

Working Tequila Configuration

Authentication via Tequila isn't officially supported.

Install Process

• Add gem 'omniauth-tequila' to Gemfile and do a bundle update (bundle install --without development test postgres --path vendor/bundle --no-deployment)
• Add Tequila to the gitlab.yml with - { name: 'tequila' } under providers:
• Add to the config/initializers/devise.rb file ruby config.omniauth :tequila, { request_info: { name: 'displayname', email: 'email' } }
• Restart GitLab

Working Crowd Configuration

Authentication via Atlassian Crowd isn't officially supported. Before doing this, ensure you have the application configured from Crowd. The application name and password will be used.

Install Process

• Add gem 'omniauth-crowd' to Gemfile and do a bundle update (bundle install --without development test postgres --path vendor/bundle --no-deployment)
• Add to the config/initializers/devise.rb file ruby config.omniauth :crowd, :name => 'crowd', :crowd_server_url => 'http://<CROWD_SERVER_IP:PORT>/crowd', :application_name => "<APP_NAME>", :application_password => "<APP_PASSWORD>"
• Add to the app/controllers/omniauth_callbacks_controller.rb file ruby def crowd handle_omniauth end
• Restart GitLab

Working SAML Configuration

Only tested with SimpleSamlPhp as IdP. Some filters may be required at the IdP in order to provide an assertion that OmniAuth likes. This guide uses omniauth-saml to connect to OmniAuth, it has a dependency on ruby-saml.

Install Process

• Add gem 'omniauth-saml' to Gemfile and do a bundle update (bundle install --without development test postgres --path vendor/bundle --no-deployment)
• In the config/gitlab.yml file, enable omniauth, add - { name: 'saml' } under providers: and enable allow_single_sign_on and disable block_auto_created_users.
• Add the following to the end of theconfig/initializers/devise.rb file, just before the last occurrence of the word end.

config.omniauth :saml,
  assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
  issuer: "https://gitlab.example.com",
  idp_sso_target_url: "https://openidp.feide.no/simplesaml/saml2/idp/SSOService.php",
  idp_sso_target_url_runtime_params: {:original_request_param => :mapped_idp_param},
  idp_cert_fingerprint: "XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX",
  name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:email"

• Add to the app/controllers/omniauth_callbacks_controller.rb file, right under the class definition (from omniauth-saml#23):

skip_before_filter :verify_authenticity_token

• Restart GitLab
• Get your metadata from https://gitlab.example.com/users/auth/saml/metadata

Common pitfalls

• Careful what you set for name_identifier_format ; it defines how a user is identified..
• omniauth-saml is hardcoded to expect the following attributes, the rest is ignored: name, email (or mail), first_name (or firstname or firstName), last_name (or lastname, lastName).
• ruby-saml requires that every attribute has exactly one value. (fixed, but not released yet, nor incorporated in omniauth-saml)
• The username (namespace) is hardcoded in GitHub to be the local part of email, so [email protected] will have john.doe as username. Any uid or similar attribute is ignored.
• Single Sign Out does not work, as it is not supported by omniauth-saml (it is supported by ruby-saml, but not incorporated in omniauth-saml)