Skip to content

Commit 6c3ceba

Browse files
rustagirrustagir
committed
DOCSP-39405: kotlin v5.1 content
1 parent f78b102 commit 6c3ceba

12 files changed

+291
-7
lines changed

‎examples/gradle.properties

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
11
kotlin.code.style=official
2-
kotlin_mongodb_version=4.11.0
2+
kotlin_mongodb_version=5.1.0

‎examples/src/test/kotlin/EnterpriseAuthTest.kt

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,13 @@ import com.mongodb.ConnectionString
33
import com.mongodb.KerberosSubjectProvider
44
import com.mongodb.MongoClientSettings
55
import com.mongodb.MongoCredential
6+
import com.mongodb.MongoCredential.OidcCallbackResult
67
import com.mongodb.ServerAddress
78
import com.mongodb.kotlin.client.coroutine.MongoClient
89
import kotlinx.coroutines.runBlocking
10+
import java.nio.file.Files
11+
import java.nio.file.Paths
12+
import javax.naming.Context
913
import javax.security.auth.Subject
1014
import javax.security.auth.login.LoginContext
1115
import kotlin.test.Ignore
@@ -113,6 +117,88 @@ internal class EnterpriseAuthTest {
113117
val mongoClient = MongoClient.create(connectionString)
114118
// :snippet-end:
115119
}
120+
121+
fun oidcAzureConnectionString() = runBlocking {
122+
// :snippet-start: oidc-azure-connection-string
123+
val connectionString = ConnectionString(
124+
"mongodb://<username>@<hostname>:<port>/?" +
125+
"?authMechanism=MONGODB-OIDC" +
126+
"&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<percent-encoded audience>")
127+
val mongoClient = MongoClient.create(connectionString)
128+
// :snippet-end:
129+
}
130+
131+
fun oidcAzureCredential() = runBlocking {
132+
// :snippet-start: oidc-azure-credential
133+
val credential = MongoCredential.createOidcCredential("<username>")
134+
.withMechanismProperty("ENVIRONMENT", "azure")
135+
.withMechanismProperty("TOKEN_RESOURCE", "<audience>")
136+
137+
val mongoClient = MongoClient.create(
138+
MongoClientSettings.builder()
139+
.applyToClusterSettings { builder ->
140+
builder.hosts(listOf(ServerAddress("<hostname>", PORT)))
141+
}
142+
.credential(credential)
143+
.build())
144+
// :snippet-end:
145+
}
146+
147+
fun oidcGCPConnectionString() = runBlocking {
148+
// :snippet-start: oidc-gcp-connection-string
149+
val connectionString = ConnectionString(
150+
"mongodb://<hostname>:<port>/?" +
151+
"authMechanism=MONGODB-OIDC" +
152+
"&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<percent-encoded audience>")
153+
val mongoClient = MongoClient.create(connectionString)
154+
// :snippet-end:
155+
}
156+
157+
fun oidcGCPCredential() = runBlocking {
158+
// :snippet-start: oidc-gcp-credential
159+
val credential = MongoCredential.createOidcCredential("<username>")
160+
.withMechanismProperty("ENVIRONMENT", "gcp")
161+
.withMechanismProperty("TOKEN_RESOURCE", "<audience>")
162+
163+
val mongoClient = MongoClient.create(
164+
MongoClientSettings.builder()
165+
.applyToClusterSettings { builder ->
166+
builder.hosts(listOf(ServerAddress("<hostname>", PORT)))
167+
}
168+
.credential(credential)
169+
.build())
170+
// :snippet-end:
171+
}
172+
173+
fun oidcCallback() = runBlocking {
174+
// :snippet-start: oidc-callback
175+
val credential = MongoCredential.createOidcCredential(null)
176+
.withMechanismProperty("OIDC_CALLBACK") { Context context ->
177+
val accessToken = "..."
178+
OidcCallbackResult(accessToken)
179+
}
180+
// :snippet-end:
181+
}
182+
183+
184+
fun oidcCallbackFile() = runBlocking {
185+
// :snippet-start: oidc-callback-file
186+
val credential = MongoCredential.createOidcCredential(null)
187+
.withMechanismProperty("OIDC_CALLBACK") { Context context ->
188+
val accessToken = String(Files.readAllBytes(Paths.get("access-token.dat")))
189+
OidcCallbackResult(accessToken)
190+
}
191+
192+
val mongoClient = MongoClient.create(
193+
MongoClientSettings.builder()
194+
.applyToClusterSettings { builder ->
195+
builder.hosts(listOf(ServerAddress("<hostname>", PORT)))
196+
}
197+
.credential(credential)
198+
.build()
199+
)
200+
// :snippet-end:
201+
}
116202
}
117203
// :replace-end:
118204

