Skip to content

Commit f0e562c

Browse files
norareidynorareidy
authored
DOCSP-41989: Security landing page (#149)
* DOCSP-41989: Security landing page * more info * edits * snooty.toml * edits * RR feedback * JM feedback
1 parent 3bb2cb7 commit f0e562c

File tree

4 files changed

+250
-8
lines changed

4 files changed

+250
-8
lines changed

‎snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ toc_landing_pages = [
2525
"/databases-collections",
2626
"/write",
2727
"/indexes",
28+
"/security"
2829
"/data-formats"
2930
]
3031

‎source/includes/authentication.php

Lines changed: 27 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@
1111
];
1212

1313
$client = new MongoDB\Client(
14-
'mongodb://<hostname>:<port>',
15-
$uriOptions,
14+
'mongodb://<hostname>:<port>',
15+
$uriOptions,
1616
);
1717
// end-scram-sha-256-client
1818

@@ -21,6 +21,25 @@
2121
$client = new MongoDB\Client($uri);
2222
// end-scram-sha-256-uri
2323

24+
// start-scram-sha-1-client
25+
$uriOptions = [
26+
'username' => '<username>',
27+
'password' => '<password>',
28+
'authSource' => '<authentication database>',
29+
'authMechanism' => 'SCRAM-SHA-1',
30+
];
31+
32+
$client = new MongoDB\Client(
33+
'mongodb://<hostname>:<port>',
34+
$uriOptions,
35+
);
36+
// end-scram-sha-1-client
37+
38+
// start-scram-sha-1-uri
39+
$uri = 'mongodb://<username>:<password>@<hostname>:<port>/?authSource=admin&authMechanism=SCRAM-SHA-1';
40+
$client = new MongoDB\Client($uri);
41+
// end-scram-sha-1-uri
42+
2443
// start-mongodb-X509-client
2544
$uriOptions = [
2645
'tls' => true,
@@ -29,8 +48,8 @@
2948
];
3049

3150
$client = new MongoDB\Client(
32-
'mongodb://<hostname>:<port>',
33-
$uriOptions,
51+
'mongodb://<hostname>:<port>',
52+
$uriOptions,
3453
);
3554
// end-mongodb-X509-client
3655

@@ -47,8 +66,8 @@
4766
];
4867

4968
$client = new MongoDB\Client(
50-
'mongodb://<hostname>:<port>',
51-
$uriOptions,
69+
'mongodb://<hostname>:<port>',
70+
$uriOptions,
5271
);
5372
// end-mongodb-aws-client
5473

@@ -59,8 +78,8 @@
5978

6079
// start-mongodb-aws-env-client
6180
$client = new MongoDB\Client(
62-
'mongodb://<hostname>:<port>',
63-
['authMechanism' => 'MONGODB-AWS']
81+
'mongodb://<hostname>:<port>',
82+
['authMechanism' => 'MONGODB-AWS']
6483
);
6584
// end-mongodb-aws-env-client
6685

‎source/includes/usage-examples/connect-sample-app.php

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
<?php
2+
3+
require __DIR__ . '/../vendor/autoload.php';
4+
5+
// Start example code here
6+
7+
// End example code here
8+
9+
try {
10+
$client->test->command(['ping' => 1]);
11+
echo 'Successfully pinged the MongoDB server.', PHP_EOL;
12+
} catch (MongoDB\Driver\Exception\RuntimeException $e) {
13+
printf("Failed to ping the MongoDB server: %s\n", $e->getMessage());
14+
}

‎source/security.txt

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,217 @@
44
Secure Your Data
55
================
66

7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: ldap, authorize, ecs, aws, authenticate
19+
:description: Learn how to use the PHP library to secure your data.
20+
721
.. toctree::
822
:titlesonly:
923
:maxdepth: 1
1024

