Skip to content

Commit c103e68

Browse files
committed
JAVA-2717: Expand on Windows limitations for GSSAPI authentication in the reference documentation,
including links to relevant Oracle JDK issues and Stack Overflow question. Also add missing documentation of GSSAPI mechanism properties in the synchronous driver reference documentation
1 parent 91798da commit c103e68

File tree

2 files changed

+46
-6
lines changed

2 files changed

+46
-6
lines changed

docs/reference/content/driver-async/tutorials/authentication.md

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -203,12 +203,6 @@ MongoClient mongoClient = MongoClients.create(new ConnectionString(
203203
{{% note %}}
204204
The method refers to the `GSSAPI` authentication mechanism instead of `Kerberos` because technically the driver is authenticating via the
205205
[GSSAPI](https://tools.ietf.org/html/rfc4752) SASL mechanism.
206-
207-
The `GSSAPI` authentication mechanism is supported only in the following environments:
208-
209-
* Linux: Java 6 and above
210-
* Windows: Java 7 and above with [SSPI](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380493)
211-
* OS X: Java 7 and above
212206
{{% /note %}}
213207

214208
To successfully authenticate via Kerberos, the application typically
@@ -245,6 +239,16 @@ Or via the `ConnectionString`:
245239
mongodb://username%40MYREALM.com@myserver/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:othername
246240
```
247241

242+
{{% note %}}
243+
On Windows, Oracle's JRE uses [LSA](https://msdn.microsoft.com/en-us/library/windows/desktop/aa378326.aspx) rather than
244+
[SSPI](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380493.aspx) in its implementation of GSSAPI, which limits
245+
interoperability with Windows Active Directory and in particular the ability to implement single sign-on.
246+
247+
- [JDK-8054026](https://bugs.openjdk.java.net/browse/JDK-8054026)
248+
- [JDK-6722928](https://bugs.openjdk.java.net/browse/JDK-6722928)
249+
- [SO 23427343](https://stackoverflow.com/questions/23427343/cannot-retrieve-tgt-despite-allowtgtsessionkey-registry-entry)
250+
{{% /note %}}
251+
248252

249253
## LDAP (PLAIN)
250254

docs/reference/content/driver/tutorials/authentication.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,42 @@ java.security.krb5.realm=MYREALM.ME
180180
java.security.krb5.kdc=mykdc.myrealm.me
181181
```
182182

183+
Depending on the Kerberos setup, additional property specifications may be required, either via the application code or, in some cases, the [withMechanismProperty()]({{<apiref "com/mongodb/MongoCredential.html#withMechanismProperty-java.lang.String-T-">}}) method of the `MongoCredential` instance:
184+
185+
- **[`SERVICE_NAME`]({{< apiref "com/mongodb/MongoCredential.html#SERVICE_NAME_KEY" >}})**
186+
187+
188+
- **[`CANONICALIZE_HOST_NAME`]({{< apiref "com/mongodb/MongoCredential.html#CANONICALIZE_HOST_NAME_KEY" >}})**
189+
190+
191+
- **[`JAVA_SUBJECT`]({{< apiref "com/mongodb/MongoCredential.html#JAVA_SUBJECT_KEY" >}})**
192+
193+
- **[`JAVA_SASL_CLIENT_PROPERTIES`]({{< apiref "com/mongodb/MongoCredential.html#JAVA_SASL_CLIENT_PROPERTIES_KEY" >}})**
194+
195+
For example, to specify the `SERVICE_NAME` property via the `MongoCredential` object:
196+
197+
198+
```java
199+
credential = credential.withMechanismProperty(MongoCredential.SERVICE_NAME_KEY, "othername");
200+
```
201+
202+
Or via the `ConnectionString`:
203+
204+
```
205+
mongodb://username%40MYREALM.com@myserver/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:othername
206+
```
207+
208+
{{% note %}}
209+
On Windows, Oracle's JRE uses [LSA](https://msdn.microsoft.com/en-us/library/windows/desktop/aa378326.aspx) rather than
210+
[SSPI](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380493.aspx) in its implementation of GSSAPI, which limits
211+
interoperability with Windows Active Directory and in particular the ability to implement single sign-on.
212+
213+
- [JDK-8054026](https://bugs.openjdk.java.net/browse/JDK-8054026)
214+
- [JDK-6722928](https://bugs.openjdk.java.net/browse/JDK-6722928)
215+
- [SO 23427343](https://stackoverflow.com/questions/23427343/cannot-retrieve-tgt-despite-allowtgtsessionkey-registry-entry)
216+
{{% /note %}}
217+
218+
183219
## LDAP (PLAIN)
184220

185221
[MongoDB Enterprise](http://www.mongodb.com/products/mongodb-enterprise) supports proxy authentication through a Lightweight Directory Access Protocol (LDAP) service. To create a credential of type [LDAP]({{<apiref "core/authentication/#ldap-proxy-authority-authentication">}}) use the

0 commit comments

Comments
 (0)