Skip to content

Commit ee9f21e

Browse files
nathan-contino-mongovincentkam
nathan-contino-mongo
authored and
vincentkam
committed
CSHARP-1927: Fix x.509 connection documentation
1 parent 5e8e748 commit ee9f21e

File tree

2 files changed

+80
-42
lines changed

2 files changed

+80
-42
lines changed

‎Docs/reference/content/reference/driver/authentication.md

Lines changed: 79 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -52,34 +52,71 @@ In .NET Standard, authenticating via SCRAM-SHA-256 may not work with non-ASCII p
5252

5353
### x.509 Authentication
5454

55-
The [x.509](http://docs.mongodb.org/manual/core/authentication/#x-509-certificate-authentication) mechanism authenticates a user whose name is derived from the distinguished subject name of the x.509 certificate presented by the driver during SSL negotiation. This authentication method requires the use of [SSL connections]({{< relref "reference\driver\ssl.md" >}}) with certificate validation and is available in MongoDB 2.6 and newer. To create a credential of this type, use the following static factory method:
55+
The [x.509](http://docs.mongodb.org/manual/core/authentication/#x-509-certificate-authentication) mechanism authenticates a user whose name is derived from the distinguished subject name of the x.509 certificate presented by the driver during SSL negotiation. This authentication method requires the use of [SSL connections]({{< relref "reference\driver\ssl.md" >}}) with certificate validation and is available in MongoDB 2.6 and newer.
5656

57-
```csharp
58-
var credential = MongoCredential.CreateX509Credential(username);
59-
```
57+
There are two ways to create a credential of this type:
6058

61-
Or via the connection string:
59+
1. Programmatically, using the following static factory method:
6260

63-
```
64-
mongodb://username@myserver/?authMechanism=MONGODB-X509
65-
```
61+
```csharp
62+
var credential = MongoCredential.CreateX509Credential(username);
63+
```
64+
65+
When configuring x.509 authentication programmatically, the `username` parameter provided to `CreateX509Credential` must match the distinguished subject name of your x.509 certificate *exactly*. To determine the exact `username` required for your x.509 connection, consult [the MongoDB server x.509 tutorial](http://docs.mongodb.org/manual/tutorial/configure-x509-client-authentication/#add-x-509-certificate-subject-as-a-user). Alternatively, any `null` `username` parameter provided to `CreateX509Credential` will cause the MongoDB server to infer a username based on the distinguished subject name of the x.509 certificate. Using a `null` username value can help prevent issues when certificates are updated, since you can avoid managing a `username` value and a certificate as separate entities in your environment.
66+
67+
68+
2. Manually, using [connection string options](https://docs.mongodb.com/manual/reference/connection-string/#connection-string-options):
69+
70+
```
71+
mongodb://myserver/?authMechanism=MONGODB-X509
72+
```
73+
74+
When configuring x.509 authentication from a connection string, you must still provide the certificate programmatically via `MongoClientSettings`. Any connection string specifying x.509 authentication must be imported into a `MongoClientSettings` object using `MongoClientSettings.FromConnectionString` to add the certificate to the configuration.
75+
76+
You can use certificates via the trust stores on your computer, or a PKCS #12 (`.pfx`) file. To be used with client authentication, the [`X509Certificate`]({{< msdnref "system.security.cryptography.x509certificates.x509certificate" >}}) provided to the driver must contain the [`PrivateKey`]({{< msdnref "system.security.cryptography.x509certificates.x509certificate2.privatekey" >}}).
77+
78+
For testing purposes, the `AllowInsecureTls` field of your `MongoClientSettings` can be set to `true` to allow the use of self-signed certificates. Since this setting bypasses the validation of certificates entirely, it should never be used for production uses.
6679

67-
Even when using the connection string to provide the credential, the certificate must still be provided via code. This certificate can be pulled out of the trust stores on the box, or from a file. However, to be used with client authentication, the [`X509Certificate`]({{< msdnref "system.security.cryptography.x509certificates.x509certificate" >}}) provided to the driver must contain the [`PrivateKey`]({{< msdnref "system.security.cryptography.x509certificates.x509certificate2.privatekey" >}}).
80+
Connecting using a `MongoClientSettings` object built from a connection string:
6881

6982
```csharp
70-
var cert = new X509Certificate2("client.pfx", "mySuperSecretPassword");
83+
var connectionString = "mongodb://myserver/?authMechanism=MONGODB-X509";
84+
var settings = MongoClientSettings.FromConnectionString(connectionString);
7185

72-
var settings = new MongoClientSettings
86+
settings.useTls = true;
87+
settings.SslSettings = new SslSettings
7388
{
74-
Credentials = new[]
89+
ClientCertificates = new List<X509Certificate>()
7590
{
76-
MongoCredential.CreateMongoX509Credential("CN=client,OU=user,O=organization,L=Some City,ST=Some State,C=Some Country")
77-
},
91+
new X509Certificate2("client-certificate.pfx", "password")
92+
}
93+
};
94+
95+
// For testing using self-signed certs, use this option to skip validation.
96+
// DO NOT USE THIS OPTION FOR PRODUCTION USES
97+
settings.AllowInsecureTls = true;
98+
```
99+
100+
Connecting using a `MongoClientSettings` object built from scratch:
101+
102+
```csharp
103+
var settings = new MongoClientSettings
104+
{
105+
// if a username is null, the distinguished name from the certificate will be used
106+
Credential = MongoCredential.CreateMongoX509Credential(null),
78107
SslSettings = new SslSettings
79108
{
80-
ClientCertificates = new[] { cert },
109+
ClientCertificates = new List<X509Certificate>()
110+
{
111+
new X509Certificate2("client-certificate.pfx", "password")
112+
},
81113
},
82-
UseSsl = true
114+
UseTls = true,
115+
Server = new MongoServerAddress("myserver", 27017),
116+
117+
// For testing using self-signed certs, use this option to skip validation.
118+
// DO NOT USE THIS OPTION FOR PRODUCTION USES
119+
AllowInsecureTls = true
83120
};
84121
```
85122

@@ -114,46 +151,46 @@ mongodb://username%40REALM.com@myserver/?authMechanism=GSSAPI
114151
Depending on the kerberos setup, it may be required to specify some additional properties. These may be specified in the connection string or via code.
115152

116153
- **CANONICALIZE_HOST_NAME**
117-
118-
Uses the DNS server to retrieve the fully qualified domain name (FQDN) of the host.
119-
120-
```csharp
121-
credential = credential.WithMechanismProperty("CANONICALIZE_HOST_NAME", "true");
122-
```
123154

124-
Or via the connection string:
155+
Uses the DNS server to retrieve the fully qualified domain name (FQDN) of the host.
156+
157+
```csharp
158+
credential = credential.WithMechanismProperty("CANONICALIZE_HOST_NAME", "true");
159+
```
160+
161+
Or via the connection string:
125162

126-
```
127-
mongodb://username@myserver/?authMechanism=GSSAPI&authMechanismProperties=CANONICALIZE_HOSTNAME:true
128-
```
163+
```
164+
mongodb://username@myserver/?authMechanism=GSSAPI&authMechanismProperties=CANONICALIZE_HOSTNAME:true
165+
```
129166

130167
- **REALM**
131168

132-
This is used when the user's realm is different from the service's realm.
169+
This is used when the user's realm is different from the service's realm.
133170

134-
```csharp
135-
credential = credential.WithMechanismProperty("REALM", "otherrealm");
136-
```
171+
```csharp
172+
credential = credential.WithMechanismProperty("REALM", "otherrealm");
173+
```
137174

138-
Or via the connection string:
175+
Or via the connection string:
139176

140-
```
141-
mongodb://username%40REALM.com@myserver/?authMechanism=GSSAPI&authMechanismProperties=REALM:otherrealm
142-
```
177+
```
178+
mongodb://username%40REALM.com@myserver/?authMechanism=GSSAPI&authMechanismProperties=REALM:otherrealm
179+
```
143180

144181
- **SERVICE_NAME**
145182

146-
This is used when the service's name is different that the default `mongodb`.
183+
This is used when the service's name is different that the default `mongodb`.
147184

148-
```csharp
149-
credential = credential.WithMechanismProperty("SERVICE_NAME", "othername");
150-
```
185+
```csharp
186+
credential = credential.WithMechanismProperty("SERVICE_NAME", "othername");
187+
```
151188

152-
Or via the connection string:
189+
Or via the connection string:
153190

154-
```
155-
mongodb://username%40REALM.com@myserver/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:othername
156-
```
191+
```
192+
mongodb://username%40REALM.com@myserver/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:othername
193+
```
157194

158195
In addition, it is possible to use multiple authentication mechanism properties either via code or in the connection string. In code, call `WithMechanismProperty` multiple times. In the connection string, separate the entries with a `,` (comma).
159196

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@ Please see our [guidelines](CONTRIBUTING.md) for contributing to the driver.
9898
* Oscar Bralo https://github.com/Oscarbralo
9999
* Alex Brown https://github.com/alexjamesbrown
100100
* Adam Avery Cole https://github.com/adamaverycole
101+
* Nate Contino https://github.com/nathan-contino-mongo
101102
* Alex Dawes https://github.com/alexdawes
102103
* Justin Dearing [email protected]
103104
* Dan DeBilt [email protected]

0 commit comments

Comments
 (0)