1125
/security/authentication
1226
/security/in-use-encryption
27+
28+
Overview
29+
--------
30+
31+
MongoDB supports multiple mechanisms that you can use to authenticate your application.
32+
This page contains code examples that demonstrate each of these mechanisms.
33+
34+
.. tip::
35+
36+
To learn more about any of the mechanisms shown on this page, see the link
37+
provided in each section.
38+
39+
To use an authentication example from this page, copy the code example into the
40+
:ref:`sample application <php-auth-sample>` or your own application.
41+
Make sure to replace all placeholders in the code examples, such as ``<hostname>``, with
42+
the relevant values for your MongoDB deployment.
43+
44+
.. _php-auth-sample:
45+
46+
.. include:: /includes/usage-examples/sample-app-intro.rst
47+
48+
.. literalinclude:: /includes/usage-examples/connect-sample-app.php
49+
:language: php
50+
:copyable: true
51+
:linenos:
52+
:emphasize-lines: 5-7
53+
54+
SCRAM-SHA-256
55+
-------------
56+
57+
The following code shows how to authenticate by using the ``SCRAM-SHA-256``
58+
authentication mechanism:
59+
60+
.. tabs::
61+
62+
.. tab:: MongoDB\\Client
63+
:tabid: Client
64+
65+
.. literalinclude:: /includes/authentication.php
66+
:language: php
67+
:dedent:
68+
:start-after: start-scram-sha-256-client
69+
:end-before: end-scram-sha-256-client
70+
71+
.. tab:: Connection URI
72+
:tabid: connectionstring
73+
74+
.. literalinclude:: /includes/authentication.php
75+
:language: php
76+
:dedent:
77+
:start-after: start-scram-sha-256-uri
78+
:end-before: end-scram-sha-256-uri
79+
80+
To learn more about SCRAM-SHA-256 authentication, see :ref:`php-scram-sha-256` in
81+
the Authentication guide.
82+
83+
SCRAM-SHA-1
84+
-----------
85+
86+
The following code shows how to authenticate by using the ``SCRAM-SHA-1``
87+
authentication mechanism:
88+
89+
.. tabs::
90+
91+
.. tab:: MongoDB\\Client
92+
:tabid: Client
93+
94+
.. literalinclude:: /includes/authentication.php
95+
:language: php
96+
:dedent:
97+
:start-after: start-scram-sha-1-client
98+
:end-before: end-scram-sha-1-client
99+
100+
.. tab:: Connection URI
101+
:tabid: connectionstring
102+
103+
.. literalinclude:: /includes/authentication.php
104+
:language: php
105+
:dedent:
106+
:start-after: start-scram-sha-1-uri
107+
:end-before: end-scram-sha-1-uri
108+
109+
To learn more about SCRAM-SHA-1 authentication, see :ref:`php-scram-sha-1` in
110+
the Authentication guide.
111+
112+
MONGODB X.509
113+
-------------
114+
115+
The following code shows how to create a connection URI to authenticate by using
116+
the ``X.509`` authentication mechanism:
117+
118+
.. tabs::
119+
120+
.. tab:: MongoDB\\Client
121+
:tabid: Client
122+
123+
.. literalinclude:: /includes/authentication.php
124+
:language: php
125+
:dedent:
126+
:start-after: start-mongodb-X509-client
127+
:end-before: end-mongodb-X509-client
128+
129+
.. tab:: Connection URI
130+
:tabid: connectionstring
131+
132+
.. literalinclude:: /includes/authentication.php
133+
:language: php
134+
:dedent:
135+
:start-after: start-mongodb-X509-uri
136+
:end-before: end-mongodb-X509-uri
137+
138+
To learn more about X.509 authentication, see :ref:`php-x509` in
139+
the Authentication guide.
140+
141+
MONGODB-AWS
142+
-----------
143+
144+
The following sections show how to connect to MongoDB by using the ``MONGODB-AWS``
145+
authentication mechanism. When you use the ``MONGODB-AWS`` mechanism, the {+php-library+}
146+
attempts to retrieve your AWS credentials from the following sources, in the order listed:
147+
148+
1. Options passed to the ``MongoDB\Client`` constructor, either as part of the connection
149+
string or the ``$uriOptions`` array parameter
150+
#. Environment variables
151+
#. AWS EKS ``AssumeRoleWithWebIdentity`` request
152+
#. ECS container metadata
153+
#. EC2 instance metadata
154+
155+
Each section shows how to authenticate with ``MONGODB-AWS`` when retrieving your
156+
AWS credentials from options passed to your client or the alternative external sources.
157+
158+
To learn more about authenticating with AWS, see :ref:`php-mongo-aws` in the
159+
Authentication guide.
160+
161+
MongoDB\\Client Credentials
162+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
163+
164+
The following code shows how to pass AWS credentials to the ``MongoDB\Client`` constructor
165+
to authenticate with ``MONGODB-AWS``:
166+
167+
.. tabs::
168+
169+
.. tab:: MongoDB\\Client
170+
:tabid: Client
171+
172+
.. literalinclude:: /includes/authentication.php
173+
:language: php
174+
:dedent:
175+
:start-after: start-mongodb-aws-client
176+
:end-before: end-mongodb-aws-client
177+
178+
.. tab:: Connection URI
179+
:tabid: connectionstring
180+
181+
.. literalinclude:: /includes/authentication.php
182+
:language: php
183+
:dedent:
184+
:start-after: start-mongodb-aws-uri
185+
:end-before: end-mongodb-aws-uri
186+
187+
External Credentials
188+
~~~~~~~~~~~~~~~~~~~~
189+
190+
The following code shows how to authenticate with ``MONGODB-AWS`` when
191+
obtaining credentials from environment variables, an ``AssumeRoleWithWebIdentity``
192+
request, ECS metadata, or EC2 instance metadata:
193+
194+
.. tabs::
195+
196+
.. tab:: MongoDB\\Client
197+
:tabid: Client
198+
199+
.. literalinclude:: /includes/authentication.php
200+
:language: php
201+
:dedent:
202+
:start-after: start-mongodb-aws-env-client
203+
:end-before: end-mongodb-aws-env-client
204+
205+
.. tab:: Connection URI
206+
:tabid: connectionstring
207+
208+
.. literalinclude:: /includes/authentication.php
209+
:language: php
210+
:dedent:
211+
:start-after: start-mongodb-aws-env-uri
212+
:end-before: end-mongodb-aws-env-uri
213+
214+
To learn more about authenticating with AWS by obtaining external
215+
credentials, see the following sections in the Authentication guide:
216+
217+
- :ref:`php-mongo-aws-environment`
218+
- :ref:`php-mongo-aws-assume-role`
219+
- :ref:`php-mongo-aws-ecs`
220+
- :ref:`php-mongo-aws-ec2`

0 commit comments

Comments
 (0)