制定 SAML 2.0 身份验证策略
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.
Add this gem to your application's Gemfile:
gem "devise_saml_authenticatable"And then execute:
$ bundleFollow the normal devise installation process. The controller filters and helpers are unchanged from normal devise usage.
In app/models/.rb set the :saml_authenticatable strategy.
In the example the model is user.rb:
…There are two ways to map SAML attributes to User attributes:
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.
Create a YAML file (config/attribute-map.yml) that maps SAML attributes with your model's fields:
# 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"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.
# config/initializers/devise.rb
Devise.setup do |config|
...
# ==> Configuration for :saml_authenticatable
config.saml_attribute_map_resolver = "MyAttributeMapResolver"
end # 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
endIf 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.
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.
If you don't have an identity provider and you would like to test the authentication against your app, there are some options:
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 support is included by immediately terminating the local session and then redirecting to the IdP.
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.
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.
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.
git checkout -b my-new-feature)git commit -am 'Added some feature')bundle exec rspec)git push origin my-new-feature)暂无开放 Issues,或尚未同步最近议题。