DOCSP-41148 Authentication Guides

source/connect/mongoclient.txt

@@ -40,9 +40,6 @@ Connection URI
 
 A standard connection string includes the following components:
 
-.. TODO, add this as last sentence for ``username:password`` description once a kotlin auth page is made: 
-.. For more information about the ``authSource`` connection option, see :ref:`kotlin-sync-auth`. 
-
 .. list-table::
    :widths: 20 80
    :header-rows: 1
@@ -59,6 +56,8 @@ A standard connection string includes the following components:
 
      - Optional. Authentication credentials. If you include these, the client
        authenticates the user against the database specified in ``authSource``.
+       For more information about the ``authSource`` connection option, 
+       see :ref:`kotlin-sync-auth`. 
 
    * - ``host[:port]``
 

source/includes/security/authentication.kt

@@ -0,0 +1,200 @@
+import com.mongodb.*
+import com.mongodb.kotlin.client.MongoClient
+import org.bson.BsonInt64
+import org.bson.Document
+
+// SCRAM Authentication
+// start-default-cred-string
+val mongoClient =
+    MongoClient.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>")
+// end-default-cred-string
+
+// start-default-mongo-cred
+val credential = MongoCredential.createCredential(
+    "<db_username>", "<authenticationDb>", "<db_password>".toCharArray()
+)
+val settings = MongoClientSettings.builder()
+        .applyToClusterSettings { builder: ClusterSettings.Builder ->
+            builder.hosts(
+                listOf(ServerAddress("<hostname>", <port>))
+            )
+        }
+        .credential(credential)
+        .build()
+
+val mongoClient = MongoClient.create(settings)
+// end-default-mongo-cred
+
+// start-scramsha256-cred-string
+val mongoClient =  
+    MongoClient.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=admin&authMechanism=SCRAM-SHA-256")
+// end-scramsha256-cred-string
+
+// start-scramsha256-mongo-cred
+val credential = MongoCredential.createScramSha256Credential(
+    "<db_username>", "<authenticationDb>", "<db_password>".toCharArray()
+)
+val settings = MongoClientSettings.builder()
+        .applyToClusterSettings { builder: ClusterSettings.Builder ->
+            builder.hosts(
+                listOf(ServerAddress("<hostname>", <port>))
+            )
+        }
+        .credential(credential)
+        .build()
+
+val mongoClient = MongoClient.create(settings)
+// end-scramsha256-mongo-cred
+
+// start-scramsha1-cred-string
+val mongoClient =
+    MongoClient.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=admin&authMechanism=SCRAM-SHA-1")
+// end-scramsha1-cred-string
+
+// start-scramsha1-mongo-cred
+val credential = MongoCredential.createScramSha1Credential(
+    "<db_username>", "<authenticationDb>", "<db_password>".toCharArray()
+)
+val settings = MongoClientSettings.builder()
+        .applyToClusterSettings { builder: ClusterSettings.Builder ->
+            builder.hosts(
+                listOf(ServerAddress("<hostname>", <port>))
+            )
+        }
+        .credential(credential)
+        .build()
+
+val mongoClient = MongoClient.create(settings)
+// end-scramsha1-mongo-cred
+
+// AWS Authentication
+
+// start-aws-sdk-mcred
+val credential = MongoCredential.createAwsCredential(null, null)
+
+val settings = MongoClientSettings.builder()
+    .applyToClusterSettings { builder: ClusterSettings.Builder ->
+        builder.hosts(
+            listOf(ServerAddress("<atlasUri>"))
+        )
+    }
+    .credential(credential)
+    .build()
+
+val mongoClient = MongoClient.create(settings)
+// end-aws-sdk-mcred
+
+// start-aws-sdk-cred-string
+val mongoClient =
+    MongoClient.create("mongodb://<atlasUri>?authMechanism=MONGODB-AWS")
+// end-aws-sdk-cred-string
+
+
+// start-aws-env-mcred
+val credential = MongoCredential.createAwsCredential(null, null)
+
+val settings = MongoClientSettings.builder()
+    .applyToClusterSettings { builder: ClusterSettings.Builder ->
+        builder.hosts(
+            listOf(ServerAddress("<atlasUri>"))
+        )
+    }
+    .credential(credential)
+    .build()
+
+val mongoClient = MongoClient.create(settings)
+// end-aws-env-mcred
+
+// start-aws-env-cred-string
+val mongoClient =
+    MongoClient.create("mongodb://<atlasUri>?authMechanism=MONGODB-AWS")
+// end-aws-env-cred-string
+
+// start-aws-mcred
+val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
+
+val settings = MongoClientSettings.builder()
+        .applyToClusterSettings { builder: ClusterSettings.Builder ->
+            builder.hosts(
+                listOf(ServerAddress("<atlasUri>"))
+            )
+        }
+        .credential(credential)
+        .build()
+
+val mongoClient = MongoClient.create(settings)
+// end-aws-mcred
+
+// start-aws-mcred-wmechprop
+val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
+    .withMechanismProperty("AWS_SESSION_TOKEN", "<awsSessionToken>")
+
+val settings = MongoClientSettings.builder()
+        .applyToClusterSettings { builder: ClusterSettings.Builder ->
+            builder.hosts(
+                listOf(ServerAddress("<atlasUri>"))
+            )
+        }
+        .credential(credential)
+        .build()
+
+val mongoClient = MongoClient.create(settings)
+// end-aws-mcred-wmechprop
+
+// start-aws-lambda-expression
+val awsFreshCredentialSupplier: Supplier<AwsCredential> = Supplier {
+    // Add your code here to fetch new credentials
+
+    // Return the new credentials
+    AwsCredential("<awsKeyId>", "<awsSecretKey>", "<awsSessionToken>")
+}
+
+val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
+    .withMechanismProperty(MongoCredential.AWS_CREDENTIAL_PROVIDER_KEY, awsFreshCredentialSupplier)
+
+val settings = MongoClientSettings.builder()
+    .applyToClusterSettings { builder ->
+        builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
+    }
+    .credential(credential)
+    .build()
+
+val mongoClient = MongoClient.create(settings)
+// end-aws-lambda-expression
+
+// start-aws-apply-connect-string
+val credential = MongoCredential.createAwsCredential("<awsKeyId>", "<awsSecretKey>".toCharArray())
+val connectionString = ConnectionString("mongodb://<atlasUri>/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<awsSessionToken>")
+
+val settings = MongoClientSettings.builder()
+    .applyConnectionString(connectionString)
+    .credential(credential)
+    .build()
+
+val mongoClient = MongoClient.create(settings)
+// end-aws-apply-connect-string
+
+// X.509
+
+// start-x509-connect-string
+val mongoClient =
+    MongoClient.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=MONGODB-X509&tls=true")
+// end-x509-connect-string
+
+// start-x509-mcred
+val credential = MongoCredential.createMongoX509Credential()
+
+val settings = MongoClientSettings.builder()
+    .applyToClusterSettings { builder ->
+        builder.hosts(listOf(
+            ServerAddress("<hostname>", <port>))
+        )
+    }
+    .applyToSslSettings { builder ->
+        builder.enabled(true)
+    }
+    .credential(credential)
+    .build()
+
+val mongoClient = MongoClient.create(settings)
+// end-x509-mcred

