Skip to content

Commit 646ea1e

Browse files
mongoKartjordan-smith721
mongoKart
and
jordan-smith721
authored
DOCSP-37510 - Enterprise Authentication (#57)
Co-authored-by: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com>
1 parent efada2d commit 646ea1e

File tree

4 files changed

+206
-143
lines changed

4 files changed

+206
-143
lines changed

‎source/fundamentals.txt

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,6 @@ Fundamentals
1414
/fundamentals/collations
1515
/fundamentals/databases-and-collections
1616
/fundamentals/dates-and-times
17-
/fundamentals/enterprise-authentication
1817
/fundamentals/gridfs
1918
/fundamentals/indexes
2019
/fundamentals/type-hints
@@ -23,7 +22,6 @@ Fundamentals
2322
- :ref:`pymongo-collations`
2423
- :ref:`pymongo-databases-collections`
2524
- :ref:`pymongo-dates-times`
26-
- :ref:`pymongo-enterprise-auth`
2725
- :ref:`pymongo-gridfs`
2826
- :ref:`pymongo-indexes`
2927
- :ref:`pymongo-type-hints`

‎source/fundamentals/enterprise-authentication.txt

Lines changed: 0 additions & 141 deletions
This file was deleted.

‎source/security.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,9 @@ Secure Your Data
1212
:maxdepth: 1
1313

1414
/security/authentication
15+
/security/enterprise-authentication
1516
/security/in-use-encryption
1617

1718
- :ref:`pymongo-auth`
19+
- :ref:`pymongo-enterprise-auth`
1820
- :ref:`pymongo-in-use-encryption`

‎source/security/enterprise-authentication.txt

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
.. _pymongo-enterprise-auth:
2+
3+
Enterprise Authentication Mechanisms
4+
====================================
5+
6+
.. contents:: On this page
7+
:local:
8+
:backlinks: none
9+
:depth: 2
10+
:class: singlecol
11+
12+
.. facet::
13+
:name: genre
14+
:values: reference
15+
16+
.. meta::
17+
:keywords: ldap, encryption, principal, tls
18+
19+
Overview
20+
--------
21+
22+
MongoDB Enterprise Edition includes the following authentication mechanisms that aren't
23+
available in MongoDB Community Edition:
24+
25+
- :ref:`GSSAPI/Kerberos <pymongo-kerberos>`
26+
- :ref:`LDAP (Plain) <pymongo-sasl>`
27+
28+
In this guide, you can learn how to authenticate to MongoDB by using these
29+
authentication mechanisms. To learn about the other authentication mechanisms available
30+
in MongoDB, see :ref:`<pymongo-auth>`.
31+
32+
.. _pymongo-kerberos:
33+
34+
GSSAPI (Kerberos)
35+
-----------------
36+
37+
The Generic Security Services API (GSSAPI) provides an interface for Kerberos
38+
authentication. Select the tab that corresponds to your operating system to learn how
39+
to use GSSAPI to authenticate.
40+
41+
.. tabs::
42+
43+
.. tab:: Unix
44+
:tabid: unix
45+
46+
First, use pip or easy_install to install the Python
47+
`kerberos <http://pypi.python.org/pypi/kerberos>`__ or
48+
`pykerberos <https://pypi.python.org/pypi/pykerberos>`__ module.
49+
50+
After installing one of these modules, run the ``kinit`` command to obtain and cache
51+
an initial ticket-granting ticket. The following example uses the
52+
``knit`` command to obtain a ticket-granting ticket for the principal
53+
``mongodbuser@EXAMPLE.COM``. It then uses the ``klist``
54+
command to display the principal and ticket in the credentials cache.
55+
56+
.. code-block:: sh
57+
:copyable: false
58+
59+
$ kinit mongodbuser@EXAMPLE.COM
60+
mongodbuser@EXAMPLE.COM's Password:
61+
$ klist
62+
Credentials cache: FILE:/tmp/krb5cc_1000
63+
Principal: mongodbuser@EXAMPLE.COM
64+
65+
Issued Expires Principal
66+
Feb 9 13:48:51 2013 Feb 9 23:48:51 2013 krbtgt/mongodbuser@EXAMPLE.COM
67+
68+
After you obtain a ticket-granting ticket, set the following connection options:
69+
70+
- ``username``: The Kerbos principal to authenticate. Percent-encode this value
71+
before including it in a connection URI.
72+
- ``authMechanism``: Set to ``"GSSAPI"``.
73+
- ``authMechanismProperties``: Optional. By default, MongoDB uses ``mongodb`` as
74+
the authentication service name. To specify a different service name, set
75+
this option to ``"SERVICE_NAME:<authentication service name>"``.
76+
77+
You can set these options in two ways: by passing arguments to the
78+
``MongoClient`` constructor or through parameters in your connection string.
79+
80+
.. tabs::
81+
82+
.. tab:: MongoClient
83+
:tabid: mongoclient
84+
85+
.. code-block:: python
86+
87+
client = pymongo.MongoClient("mongodb://<hostname>:<port>",
88+
username="mongodbuser@EXAMPLE.COM",
89+
authMechanism="GSSAPI",
90+
authMechanismProperties="SERVICE_NAME:<authentication service name>")
91+
92+
.. tab:: Connection String
93+
:tabid: connectionstring
94+
95+
.. code-block:: python
96+
97+
uri = ("mongodb://mongodbuser%40EXAMPLE.COM@<hostname>:<port>/?"
98+
"&authMechanism=GSSAPI"
99+
"&authMechanismProperties=SERVICE_NAME:<authentication service name>")
100+
client = pymongo.MongoClient(uri)
101+
102+
.. tab:: Windows (SSPI)
103+
:tabid: windows
104+
105+
First, install the `winkerberos <https://pypi.python.org/pypi/winkerberos/>`__ module.
106+
Then, set the following connection options:
107+
108+
- ``username``: The Kerbos principal to authenticate. Percent-encode this value before including
109+
it in a connection URI.
110+
- ``authMechanism``: Set to ``"GSSAPI"``.
111+
- ``password``: Optional. If the user to authenticate is different from the user
112+
that owns the application process, set this option to the authenticating user's
113+
password.
114+
- ``authMechanismProperties``: Optional. This option includes multiple
115+
authentication properties. To specify more than one of the following properties,
116+
use a comma-delimited list.
117+
118+
- ``SERVICE_NAME:`` By default, MongoDB uses ``mongodb`` as
119+
the authentication service name. Use this option to specify a different service name.
120+
- ``CANONICALIZE_HOST_NAME``: Whether to use the fully qualified domain name (FQDN)
121+
of the MongoDB host for the server principal.
122+
- ``SERVICE_REALM``: The service realm. Use this option when the user's
123+
realm is different from the service's realm.
124+
125+
You can set these options in two ways: by passing arguments to the
126+
``MongoClient`` constructor or through parameters in your connection string.
127+
128+
.. tabs::
129+
130+
.. tab:: MongoClient
131+
:tabid: mongoclient
132+
133+
.. code-block:: python
134+
135+
client = pymongo.MongoClient("mongodb://<hostname>:<port>",
136+
username="mongodbuser@EXAMPLE.COM",
137+
authMechanism="GSSAPI",
138+
password="<user password>",
139+
authMechanismProperties="SERVICE_NAME:<authentication service name>,
140+
CANONICALIZE_HOST_NAME:true,
141+
SERVICE_REALM:<service realm>")
142+
143+
.. tab:: Connection String
144+
:tabid: connectionstring
145+
146+
.. code-block:: python
147+
148+
uri = ("mongodb://mongodbuser%40EXAMPLE.COM:<percent-encoded user password>"
149+
"@<hostname>:<port>/?"
150+
"&authMechanism=GSSAPI"
151+
"&authMechanismProperties="
152+
"SERVICE_NAME:<authentication service name>,"
153+
"CANONICALIZE_HOST_NAME:true,"
154+
"SERVICE_REALM:<service realm>")
155+
client = pymongo.MongoClient(uri)
156+
157+
.. _pymongo-sasl:
158+
159+
PLAIN SASL
160+
----------
161+
162+
The PLAIN Simple Authentication and Security Layer (SASL), as defined
163+
by `RFC 4616 <https://www.rfc-editor.org/rfc/rfc4616>`__, is a username-password
164+
authentication mechanism often used with TLS or another encryption layer.
165+
166+
.. important::
167+
168+
PLAIN SASL is a clear-text authentication mechanism. We strongly recommend that you
169+
use TLS/SSL with certificate validation when using PLAIN SASL to authenticate to MongoDB.
170+
171+
To learn more about how to enable TLS for your connection, see :ref:`<pymongo-tls>`.
172+
173+
To authenticate with SASL, set the ``authMechanism`` connection option to ``PLAIN``.
174+
You can set this option in two ways: by passing an argument to the
175+
``MongoClient`` constructor or through a parameter in your connection string.
176+
177+
.. tabs::
178+
179+
.. tab:: MongoClient
180+
:tabid: mongoclient
181+
182+
.. code-block:: python
183+
184+
client = pymongo.MongoClient("mongodb://<hostname>:<port>",
185+
authMechanism="PLAIN",
186+
tls=True)
187+
188+
.. tab:: Connection String
189+
:tabid: connectionstring
190+
191+
.. code-block:: python
192+
193+
uri = ("mongodb://<hostname>:<port>/?"
194+
"&authMechanism=PLAIN"
195+
"&tls=true")
196+
client = pymongo.MongoClient(uri)
197+
198+
API Documentation
199+
-----------------
200+
201+
To learn more about using enterprise authentication mechanisms with {+driver-short+},
202+
see the following API documentation:
203+
204+
- `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__

0 commit comments

Comments
 (0)