Skip to content

Commit 01586f5

Browse files
pbolingpboling
authored
Merge pull request #110 from omniauth/feat/docs-tls-verification
2 parents 97d99fc + 0105435 commit 01586f5

33 files changed

+179
-32
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ Please file a bug if you notice a violation of semantic versioning.
3333
- Support custom LDAP attributes mapping
3434
- Raise a distinct error when LDAP server is unreachable
3535
- Previously raised an invalid credentials authentication failure error, which is technically incorrect
36+
- Documentation of TLS verification options
3637

3738
### Changed
3839

‎README.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,50 @@ use OmniAuth::Strategies::LDAP,
8181

8282
All of the listed options are required, with the exception of `:title`, `:name_proc`, `:bind_dn`, and `:password`.
8383

84+
## TLS certificate verification
85+
86+
This gem enables TLS certificate verification by default when you use `encryption: "ssl"` (LDAPS / simple TLS) or `encryption: "tls"` (STARTTLS). We always pass `tls_options` to Net::LDAP based on `OpenSSL::SSL::SSLContext::DEFAULT_PARAMS`, which includes `verify_mode: OpenSSL::SSL::VERIFY_PEER` and sane defaults.
87+
88+
- Secure by default: you do not need to set anything extra to verify the LDAP server certificate.
89+
- To customize trust or ciphers, supply your own `tls_options`, which are merged over the safe defaults.
90+
- If you truly need to skip verification (not recommended), set `disable_verify_certificates: true`.
91+
92+
Examples:
93+
94+
```ruby
95+
# Verify server certs (default behavior)
96+
use OmniAuth::Strategies::LDAP,
97+
host: ENV["LDAP_HOST"],
98+
port: 636,
99+
encryption: "ssl", # or "tls"
100+
base: "dc=example,dc=com",
101+
uid: "uid"
102+
103+
# Use a private CA bundle and restrict protocol/ciphers
104+
use OmniAuth::Strategies::LDAP,
105+
host: ENV["LDAP_HOST"],
106+
port: 636,
107+
encryption: "ssl",
108+
base: "dc=example,dc=com",
109+
uid: "uid",
110+
tls_options: {
111+
ca_file: "/etc/ssl/private/my_org_ca.pem",
112+
ssl_version: "TLSv1_2",
113+
ciphers: ["TLS_AES_256_GCM_SHA384", "TLS_CHACHA20_POLY1305_SHA256"],
114+
}
115+
116+
# Opt out of verification (NOT recommended – use only in trusted test/dev scenarios)
117+
use OmniAuth::Strategies::LDAP,
118+
host: ENV["LDAP_HOST"],
119+
port: 636,
120+
encryption: "ssl",
121+
base: "dc=example,dc=com",
122+
uid: "uid",
123+
disable_verify_certificates: true
124+
```
125+
126+
Note: Net::LDAP historically defaulted to no certificate validation when `tls_options` were not provided. This library mitigates that by always providing secure `tls_options` unless you explicitly disable verification.
127+
84128
## 💡 Info you can shake a stick at
85129

86130
| Tokens to Remember | [![Gem name][⛳️name-img]][⛳️gem-name] [![Gem namespace][⛳️namespace-img]][⛳️gem-namespace] |

‎docs/OmniAuth.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ <h2>Defined Under Namespace</h2>
107107
</div>
108108

109109
<div id="footer">
110-
Generated on Thu Nov 6 02:24:32 2025 by
110+
Generated on Thu Nov 6 04:21:53 2025 by
111111
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
112112
0.9.37 (ruby-3.4.7).
113113
</div>

‎docs/OmniAuth/LDAP.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -135,7 +135,7 @@ <h2>
135135
</div>
136136

137137
<div id="footer">
138-
Generated on Thu Nov 6 02:24:32 2025 by
138+
Generated on Thu Nov 6 04:21:53 2025 by
139139
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
140140
0.9.37 (ruby-3.4.7).
141141
</div>