source/includes/security/enterprise-auth.kt

@@ -0,0 +1,147 @@
+import com.mongodb.*
+import com.mongodb.kotlin.client.MongoClient
+import org.bson.BsonInt64
+import org.bson.Document
+
+// GSSAPI
+
+// start-gssapi-connect-string
+val connectionString = ConnectionString("<Kerberos principal>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI")
+val mongoClient = MongoClient.create(connectionString)
+// end-gssapi-connect-string
+
+// start-gssapi-mongo-cred
+val credential = MongoCredential.createGSSAPICredential("<Kerberos principal>")
+
+val settings = MongoClientSettings.builder()
+        .applyToClusterSettings { builder ->
+            builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
+        }
+        .credential(credential)
+        .build()
+
+val mongoClient = MongoClient.create(settings)
+// end-gssapi-mongo-cred
+
+// start-gssapi-properties-connect-string
+val connectionString = ConnectionString("<Kerberos principal>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:myService")
+val mongoClient = MongoClient.create(connectionString)
+// end-gssapi-properties-connect-string
+
+// start-gssapi-service-name-key
+val credential = MongoCredential.createGSSAPICredential("<Kerberos principal>")
+    .withMechanismProperty(MongoCredential.SERVICE_NAME_KEY, "myService")
+// end-gssapi-service-name-key
+
+// start-gssapi-java-subject-key
+val loginContext = LoginContext("<LoginModule implementation from JAAS config>")
+loginContext.login()
+val subject: Subject = loginContext.subject
+
+val credential = MongoCredential.createGSSAPICredential("<Kerberos principal>")
+    .withMechanismProperty(MongoCredential.JAVA_SUBJECT_KEY, subject)
+// end-gssapi-java-subject-key
+
+// start-gssapi-java-subject-provider
+/* All MongoClient instances sharing this instance of KerberosSubjectProvider
+will share a Kerberos ticket cache */
+val myLoginContext = "myContext"
+/* Login context defaults to "com.sun.security.jgss.krb5.initiate"
+if unspecified in KerberosSubjectProvider */
+val credential = MongoCredential.createGSSAPICredential("<Kerberos principal>")
+    .withMechanismProperty(
+        MongoCredential.JAVA_SUBJECT_PROVIDER_KEY,
+        KerberosSubjectProvider(myLoginContext)
+    )
+// end-gssapi-java-subject-provider
+
+// LDAP
+
+// start-ldap-connect-string
+val connectionString = ConnectionString("<LDAP username>:<password>@<hostname>:<port>/?authSource=$external&authMechanism=PLAIN")
+val mongoClient = MongoClient.create(connectionString)
+// end-ldap-connect-string
+
+// start-ldap-mongo-cred
+val credential = MongoCredential.createPlainCredential("<LDAP username>", "$external", "<password>".toCharArray())
+
+val settings = MongoClientSettings.builder()
+    .applyToClusterSettings { builder ->
+        builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
+    }
+    .credential(credential)
+    .build()
+
+val mongoClient = MongoClient.create(settings)
+// end-ldap-mongo-cred
+
+// OIDC
+
+// start-oidc-azure-connect-str
+val connectionString = ConnectionString(
+    "mongodb://<OIDC principal>@<hostname>:<port>/?" +
+        "?authMechanism=MONGODB-OIDC" +
+        "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<percent-encoded audience>")
+val mongoClient = MongoClient.create(connectionString)
+// end-oidc-azure-connect-str
+
+// start-oidc-azure-mongo-cred
+val credential = MongoCredential.createOidcCredential("<OIDC principal>")
+    .withMechanismProperty("ENVIRONMENT", "azure")
+    .withMechanismProperty("TOKEN_RESOURCE", "<audience>")
+
+val mongoClient = MongoClient.create(
+        MongoClientSettings.builder()
+            .applyToClusterSettings { builder ->
+                builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
+            }
+        .credential(credential)
+        .build())
+// end-oidc-azure-mongo-cred
+
+// start-oidc-gcp-connect-str
+val connectionString = ConnectionString(
+    "mongodb://<OIDC principal>@<hostname>:<port>/?" +
+            "authMechanism=MONGODB-OIDC" +
+            "&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<percent-encoded audience>")
+val mongoClient = MongoClient.create(connectionString)
+// end-oidc-gcp-connect-str
+
+// start-oidc-gcp-mongo-cred
+val credential = MongoCredential.createOidcCredential("<OIDC principal>")
+    .withMechanismProperty("ENVIRONMENT", "gcp")
+    .withMechanismProperty("TOKEN_RESOURCE", "<audience>")
+
+val mongoClient = MongoClient.create(
+    MongoClientSettings.builder()
+        .applyToClusterSettings { builder ->
+            builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
+        }
+        .credential(credential)
+        .build())
+// end-oidc-gcp-mongo-cred
+
+// start-oidc-custom-callback
+val credential = MongoCredential.createOidcCredential(null)
+    .withMechanismProperty("OIDC_CALLBACK") { context: Context ->
+        val accessToken = "..."
+        OidcCallbackResult(accessToken)
+    }
+// end-oidc-custom-callback
+
+// start-oidc-custom-callback-ex
+val credential = MongoCredential.createOidcCredential(null)
+    .withMechanismProperty("OIDC_CALLBACK") { context: Context ->
+        val accessToken = String(Files.readAllBytes(Paths.get("access-token.dat")))
+        OidcCallbackResult(accessToken)
+    }
+
+val mongoClient = MongoClient.create(
+    MongoClientSettings.builder()
+        .applyToClusterSettings { builder ->
+            builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
+        }
+        .credential(credential)
+        .build()
+)
+// end-oidc-custom-callback-ex

source/index.txt

@@ -22,6 +22,7 @@
    Aggregation Operations </agg-exp-ops>
    Specialized Data Formats </data-formats>
    Builders </builders>
+   Security </security>
    In-Use Encryption </encrypt-fields>
    Compatibility </compatibility>
    Validate Driver Signatures </validate-signatures>

source/security.txt

@@ -0,0 +1,14 @@
+
+================
+Secure Your Data
+================
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   Authentication </security/authentication>
+   Enterprise Authentication </security/enterprise-auth>
+   In-Use Encryption </security/encrypt-fields>
+
+.. placeholder