Skip to content

Commit b996929

Browse files
ococ
committed
Update README.md
WARNING!
1 parent 5ffd0f0 commit b996929

File tree

1 file changed

+4
-122
lines changed

1 file changed

+4
-122
lines changed

‎README.md

Lines changed: 4 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -1,126 +1,8 @@
1-
# Ruby SAML [![Build Status](https://secure.travis-ci.org/onelogin/ruby-saml.png)](http://travis-ci.org/onelogin/ruby-saml)
1+
# IMPORTANT!
22

3-
The Ruby SAML library is for implementing the client side of a SAML authorization, i.e. it provides a means for managing authorization initialization and confirmation requests from identity providers.
3+
Here be dragons!
44

5-
SAML authorization is a two step process and you are expected to implement support for both.
5+
This repo is severely out to date.
66

7-
## The initialization phase
7+
All significant code has already been merged into the onelogin/ruby-saml project. This is just kept for reference since it's used in a couple of projects.
88

9-
This is the first request you will get from the identity provider. It will hit your application at a specific URL (that you've announced as being your SAML initialization point). The response to this initialization, is a redirect back to the identity provider, which can look something like this (ignore the saml_settings method call for now):
10-
11-
```ruby
12-
def init
13-
request = Onelogin::Saml::Authrequest.new
14-
redirect_to(request.create(saml_settings))
15-
end
16-
```
17-
18-
Once you've redirected back to the identity provider, it will ensure that the user has been authorized and redirect back to your application for final consumption, this is can look something like this (the authorize_success and authorize_failure methods are specific to your application):
19-
20-
```ruby
21-
def consume
22-
response = Onelogin::Saml::Response.new(params[:SAMLResponse])
23-
response.settings = saml_settings
24-
25-
if response.is_valid? && user = current_account.users.find_by_email(response.name_id)
26-
authorize_success(user)
27-
else
28-
authorize_failure(user)
29-
end
30-
end
31-
```
32-
33-
In the above there are a few assumptions in place, one being that the response.name_id is an email address. This is all handled with how you specify the settings that are in play via the saml_settings method. That could be implemented along the lines of this:
34-
35-
```ruby
36-
def saml_settings
37-
settings = Onelogin::Saml::Settings.new
38-
39-
settings.assertion_consumer_service_url = "http://#{request.host}/saml/finalize"
40-
settings.issuer = request.host
41-
settings.idp_sso_target_url = "https://app.onelogin.com/saml/signon/#{OneLoginAppId}"
42-
settings.idp_cert_fingerprint = OneLoginAppCertFingerPrint
43-
settings.name_identifier_format = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
44-
# Optional for most SAML IdPs
45-
settings.authn_context = "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
46-
47-
settings
48-
end
49-
```
50-
51-
What's left at this point, is to wrap it all up in a controller and point the initialization and consumption URLs in OneLogin at that. A full controller example could look like this:
52-
53-
```ruby
54-
# This controller expects you to use the URLs /saml/init and /saml/consume in your OneLogin application.
55-
class SamlController < ApplicationController
56-
def init
57-
request = Onelogin::Saml::Authrequest.new
58-
redirect_to(request.create(saml_settings))
59-
end
60-
61-
def consume
62-
response = Onelogin::Saml::Response.new(params[:SAMLResponse])
63-
response.settings = saml_settings
64-
65-
if response.is_valid? && user = current_account.users.find_by_email(response.name_id)
66-
authorize_success(user)
67-
else
68-
authorize_failure(user)
69-
end
70-
end
71-
72-
private
73-
74-
def saml_settings
75-
settings = Onelogin::Saml::Settings.new
76-
77-
settings.assertion_consumer_service_url = "http://#{request.host}/saml/consume"
78-
settings.issuer = request.host
79-
settings.idp_sso_target_url = "https://app.onelogin.com/saml/signon/#{OneLoginAppId}"
80-
settings.idp_cert_fingerprint = OneLoginAppCertFingerPrint
81-
settings.name_identifier_format = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
82-
# Optional for most SAML IdPs
83-
settings.authn_context = "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
84-
85-
settings
86-
end
87-
end
88-
```
89-
90-
If are using saml:AttributeStatement to transfare metadata, like the user name, you can access all the attributes through response.attributes. It
91-
contains all the saml:AttributeStatement with its 'Name' as a indifferent key and the one saml:AttributeValue as value.
92-
93-
response = Onelogin::Saml::Response.new(params[:SAMLResponse])
94-
response.settings = saml_settings
95-
96-
response.attributes[:username]
97-
98-
## Service Provider Metadata
99-
100-
To form a trusted pair relationship with the IdP, the SP (you) need to provide metadata XML
101-
to the IdP for various good reasons. (Caching, certificate lookups, relying party permissions, etc)
102-
103-
The class Onelogin::Saml::Metdata takes care of this by reading the Settings and returning XML. All
104-
you have to do is add a controller to return the data, then give this URL to the IdP administrator.
105-
The metdata will be polled by the IdP every few minutes, so updating your settings should propagate
106-
to the IdP settings.
107-
108-
```ruby
109-
class SamlController < ApplicationController
110-
# ... the rest of your controller definitions ...
111-
def metadata
112-
settings = Account.get_saml_settings
113-
meta = Onelogin::Saml::Metadata.new
114-
render :xml => meta.generate(settings)
115-
end
116-
end
117-
```
118-
119-
## Note on Patches/Pull Requests
120-
121-
* Fork the project.
122-
* Make your feature addition or bug fix.
123-
* Add tests for it. This is important so I don't break it in a
124-
future version unintentionally.
125-
* Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
126-
* Send me a pull request. Bonus points for topic branches.

0 commit comments

Comments
 (0)