‎source/examples/generated/EnterpriseAuthTest.snippet.oidc-azure-connection-string.kt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
val connectionString = ConnectionString(
2+
"mongodb://<username>@<hostname>:<port>/?" +
3+
"?authMechanism=MONGODB-OIDC" +
4+
"&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<percent-encoded audience>")
5+
val mongoClient = MongoClient.create(connectionString)

‎source/examples/generated/EnterpriseAuthTest.snippet.oidc-azure-credential.kt

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
val credential = MongoCredential.createOidcCredential("<username>")
2+
.withMechanismProperty("ENVIRONMENT", "azure")
3+
.withMechanismProperty("TOKEN_RESOURCE", "<audience>")
4+
5+
val mongoClient = MongoClient.create(
6+
MongoClientSettings.builder()
7+
.applyToClusterSettings { builder ->
8+
builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
9+
}
10+
.credential(credential)
11+
.build())

‎source/examples/generated/EnterpriseAuthTest.snippet.oidc-callback-file.kt

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
val credential = MongoCredential.createOidcCredential(null)
2+
.withMechanismProperty("OIDC_CALLBACK") { Context context ->
3+
val accessToken = String(Files.readAllBytes(Paths.get("access-token.dat")))
4+
OidcCallbackResult(accessToken)
5+
}
6+
7+
val mongoClient = MongoClient.create(
8+
MongoClientSettings.builder()
9+
.applyToClusterSettings { builder ->
10+
builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
11+
}
12+
.credential(credential)
13+
.build()
14+
)

‎source/examples/generated/EnterpriseAuthTest.snippet.oidc-callback.kt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
val credential = MongoCredential.createOidcCredential(null)
2+
.withMechanismProperty("OIDC_CALLBACK") { Context context ->
3+
val accessToken = "..."
4+
OidcCallbackResult(accessToken)
5+
}

‎source/examples/generated/EnterpriseAuthTest.snippet.oidc-gcp-connection-string.kt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
val connectionString = ConnectionString(
2+
"mongodb://<hostname>:<port>/?" +
3+
"authMechanism=MONGODB-OIDC" +
4+
"&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<percent-encoded audience>")
5+
val mongoClient = MongoClient.create(connectionString)

‎source/examples/generated/EnterpriseAuthTest.snippet.oidc-gcp-credential.kt

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
val credential = MongoCredential.createOidcCredential("<username>")
2+
.withMechanismProperty("ENVIRONMENT", "gcp")
3+
.withMechanismProperty("TOKEN_RESOURCE", "<audience>")
4+
5+
val mongoClient = MongoClient.create(
6+
MongoClientSettings.builder()
7+
.applyToClusterSettings { builder ->
8+
builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
9+
}
10+
.credential(credential)
11+
.build())

‎source/fundamentals/connection/connection-options.txt

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -261,6 +261,15 @@ parameters of the connection URI to specify the behavior of the client.
261261

262262
| **Default**: ``true``
263263

