1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
# Ruby SAML Migration Guide
## Updating from 1.12.x to 1.13.0 (NOT YET RELEASED)
Version `1.13.0` adds `settings.idp_sso_service_binding` and `settings.idp_slo_service_binding`, and
deprecates `settings.security[:embed_sign]`. If specified, new binding parameters will be used in place of `:embed_sign`
to determine how to handle SAML message signing (`HTTP-POST` embeds signature and `HTTP-Redirect` does not.)
In addition, the `IdpMetadataParser#parse`, `#parse_to_hash` and `#parse_to_array` methods now retrieve
`idp_sso_service_binding` and `idp_slo_service_binding`.
Lastly, for convenience you may now use the Symbol aliases `:post` and `:redirect` for any `settings.*_binding` parameter.
## Upgrading from 1.11.x to 1.12.0
Version `1.12.0` adds support for gcm algorithm and
change/adds specific error messages for signature validations
`idp_sso_target_url` and `idp_slo_target_url` attributes of the Settings class deprecated
in favor of `idp_sso_service_url` and `idp_slo_service_url`. The `IdpMetadataParser#parse`,
`#parse_to_hash` and `#parse_to_array` methods now retrieve SSO URL and SLO URL endpoints with
`idp_sso_service_url` and `idp_slo_service_url` (previously `idp_sso_target_url` and
`idp_slo_target_url` respectively).
## Upgrading from 1.10.x to 1.11.0
Version `1.11.0` deprecates the use of `settings.issuer` in favour of `settings.sp_entity_id`.
There are two new security settings: `settings.security[:check_idp_cert_expiration]` and
`settings.security[:check_sp_cert_expiration]` (both false by default) that check if the
IdP or SP X.509 certificate has expired, respectively.
Version `1.10.2` includes the `valid_until` attribute in parsed IdP metadata.
Version `1.10.1` improves Ruby 1.8.7 support.
## Upgrading from 1.9.0 to 1.10.0
Version `1.10.0` improves IdpMetadataParser to allow parse multiple IDPSSODescriptor,
Add Subject support on AuthNRequest to allow SPs provide info to the IdP about the user
to be authenticated and updates the format_cert method to accept certs with /\x0d/
## Upgrading from 1.8.0 to 1.9.0
Version `1.9.0` better supports Ruby 2.4+ and JRuby 9.2.0.0. `Settings` initialization
now has a second parameter, `keep_security_settings` (default: false), which saves security
settings attributes that are not explicitly overridden, if set to true.
## Upgrading from 1.7.x to 1.8.0
On Version `1.8.0`, creating AuthRequests/LogoutRequests/LogoutResponses with nil RelayState
param will not generate a URL with an empty RelayState parameter anymore. It also changes
the invalid audience error message.
## Upgrading from 1.6.0 to 1.7.0
Version `1.7.0` is a recommended update for all Ruby SAML users as it includes a fix for
the [CVE-2017-11428](https://www.cvedetails.com/cve/CVE-2017-11428/) vulnerability.
## Upgrading from 1.5.0 to 1.6.0
Version `1.6.0` changes the preferred way to construct instances of `Logoutresponse` and
`SloLogoutrequest`. Previously the _SAMLResponse_, _RelayState_, and _SigAlg_ parameters
of these message types were provided via the constructor's `options[:get_params]` parameter.
Unfortunately this can result in incompatibility with other SAML implementations; signatures
are specified to be computed based on the _sender's_ URI-encoding of the message, which can
differ from that of Ruby SAML. In particular, Ruby SAML's URI-encoding does not match that
of Microsoft ADFS, so messages from ADFS can fail signature validation.
The new preferred way to provide _SAMLResponse_, _RelayState_, and _SigAlg_ is via the
`options[:raw_get_params]` parameter. For example:
```ruby
# In this example `query_params` is assumed to contain decoded query parameters,
# and `raw_query_params` is assumed to contain encoded query parameters as sent by the IDP.
settings = {
settings.security[:signature_method] = XMLSecurity::Document::RSA_SHA1
settings.soft = false
}
options = {
get_params: {
"Signature" => query_params["Signature"],
},
raw_get_params: {
"SAMLRequest" => raw_query_params["SAMLRequest"],
"SigAlg" => raw_query_params["SigAlg"],
"RelayState" => raw_query_params["RelayState"],
},
}
slo_logout_request = OneLogin::RubySaml::SloLogoutrequest.new(query_params["SAMLRequest"], settings, options)
raise "Invalid Logout Request" unless slo_logout_request.is_valid?
```
The old form is still supported for backward compatibility, but all Ruby SAML users
should prefer `options[:raw_get_params]` where possible to ensure compatibility with
other SAML implementations.
## Upgrading from 1.4.2 to 1.4.3
Version `1.4.3` introduces Recipient validation of SubjectConfirmation elements.
The 'Recipient' value is compared with the settings.assertion_consumer_service_url
value.
If you want to skip that validation, add the :skip_recipient_check option to the
initialize method of the Response object.
Parsing metadata that contains more than one certificate will propagate the
idp_cert_multi property rather than idp_cert. See [signature validation
section](#signature-validation) for details.
## Upgrading from 1.3.x to 1.4.x
Version `1.4.0` is a recommended update for all Ruby SAML users as it includes security improvements.
## Upgrading from 1.2.x to 1.3.x
Version `1.3.0` is a recommended update for all Ruby SAML users as it includes security fixes.
It adds security improvements in order to prevent Signature wrapping attacks.
[CVE-2016-5697](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-5697)
## Upgrading from 1.1.x to 1.2.x
Version `1.2` adds IDP metadata parsing improvements, uuid deprecation in favour of SecureRandom,
refactor error handling and some minor improvements.
There is no compatibility issue detected.
For more details, please review [CHANGELOG.md](CHANGELOG.md).
## Upgrading from 1.0.x to 1.1.x
Version `1.1` adds some improvements on signature validation and solves some namespace conflicts.
## Upgrading from 0.9.x to 1.0.x
Version `1.0` is a recommended update for all Ruby SAML users as it includes security fixes.
Version `1.0` adds security improvements like entity expansion limitation, more SAML message validations, and other important improvements like decrypt support.
### Important Changes
Please note the `get_idp_metadata` method raises an exception when it is not able to fetch the idp metadata, so review your integration if you are using this functionality.
## Upgrading from 0.8.x to 0.9.x
Version `0.9` adds many new features and improvements.
## Upgrading from 0.7.x to 0.8.x
Version `0.8.x` changes the namespace of the gem from `OneLogin::Saml` to `OneLogin::RubySaml`. Please update your implementations of the gem accordingly.
|
