百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
D

devise_saml_authenticatable

> 编程语言
开源

制定 SAML 2.0 身份验证策略

301 stars0 点赞1 次浏览
访问官网GitHub

工具介绍

制定 SAML 2.0 身份验证策略

DeviseSamlAuthenticatable

Devise Saml Authenticatable is a Single-Sign-On authentication strategy for devise that relies on SAML. It uses ruby-saml to handle all SAML-related stuff.

[!WARNING] The master branch now represents v2.x of this gem, which is still unreleased. See the 1.x branch README for details about that version.

Installation

Add this gem to your application's Gemfile:

gem "devise_saml_authenticatable"

And then execute:

$ bundle

Usage

Follow the normal devise installation process. The controller filters and helpers are unchanged from normal devise usage.

Configuring Models

In app/models/.rb set the :saml_authenticatable strategy.

In the example the model is user.rb:

…

Attributes

There are two ways to map SAML attributes to User attributes:

  • initializer
  • config file

The attribute mappings are very dependent on the way the IdP encodes the attributes. In these examples the attributes are given in URN style. Other IdPs might provide them as OID's, or by other means.

You are now ready to test it against an IdP.

When the user visits /users/saml/sign_in they will be redirected to the login page of the IdP.

Upon successful login the user is redirected to the Devise user_root_path.

Attribute map config file

Create a YAML file (config/attribute-map.yml) that maps SAML attributes with your model's fields:

yaml
  # attribute-map.yml

  "urn:mace:dir:attribute-def:uid": "user_name"
  "urn:mace:dir:attribute-def:email": "email"
  "urn:mace:dir:attribute-def:name": "last_name"
  "urn:mace:dir:attribute-def:givenName": "name"
Attribute map initializer

In config/initializers/devise.rb (see above), add an attribute map resolver. The resolver gets the SAML response from the IdP so it can decide which attribute map to load. If you only have one IdP, you can use the config file above, or just return a single hash.

ruby
  # config/initializers/devise.rb
  Devise.setup do |config|
    ...
    # ==> Configuration for :saml_authenticatable

    config.saml_attribute_map_resolver = "MyAttributeMapResolver"
  end
ruby
  # app/lib/my_attribute_map_resolver
  class MyAttributeMapResolver  "user_name",
          "urn:mace:dir:attribute-def:email" => "email",
          "urn:mace:dir:attribute-def:name" => "last_name",
          "urn:mace:dir:attribute-def:givenName" => "name",
        }
      end
    end
  end

If you are mapping authorisation groups or any other array of values as some providers render (ie: Okta), be aware of ruby-saml's single_value_compatibility.

IdP Settings Adapter

Implementing a custom settings adapter allows you to support multiple Identity Providers, and dynamic application domains with the request object.

You can implement an adapter class with a #settings method. It must take two arguments (idp_entity_id, request) and return a hash of settings for the corresponding IdP. The config.idp_settings_adapter then must be set to point to your adapter in config/initializers/devise.rb. The implementation of the adapter is up to you. A simple example may look like this:

…

Settings specified in the adapter will override settings in config/initializers/devise.rb. This is useful for establishing common settings or defaults across all IdPs.

Detecting the entity ID passed to the settings method is done by config.idp_entity_id_reader.

By default this will find the Issuer in the SAML request.

You can support more use cases by writing your own and implementing the .entity_id method.

If you use encrypted assertions, your entity ID reader will need to understand how to decrypt the response from each of the possible IdPs.

Identity Provider

If you don't have an identity provider and you would like to test the authentication against your app, there are some options:

  1. Use ruby-saml-idp. You can add your own logic to your IdP, or you can also set it up as a dummy IdP that always sends a valid authentication response to your app.
  2. Use an online service that can act as an IdP. OneLogin, Salesforce, Okta and some others provide you with this functionality.
  3. Install your own IdP.

There are numerous IdPs that support SAML 2.0, there are proprietary (like Microsoft ADFS 2.0 or Ping federate) and there are also open source solutions like Shibboleth and SimpleSAMLphp.

SimpleSAMLphp was my choice for development since it is a production-ready SAML solution, that is also really easy to install, configure and use.

Logout

Logout support is included by immediately terminating the local session and then redirecting to the IdP.

Logout Request

Logout requests from the IDP are supported by the idp_sign_out endpoint. Directing logout requests to users/saml/idp_sign_out will log out the respective user by invalidating their current sessions.

To disable this feature, set saml_session_index_key to nil.

Signing and Encrypting Authentication Requests and Assertions

ruby-saml 1.0.0 supports signature and decrypt. The only requirement is to set the public certificate and the private key. For more information, see the ruby-saml documentation.

If you have multiple IdPs, the certificate and private key must be in the shared settings in config/initializers/devise.rb.

Thanks

The continued maintenance of this gem could not have been possible without the hard work of Adam Stegman and Mitch Lindsay. Thank you guys for keeping this project alive.

Thanks to all other contributors that have also helped us make this software better.

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Run the tests (bundle exec rspec)
  5. Push to the branch (git push origin my-new-feature)
  6. Create new Pull Request

Issues· 51 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Ruby

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月18日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言