264+
* - **serverMonitoringMode**
265+
- string
266+
- Specifies which server monitoring protocol the driver uses. When set to
267+
``auto``, the monitoring mode is determined by the environment in which
268+
the driver is running. The driver uses ``poll`` mode in function-as-a-service
269+
(FaaS) environments and ``stream`` mode in other environments.
270+
271+
| **Default**: ``auto``
272+
264273
* - **uuidRepresentation**
265274
- string
266275
- Specifies the UUID representation to use for read and write

‎source/fundamentals/connection/mongoclientsettings.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -433,6 +433,9 @@ settings to modify the driver's behavior:
433433
* - ``minHeartbeatFrequency()``
434434
- Sets the minimum interval for server monitoring checks.
435435

436+
* - ``serverMonitoringMode()``
437+
- Specifies which server monitoring protocol the driver uses.
438+
436439
Example
437440
~~~~~~~
438441

‎source/fundamentals/enterprise-auth.txt

Lines changed: 137 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,14 @@
44
Enterprise Authentication Mechanisms
55
====================================
66

7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: ldap, encryption, principal, tls
13+
14+
715
.. contents:: On this page
816
:local:
917
:backlinks: none
@@ -22,6 +30,7 @@ Enterprise Edition:
2230

2331
- :ref:`Kerberos (GSSAPI) <gssapi-auth-mechanism>`
2432
- :ref:`LDAP (PLAIN) <plain-auth-mechanism>`
33+
- :ref:`MONGODB-OIDC <kotlin-oidc>`
2534

2635
:doc:`Authentication Mechanisms guide </fundamentals/auth>`.
2736

@@ -278,4 +287,131 @@ mechanism:
278287

