Skip to content

Commit d360ee1

Browse files
lindseymoorelindseymoore
authored
DOCSP-41148 Authentication Guides (#50)
* authentication v1 * fix build * add to toc * enterprise auth ex * broken link fix * link fix * link fix * last link fix for auth * enterprise auth links * fix * enterprise standardize * authen remodel * move x509 up * add ref * remove note * review comments * fix link * first round * fix core api links * last comments * link run through * quick * last inernal review comments * back to standard form * edit * port as integer * add security section * fix sncrypt fileds toc * add toc labels
1 parent fe5d9f8 commit d360ee1

File tree

8 files changed

+1368
-3
lines changed

8 files changed

+1368
-3
lines changed

‎source/connect/mongoclient.txt

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,9 +40,6 @@ Connection URI
4040

4141
A standard connection string includes the following components:
4242

43-
.. TODO, add this as last sentence for ``username:password`` description once a kotlin auth page is made:
44-
.. For more information about the ``authSource`` connection option, see :ref:`kotlin-sync-auth`.
45-
4643
.. list-table::
4744
:widths: 20 80
4845
:header-rows: 1
@@ -59,6 +56,8 @@ A standard connection string includes the following components:
5956

6057
- Optional. Authentication credentials. If you include these, the client
6158
authenticates the user against the database specified in ``authSource``.
59+
For more information about the ``authSource`` connection option,
60+
see :ref:`kotlin-sync-auth`.
6261

6362
* - ``host[:port]``
6463

‎source/includes/security/authentication.kt

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
import com.mongodb.*
2+
import com.mongodb.kotlin.client.MongoClient
3+
import org.bson.BsonInt64
4+
import org.bson.Document
5+
6+
// SCRAM Authentication
7+
// start-default-cred-string
8+
val mongoClient =
9+
MongoClient.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>")
10+
// end-default-cred-string
11+
12+
// start-default-mongo-cred
13+
val credential = MongoCredential.createCredential(
14+
"<db_username>", "<authenticationDb>", "<db_password>".toCharArray()
15+
)
16+
val settings = MongoClientSettings.builder()
17+
.applyToClusterSettings { builder: ClusterSettings.Builder ->
18+
builder.hosts(
19+
listOf(ServerAddress("<hostname>", <port>))
20+
)
21+
}
22+
.credential(credential)
23+
.build()
24+
25+
val mongoClient = MongoClient.create(settings)
26+
// end-default-mongo-cred
27+
28+
// start-scramsha256-cred-string
29+
val mongoClient =
30+
MongoClient.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=admin&authMechanism=SCRAM-SHA-256")
31+
// end-scramsha256-cred-string
32+
33+
// start-scramsha256-mongo-cred
34+
val credential = MongoCredential.createScramSha256Credential(
35+
"<db_username>", "<authenticationDb>", "<db_password>".toCharArray()
36+
)
37+
val settings = MongoClientSettings.builder()
38+
.applyToClusterSettings { builder: ClusterSettings.Builder ->
39+
builder.hosts(
40+
listOf(ServerAddress("<hostname>", <port>))
41+
)
42+
}
43+
.credential(credential)
44+
.build()
45+
46+
val mongoClient = MongoClient.create(settings)
47+
// end-scramsha256-mongo-cred
48+
49+
// start-scramsha1-cred-string
50+
val mongoClient =
51+
MongoClient.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=admin&authMechanism=SCRAM-SHA-1")
52+
// end-scramsha1-cred-string
53+
54+
// start-scramsha1-mongo-cred
55+
val credential = MongoCredential.createScramSha1Credential(
56+
"<db_username>", "<authenticationDb>", "<db_password>".toCharArray()
57+
)
58+
val settings = MongoClientSettings.builder()
59+
.applyToClusterSettings { builder: ClusterSettings.Builder ->
60+
builder.hosts(
61+
listOf(ServerAddress("<hostname>", <port>))
62+
)
63+
}
64+
.credential(credential)
65+
.build()
66+
67+
val mongoClient = MongoClient.create(settings)
68+
// end-scramsha1-mongo-cred
69+
70+
// AWS Authentication
71+
72+
// start-aws-sdk-mcred
73+
val credential = MongoCredential.createAwsCredential(null, null)
74+
75+
val settings = MongoClientSettings.builder()
76+
.applyToClusterSettings { builder: ClusterSettings.Builder ->
77+
builder.hosts(
78+
listOf(ServerAddress("<atlasUri>"))
79+
)
80+
}
81+
.credential(credential)
82+
.build()
83+
84+
val mongoClient = MongoClient.create(settings)
85+
// end-aws-sdk-mcred
86+
87+
// start-aws-sdk-cred-string
88+
val mongoClient =
89+
MongoClient.create("mongodb://<atlasUri>?authMechanism=MONGODB-AWS")
90+
// end-aws-sdk-cred-string
91+
92+
93+
// start-aws-env-mcred
94+
val credential = MongoCredential.createAwsCredential(null, null)
95+
96+
val settings = MongoClientSettings.builder()
97+
.applyToClusterSettings { builder: ClusterSettings.Builder ->
98+
builder.hosts(
99+
listOf(ServerAddress("<atlasUri>"))
100+
)
101+
}
102+
.credential(credential)
103+
.build()
104+
105+
val mongoClient = MongoClient.create(settings)
106+
// end-aws-env-mcred
107+
108+
// start-aws-env-cred-string
109+
val mongoClient =
110+
MongoClient.create("mongodb://<atlasUri>?authMechanism=MONGODB-AWS")
111+
// end-aws-env-cred-string
112+
113+
// start-aws-mcred
114+
val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
115+
116+
val settings = MongoClientSettings.builder()
117+
.applyToClusterSettings { builder: ClusterSettings.Builder ->
118+
builder.hosts(
119+
listOf(ServerAddress("<atlasUri>"))
120+
)
121+
}
122+
.credential(credential)
123+
.build()
124+
125+
val mongoClient = MongoClient.create(settings)
126+
// end-aws-mcred
127+
128+
// start-aws-mcred-wmechprop
129+
val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
130+
.withMechanismProperty("AWS_SESSION_TOKEN", "<awsSessionToken>")
131+
132+
val settings = MongoClientSettings.builder()
133+
.applyToClusterSettings { builder: ClusterSettings.Builder ->
134+
builder.hosts(
135+
listOf(ServerAddress("<atlasUri>"))
136+
)
137+
}
138+
.credential(credential)
139+
.build()
140+
141+
val mongoClient = MongoClient.create(settings)
142+
// end-aws-mcred-wmechprop
143+
144+
// start-aws-lambda-expression
145+
val awsFreshCredentialSupplier: Supplier<AwsCredential> = Supplier {
146+
// Add your code here to fetch new credentials
147+
148+
// Return the new credentials
149+
AwsCredential("<awsKeyId>", "<awsSecretKey>", "<awsSessionToken>")
150+
}
151+
152+
val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
153+
.withMechanismProperty(MongoCredential.AWS_CREDENTIAL_PROVIDER_KEY, awsFreshCredentialSupplier)
154+
155+
val settings = MongoClientSettings.builder()
156+
.applyToClusterSettings { builder ->
157+
builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
158+
}
159+
.credential(credential)
160+
.build()
161+
162+
val mongoClient = MongoClient.create(settings)
163+
// end-aws-lambda-expression
164+
165+
// start-aws-apply-connect-string
166+
val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
167+
val connectionString = ConnectionString("mongodb://<atlasUri>/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<awsSessionToken>")
168+
169+
val settings = MongoClientSettings.builder()
170+
.applyConnectionString(connectionString)
171+
.credential(credential)
172+
.build()
173+
174+
val mongoClient = MongoClient.create(settings)
175+
// end-aws-apply-connect-string
176+
177+
// X.509
178+
179+
// start-x509-connect-string
180+
val mongoClient =
181+
MongoClient.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=MONGODB-X509&tls=true")
182+
// end-x509-connect-string
183+
184+
// start-x509-mcred
185+
val credential = MongoCredential.createMongoX509Credential()
186+
187+
val settings = MongoClientSettings.builder()
188+
.applyToClusterSettings { builder ->
189+
builder.hosts(listOf(
190+
ServerAddress("<hostname>", <port>))
191+
)
192+
}
193+
.applyToSslSettings { builder ->
194+
builder.enabled(true)
195+
}
196+
.credential(credential)
197+
.build()
198+
199+
val mongoClient = MongoClient.create(settings)
200+
// end-x509-mcred

‎source/includes/security/enterprise-auth.kt

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
import com.mongodb.*
2+
import com.mongodb.kotlin.client.MongoClient
3+
import org.bson.BsonInt64
4+
import org.bson.Document
5+
6+
// GSSAPI
7+
8+
// start-gssapi-connect-string
9+
val connectionString = ConnectionString("<Kerberos principal>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI")
10+
val mongoClient = MongoClient.create(connectionString)
11+
// end-gssapi-connect-string
12+
13+
// start-gssapi-mongo-cred
14+
val credential = MongoCredential.createGSSAPICredential("<Kerberos principal>")
15+
16+
val settings = MongoClientSettings.builder()
17+
.applyToClusterSettings { builder ->
18+
builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
19+
}
20+
.credential(credential)
21+
.build()
22+
23+
val mongoClient = MongoClient.create(settings)
24+
// end-gssapi-mongo-cred
25+
26+
// start-gssapi-properties-connect-string
27+
val connectionString = ConnectionString("<Kerberos principal>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:myService")
28+
val mongoClient = MongoClient.create(connectionString)
29+
// end-gssapi-properties-connect-string
30+
31+
// start-gssapi-service-name-key
32+
val credential = MongoCredential.createGSSAPICredential("<Kerberos principal>")
33+
.withMechanismProperty(MongoCredential.SERVICE_NAME_KEY, "myService")
34+
// end-gssapi-service-name-key
35+
36+
// start-gssapi-java-subject-key
37+
val loginContext = LoginContext("<LoginModule implementation from JAAS config>")
38+
loginContext.login()
39+
val subject: Subject = loginContext.subject
40+
41+
val credential = MongoCredential.createGSSAPICredential("<Kerberos principal>")
42+
.withMechanismProperty(MongoCredential.JAVA_SUBJECT_KEY, subject)
43+
// end-gssapi-java-subject-key
44+
45+
// start-gssapi-java-subject-provider
46+
/* All MongoClient instances sharing this instance of KerberosSubjectProvider
47+
will share a Kerberos ticket cache */
48+
val myLoginContext = "myContext"
49+
/* Login context defaults to "com.sun.security.jgss.krb5.initiate"
50+
if unspecified in KerberosSubjectProvider */
51+
val credential = MongoCredential.createGSSAPICredential("<Kerberos principal>")
52+
.withMechanismProperty(
53+
MongoCredential.JAVA_SUBJECT_PROVIDER_KEY,
54+
KerberosSubjectProvider(myLoginContext)
55+
)
56+
// end-gssapi-java-subject-provider
57+
58+
// LDAP
59+
60+
// start-ldap-connect-string
61+
val connectionString = ConnectionString("<LDAP username>:<password>@<hostname>:<port>/?authSource=$external&authMechanism=PLAIN")
62+
val mongoClient = MongoClient.create(connectionString)
63+
// end-ldap-connect-string
64+
65+
// start-ldap-mongo-cred
66+
val credential = MongoCredential.createPlainCredential("<LDAP username>", "$external", "<password>".toCharArray())
67+
68+
val settings = MongoClientSettings.builder()
69+
.applyToClusterSettings { builder ->
70+
builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
71+
}
72+
.credential(credential)
73+
.build()
74+
75+
val mongoClient = MongoClient.create(settings)
76+
// end-ldap-mongo-cred
77+
78+
// OIDC
79+
80+
// start-oidc-azure-connect-str
81+
val connectionString = ConnectionString(
82+
"mongodb://<OIDC principal>@<hostname>:<port>/?" +
83+
"?authMechanism=MONGODB-OIDC" +
84+
"&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<percent-encoded audience>")
85+
val mongoClient = MongoClient.create(connectionString)
86+
// end-oidc-azure-connect-str
87+
88+
// start-oidc-azure-mongo-cred
89+
val credential = MongoCredential.createOidcCredential("<OIDC principal>")
90+
.withMechanismProperty("ENVIRONMENT", "azure")
91+
.withMechanismProperty("TOKEN_RESOURCE", "<audience>")
92+
93+
val mongoClient = MongoClient.create(
94+
MongoClientSettings.builder()
95+
.applyToClusterSettings { builder ->
96+
builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
97+
}
98+
.credential(credential)
99+
.build())
100+
// end-oidc-azure-mongo-cred
101+
102+
// start-oidc-gcp-connect-str
103+
val connectionString = ConnectionString(
104+
"mongodb://<OIDC principal>@<hostname>:<port>/?" +
105+
"authMechanism=MONGODB-OIDC" +
106+
"&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<percent-encoded audience>")
107+
val mongoClient = MongoClient.create(connectionString)
108+
// end-oidc-gcp-connect-str
109+
110+
// start-oidc-gcp-mongo-cred
111+
val credential = MongoCredential.createOidcCredential("<OIDC principal>")
112+
.withMechanismProperty("ENVIRONMENT", "gcp")
113+
.withMechanismProperty("TOKEN_RESOURCE", "<audience>")
114+
115+
val mongoClient = MongoClient.create(
116+
MongoClientSettings.builder()
117+
.applyToClusterSettings { builder ->
118+
builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
119+
}
120+
.credential(credential)
121+
.build())
122+
// end-oidc-gcp-mongo-cred
123+
124+
// start-oidc-custom-callback
125+
val credential = MongoCredential.createOidcCredential(null)
126+
.withMechanismProperty("OIDC_CALLBACK") { context: Context ->
127+
val accessToken = "..."
128+
OidcCallbackResult(accessToken)
129+
}
130+
// end-oidc-custom-callback
131+
132+
// start-oidc-custom-callback-ex
133+
val credential = MongoCredential.createOidcCredential(null)
134+
.withMechanismProperty("OIDC_CALLBACK") { context: Context ->
135+
val accessToken = String(Files.readAllBytes(Paths.get("access-token.dat")))
136+
OidcCallbackResult(accessToken)
137+
}
138+
139+
val mongoClient = MongoClient.create(
140+
MongoClientSettings.builder()
141+
.applyToClusterSettings { builder ->
142+
builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
143+
}
144+
.credential(credential)
145+
.build()
146+
)
147+
// end-oidc-custom-callback-ex

‎source/index.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
Aggregation Operations </agg-exp-ops>
2323
Specialized Data Formats </data-formats>
2424
Builders </builders>
25+
Security </security>
2526
In-Use Encryption </encrypt-fields>
2627
Compatibility </compatibility>
2728
Validate Driver Signatures </validate-signatures>

‎source/security.txt

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
2+
================
3+
Secure Your Data
4+
================
5+
6+
.. toctree::
7+
:titlesonly:
8+
:maxdepth: 1
9+
10+
Authentication </security/authentication>
11+
Enterprise Authentication </security/enterprise-auth>
12+
In-Use Encryption </security/encrypt-fields>
13+
14+
.. placeholder

0 commit comments

Comments
 (0)