‎docs/OmniAuth/LDAP/Adaptor.html‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1273,7 +1273,9 @@ <h3 class="signature first" id="bind_as-instance_method">
12731273
173
12741274
174
12751275
175
1276-
176</pre>
1276+
176
1277+
177
1278+
178</pre>
12771279
</td>
12781280
<td>
12791281
<pre class="code"><span class="info file"># File 'lib/omniauth-ldap/adaptor.rb', line 131</span>
@@ -1284,6 +1286,8 @@ <h3 class="signature first" id="bind_as-instance_method">
12841286
<span class='ivar'>@last_password_policy_response</span> <span class='op'>=</span> <span class='kw'>nil</span>
12851287
<span class='ivar'>@connection</span><span class='period'>.</span><span class='id identifier rubyid_open'>open</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_me'>me</span><span class='op'>|</span>
12861288
<span class='id identifier rubyid_rs'>rs</span> <span class='op'>=</span> <span class='id identifier rubyid_me'>me</span><span class='period'>.</span><span class='id identifier rubyid_search'>search</span><span class='lparen'>(</span><span class='id identifier rubyid_args'>args</span><span class='rparen'>)</span>
1289+
<span class='id identifier rubyid_raise'>raise</span> <span class='const'><span class='object_link'><a href="Adaptor/ConnectionError.html" title="OmniAuth::LDAP::Adaptor::ConnectionError (class)">ConnectionError</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="#initialize-instance_method" title="OmniAuth::LDAP::Adaptor#initialize (method)">new</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>LDAP search operation failed</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span> <span class='kw'>unless</span> <span class='id identifier rubyid_rs'>rs</span>
1290+
12871291
<span class='kw'>if</span> <span class='id identifier rubyid_rs'>rs</span> <span class='op'>&amp;&amp;</span> <span class='id identifier rubyid_rs'>rs</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span>
12881292
<span class='id identifier rubyid_dn'>dn</span> <span class='op'>=</span> <span class='id identifier rubyid_rs'>rs</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span><span class='period'>.</span><span class='id identifier rubyid_dn'>dn</span>
12891293
<span class='kw'>if</span> <span class='id identifier rubyid_dn'>dn</span>
@@ -1334,7 +1338,7 @@ <h3 class="signature first" id="bind_as-instance_method">
13341338
</div>
13351339

13361340
<div id="footer">
1337-
Generated on Thu Nov 6 02:24:32 2025 by
1341+
Generated on Thu Nov 6 04:21:53 2025 by
13381342
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
13391343
0.9.37 (ruby-3.4.7).
13401344
</div>

‎docs/OmniAuth/LDAP/Adaptor/AuthenticationError.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@
114114
</div>
115115

116116
<div id="footer">
117-
Generated on Thu Nov 6 02:24:32 2025 by
117+
Generated on Thu Nov 6 04:21:53 2025 by
118118
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
119119
0.9.37 (ruby-3.4.7).
120120
</div>

‎docs/OmniAuth/LDAP/Adaptor/ConfigurationError.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@
114114
</div>
115115

116116
<div id="footer">
117-
Generated on Thu Nov 6 02:24:32 2025 by
117+
Generated on Thu Nov 6 04:21:53 2025 by
118118
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
119119
0.9.37 (ruby-3.4.7).
120120
</div>

‎docs/OmniAuth/LDAP/Adaptor/ConnectionError.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@
114114
</div>
115115

116116
<div id="footer">
117-
Generated on Thu Nov 6 02:24:32 2025 by
117+
Generated on Thu Nov 6 04:21:53 2025 by
118118
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
119119
0.9.37 (ruby-3.4.7).
120120
</div>

‎docs/OmniAuth/LDAP/Adaptor/LdapError.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@
114114
</div>
115115

116116
<div id="footer">
117-
Generated on Thu Nov 6 02:24:32 2025 by
117+
Generated on Thu Nov 6 04:21:53 2025 by
118118
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
119119
0.9.37 (ruby-3.4.7).
120120
</div>

‎docs/OmniAuth/LDAP/Version.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ <h2>
111111
</div>
112112

113113
<div id="footer">
114-
Generated on Thu Nov 6 02:24:32 2025 by
114+
Generated on Thu Nov 6 04:21:53 2025 by
115115
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
116116
0.9.37 (ruby-3.4.7).
117117
</div>

0 commit comments

Comments
 (0)