279288
.. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.ldap-mongo-credential.kt
280289
:language: kotlin
281-
290+
291+
.. _kotlin-oidc:
292+
293+
MONGODB-OIDC
294+
~~~~~~~~~~~~
295+
296+
.. important::
297+
298+
The MONGODB-OIDC authentication mechanism requires {+mdb-server+} v7.0 or later running
299+
on a Linux platform.
300+
301+
The following sections describe how to use the ``MONGODB-OIDC``
302+
authentication mechanism to authenticate to various platforms.
303+
304+
For more information about the MONGODB-OIDC authentication mechanism, see
305+
:manual:`OpenID Connect Authentication </core/security-oidc/>` and
306+
:manual:`MongoDB Server Parameters </reference/parameters/#mongodb-parameter-param.oidcIdentityProviders>`
307+
in the MongoDB Server manual.
308+
309+
.. _kotlin-mongodb-oidc-azure-imds:
310+
311+
Azure IMDS
312+
++++++++++
313+
314+
If your application runs on an Azure VM, or otherwise uses the
315+
`Azure Instance Metadata Service <https://learn.microsoft.com/en-us/azure/virtual-machines/instance-metadata-service>`__
316+
(IMDS), you can authenticate to MongoDB by using the {+driver-short+}'s built-in Azure
317+
support.
318+
319+
You can specify Azure IMDS OIDC authentication either by
320+
using a ``MongoCredential`` or specifying your credentials in the connection string.
321+
322+
Select from the :guilabel:`Connection String` or :guilabel:`MongoCredential` tabs to
323+
see the corresponding syntax.
324+
325+
.. tabs::
326+
327+
.. tab:: Connection String
328+
:tabid: mongodb-azure-imds-connection-string
329+
330+
Replace the ``<percent-encoded audience>`` placeholder in the
331+
following code with the percent-encoded value of the audience server
332+
parameter configured on your MongoDB deployment.
333+
334+
The comma (``,``) character and its encoding (``%2C``) are
335+
reserved, and using these characters in a value causes the
336+
driver to interpret commas as delimiters of key-value pairs.
337+
You must specify values that contain commas in a ``MongoCredential`` instance, as
338+
demonstrated in the :guilabel:`MongoCredential` tab.
339+
340+
.. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-azure-connection-string.kt
341+
:language: kotlin
342+
343+
.. tab:: MongoCredential
344+
:tabid: mongodb-azure-mongo-credential
345+
346+
Replace the ``<username>`` placeholder with the client ID or application ID of the
347+
Azure managed identity or enterprise application. Replace the ``<audience>``
348+
placeholder with the value of the
349+
``audience`` server parameter configured on your MongoDB deployment.
350+
351+
.. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-azure-credential.kt
352+
:language: kotlin
353+
354+
.. _kotlin-mongodb-oidc-gcp-imds:
355+
356+
GCP IMDS
357+
++++++++
358+
359+
If your application runs on a Google Compute Engine VM, or otherwise uses the
360+
`GCP Instance Metadata Service <https://cloud.google.com/compute/docs/metadata/querying-metadata>`__,
361+
you can authenticate to MongoDB by using {+driver-short+}'s built-in GCP
362+
support.
363+
364+
You can specify GCP IMDS OIDC authentication either by
365+
using a ``MongoCredential`` or as part of the connection string.
366+
367+
Select from the :guilabel:`Connection String` or :guilabel:`MongoCredential` tabs to
368+
see the corresponding syntax.
369+
370+
.. tabs::
371+
372+
.. tab:: Connection String
373+
:tabid: mongodb-gcp-imds-connection-string
374+
375+
Replace the ``<percent-encoded audience>`` placeholder in the
376+
following code with the percent-encoded value of the audience server
377+
parameter configured on your MongoDB deployment.
378+
379+
The comma (``,``) character and its encoding (``%2C``) are
380+
reserved, and using these characters in a value causes the
381+
driver to interpret commas as delimiters of key-value pairs.
382+
You must specify values that contain commas in a ``MongoCredential`` instance, as
383+
demonstrated in the :guilabel:`MongoCredential` tab.
384+
385+
.. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-gcp-connection-string.kt
386+
:language: kotlin
387+
388+
.. tab:: MongoCredential
389+
:tabid: mongodb-gcp-mongo-credential
390+
391+
Replace the ``<audience>`` placeholder with the value of the
392+
``audience`` server parameter configured on your MongoDB deployment.
393+
394+
.. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-gcp-credential.kt
395+
:language: kotlin
396+
397+
Custom Callback
398+
+++++++++++++++
399+
400+
The {+driver-short+} doesn't offer built-in support for all platforms, including
401+
Azure Functions and Azure Kubernetes Service (AKS). Instead, you
402+
must define a custom callback to use OIDC to authenticate from these platforms.
403+
To do so, use the ``"OIDC_CALLBACK"`` authentication property, as shown in the following
404+
code example:
405+
406+
.. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-callback.kt
407+
:language: kotlin
408+
409+
The value of the ``"OIDC_CALLBACK"`` property must be a lambda or other implementation
410+
of the ``OidcCallback`` functional interface that accepts an ``OidcCallbackContext``
411+
as a parameter and returns an ``OidcCallbackResult``.
412+
413+
The following example uses an example callback to retrieve an OIDC token from a file
414+
named ``"access-token.dat"`` in the local file system:
415+
416+
.. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-callback-file.kt
417+
:language: kotlin

‎source/whats-new.txt

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,8 @@ Improvements in 5.1
5252
native applications by using the GraalVM native-image tool.
5353

5454
- Enhanced support for the ``MONGODB-OIDC`` authentication mechanism.
55-
56-
.. TODO add OIDC content and link
55+
To learn more about OIDC, see the :ref:`kotlin-oidc` section of the
56+
Enterprise Authentication Mechanisms guide.
5757

5858
- Fixes an issue in which operations used the incorrect codec when using
5959
a polymorphic ``MongoCollection`` instance. This ensures that
@@ -72,9 +72,8 @@ New Features in 5.1
7272

7373
.. TODO add polymorphic serialization content
7474

75-
- Introduces the ``serverMonitoringMode`` connection URI option.
76-
77-
.. TODO add serverMonitoringMode content and link
75+
- Introduces the ``serverMonitoringMode`` connection URI option. To
76+
learn more, see the :ref:`connection-options` guide.
7877

7978
.. _version-5.0:
8079

0 commit comments

Comments
 (0)