Skip to content

Commit 331a720

Browse files
mongoKartmongoKart
authored
DOCSP-37001 - Enterprise Auth (#19)
1 parent cf9c7e6 commit 331a720

File tree

2 files changed

+84
-58
lines changed

2 files changed

+84
-58
lines changed

‎source/fundamentals.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,13 @@ Fundamentals
1111
:titlesonly:
1212
:maxdepth: 1
1313

14+
/fundamentals/enterprise-authentication
1415
/fundamentals/indexes
1516
/fundamentals/in-use-encryption
1617
/fundamentals/periodic-executors
1718
/fundamentals/type-hints
1819

20+
- :ref:`pymongo-enterprise-auth`
1921
- :ref:`pymongo-indexes`
2022
- :ref:`pymongo-in-use-encryption`
2123
- :ref:`pymongo-periodic-executors`

‎source/fundamentals/enterprise-authentication.txt

Lines changed: 82 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,58 @@
1-
.. uses authentication.rst
1+
.. _pymongo-enterprise-auth:
22

3-
Enterprise Authentication
4-
=========================
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+
In this guide, you can learn how to authenticate with MongoDB by using the authentication
20+
mechanisms available only in the MongoDB Enterprise Edition.
521

622
.. _gssapi:
723

824
GSSAPI (Kerberos)
925
-----------------
10-
.. versionadded:: 2.5
1126

12-
GSSAPI (Kerberos) authentication is available in the Enterprise Edition of
13-
MongoDB.
27+
The Generic Security Services API (GSSAPI) provides an interface for Kerberos
28+
authentication.
1429

1530
Unix
1631
~~~~
1732

18-
To authenticate using GSSAPI you must first install the python `kerberos`_ or
19-
`pykerberos`_ module using easy_install or pip. Make sure you run kinit before
20-
using the following authentication methods:
33+
To use GSSAPI to authenticate, you must first use pip or easy_install to install the Python
34+
`kerberos <http://pypi.python.org/pypi/kerberos>`__ or
35+
`pykerberos <https://pypi.python.org/pypi/pykerberos>`__ module.
2136

22-
.. code-block:: python
37+
After installing the module, run the ``kinit`` command, as shown in the following example.
38+
``kinit`` obtains and caches an initial ticket-granting ticket.
2339

24-
$ kinit [email protected]
25-
[email protected]'s Password:
26-
$ klist
27-
Credentials cache: FILE:/tmp/krb5cc_1000
28-
Principal: [email protected]
40+
.. _kerberos:
2941

30-
Issued Expires Principal
31-
Feb 9 13:48:51 2013 Feb 9 23:48:51 2013 krbtgt/[email protected]
42+
.. code-block:: none
3243

33-
Now authenticate using the MongoDB URI. GSSAPI authenticates against the
34-
$external virtual database so you do not have to specify a database in the
35-
URI:
44+
$ kinit [email protected]
45+
[email protected]'s Password:
46+
$ klist
47+
Credentials cache: FILE:/tmp/krb5cc_1000
48+
Principal: [email protected]
49+
50+
Issued Expires Principal
51+
Feb 9 13:48:51 2013 Feb 9 23:48:51 2013 krbtgt/[email protected]
52+
53+
After obtaining a ticket-granting ticket, call the ``MongoClient`` constructor, passing
54+
the MongoDB URI as an argument. The URI must contain the URL-encoded Kerberos principal
55+
and the ``authMechanism=GSSAPI`` as a parameter.
3656

3757
.. code-block:: python
3858

@@ -42,76 +62,80 @@ URI:
4262
>>> client = MongoClient(uri)
4363
>>>
4464

45-
The default service name used by MongoDB and PyMongo is ``mongodb``. You can
46-
specify a custom service name with the ``authMechanismProperties`` option:
65+
.. note::
66+
67+
You don't need to include a database in the MongoDB URI. GSSAPI authenticates against
68+
the ``$external`` virtual database.
69+
70+
By default, MongoDB uses ``mongodb`` as the authentication service name. To specify a
71+
different service name, add the ``authMechanismProperties`` parameter to your MongoDB
72+
URI, as shown in the following example:
4773

4874
.. code-block:: python
75+
:emphasize-lines: 2
4976

50-
>>> from pymongo import MongoClient
51-
>>> uri = "mongodb://mongodbuser%[email protected]/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:myservicename"
52-
>>> client = MongoClient(uri)
77+
>>> from pymongo import MongoClient
78+
>>> uri = "mongodb://mongodbuser%[email protected]/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:myservicename"
79+
>>> client = MongoClient(uri)
5380

5481
Windows (SSPI)
5582
~~~~~~~~~~~~~~
56-
.. versionadded:: 3.3
5783

58-
First install the `winkerberos`_ module. Unlike authentication on Unix kinit is
59-
not used. If the user to authenticate is different from the user that owns the
60-
application process provide a password to authenticate:
84+
First, install the `winkerberos <https://pypi.python.org/pypi/winkerberos/>`__ module.
85+
You can then call the ``MongoClient()`` constructor, passing in your MongoDB URI. The
86+
URI must include the principal name and ``authMechanism=GSSAPI`` parameter.
87+
If the user to authenticate is different from the user that owns the
88+
application process, you must also provide the authenticating user's password.
6189

6290
.. code-block:: python
6391

64-
>>> uri = "mongodb://mongodbuser%40EXAMPLE.COM:[email protected]/?authMechanism=GSSAPI"
92+
>>> uri = "mongodb://mongodbuser%40EXAMPLE.COM:[email protected]/?authMechanism=GSSAPI"
6593

66-
Two extra ``authMechanismProperties`` are supported on Windows platforms:
94+
Two more ``authMechanismProperties`` are supported on Windows platforms:
6795

68-
- CANONICALIZE_HOST_NAME - Uses the fully qualified domain name (FQDN) of the
69-
MongoDB host for the server principal (GSSAPI libraries on Unix do this by
70-
default):
96+
- **CANONICALIZE_HOST_NAME**: whether to use the fully qualified domain name (FQDN) of the
97+
MongoDB host for the server principal. (GSSAPI libraries on Unix do this by
98+
default).
7199

72100
.. code-block:: python
73101

74-
>>> uri = "mongodb://mongodbuser%[email protected]/?authMechanism=GSSAPI&authMechanismProperties=CANONICALIZE_HOST_NAME:true"
102+
>>> uri = "mongodb://mongodbuser%[email protected]/?authMechanism=GSSAPI&authMechanismProperties=CANONICALIZE_HOST_NAME:true"
75103

76-
- SERVICE_REALM - This is used when the user's realm is different from the service's realm:
104+
- **SERVICE_REALM**: specifies the realm of the service. Use this option when the user's
105+
realm is different from the service's realm.
77106

78107
.. code-block:: python
79108

80-
>>> uri = "mongodb://mongodbuser%[email protected]/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_REALM:otherrealm"
81-
82-
83-
.. _kerberos: http://pypi.python.org/pypi/kerberos
84-
.. _pykerberos: https://pypi.python.org/pypi/pykerberos
85-
.. _winkerberos: https://pypi.python.org/pypi/winkerberos/
109+
>>> uri = "mongodb://mongodbuser%[email protected]/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_REALM:otherrealm"
86110

87111
.. _sasl_plain:
88112

89113
SASL PLAIN (RFC 4616)
90114
---------------------
91-
.. versionadded:: 2.6
92115

93-
MongoDB Enterprise Edition version 2.6 and newer support the SASL PLAIN
94-
authentication mechanism, initially intended for delegating authentication
95-
to an LDAP server. Using the PLAIN mechanism is very similar to MONGODB-CR.
96-
These examples use the $external virtual database for LDAP support:
116+
To authenticate with the PLAIN Simple Authentication and Security Layer (SASL), include
117+
``authMechanism=PLAIN`` as a parameter in your MongoDB URI:
97118

98119
.. code-block:: python
99120

100121
>>> from pymongo import MongoClient
101122
>>> uri = "mongodb://user:[email protected]/?authMechanism=PLAIN"
102123
>>> client = MongoClient(uri)
103-
>>>
104124

105-
SASL PLAIN is a clear-text authentication mechanism. We **strongly** recommend
106-
that you connect to MongoDB using TLS/SSL with certificate validation when
107-
using the SASL PLAIN mechanism:
125+
SASL PLAIN is a clear-text authentication mechanism. We strongly recommend
126+
that you use TLS/SSL with certificate validation when using the SASL PLAIN mechanism
127+
to connect to MongoDB. The following example shows how to enable TLS and certificate
128+
validation when you construct a ``MongoClient`` object:
108129

109130
.. code-block:: python
110131

111-
>>> from pymongo import MongoClient
112-
>>> uri = "mongodb://user:[email protected]/?authMechanism=PLAIN"
113-
>>> client = MongoClient(uri,
114-
... tls=True,
115-
... tlsCertificateKeyFile='/path/to/client.pem',
116-
... tlsCAFile='/path/to/ca.pem')
117-
>>>
132+
>>> from pymongo import MongoClient
133+
>>> uri = "mongodb://user:[email protected]/?authMechanism=PLAIN"
134+
>>> client = MongoClient(uri,
135+
... tls=True,
136+
... tlsCertificateKeyFile='/path/to/client.pem',
137+
... tlsCAFile='/path/to/ca.pem')
138+
139+
.. note::
140+
141+
The code examples in this section use the ``$external`` virtual database for LDAP support.

0 commit comments

Comments
 (0)