Skip to content

Commit 80e62ca

Browse files
shuangelashuangela
authored
DOCSP-52562-convert-composable-tutorial (#13660)
* composable * add leading sentence * fix steps * fix bullets * mw feedback * create include
1 parent 139c6cb commit 80e62ca

File tree

5 files changed

+229
-197
lines changed

5 files changed

+229
-197
lines changed

‎content/pymongo-driver/upcoming/snooty.toml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,3 +49,12 @@ value = """
4949
To discover its features and learn more, see the `{+django-odm+} documentation <{+django-docs+}>`__. \
5050
To learn more about preview release considerations, see `Preview Features <https://www.mongodb.com/docs/preview-features/>`__.
5151
"""
52+
53+
[[composables]]
54+
id = "operating-system"
55+
title = "Operating System"
56+
default = "unix"
57+
options = [
58+
{id = "unix", title = "Unix"},
59+
{id = "windows-sspi", title = "Windows (SSPI)"},
60+
]

‎content/pymongo-driver/upcoming/source/includes/authentication/kerberos-intro.rst‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
Overview
2+
--------
3+
4+
The Generic Security Services API (GSSAPI) authentication mechanism allows you to
5+
use your principal name to authenticate to a Kerberos service.
6+
You can use this mechanism only when authenticating to MongoDB Enterprise Advanced.
7+
8+
Code Placeholders
9+
~~~~~~~~~~~~~~~~~
10+
11+
The code examples on this page use the following placeholders:
12+
13+
- ``<username>``: Your :wikipedia:`URL-encoded <Percent-encoding>` principal name. For
14+
example: ``"username%40REALM.ME"``
15+
- ``<password>``: Your Kerberos user's password.
16+
- ``<hostname>``: The network address of your MongoDB deployment.
17+
- ``<port>``: The port number of your MongoDB deployment. If you omit this parameter,
18+
the driver uses the default port number (``27017``).
19+
20+
To use the code examples on this page, replace these placeholders with your own values.
21+
22+
.. include:: /includes/authentication/percent-encoding.rst

‎content/pymongo-driver/upcoming/source/includes/authentication/unix-kerberos.rst‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
.. include:: /includes/authentication/kerberos-intro.rst
2+
3+
Using GSSAPI Authentication in Your Application
4+
-----------------------------------------------
5+
6+
To use GSSAPI authentication in your application, follow the steps below.
7+
8+
1. Use pip or easy_install to install the Python
9+
`kerberos <http://pypi.python.org/pypi/kerberos>`__ or
10+
`pykerberos <https://pypi.python.org/pypi/pykerberos>`__ module.
11+
12+
#. Run the ``kinit`` command to obtain and cache
13+
an initial ticket-granting ticket. The following example uses the
14+
``kinit`` command to obtain a ticket-granting ticket for the principal
15+
``mongodbuser@EXAMPLE.COM``. It then uses the ``klist``
16+
command to display the principal and ticket in the credentials cache.
17+
18+
.. code-block:: sh
19+
:copyable: false
20+
21+
$ kinit mongodbuser@EXAMPLE.COM
22+
mongodbuser@EXAMPLE.COM's Password:
23+
$ klist
24+
Credentials cache: FILE:/tmp/krb5cc_1000
25+
Principal: mongodbuser@EXAMPLE.COM
26+
27+
Issued Expires Principal
28+
Feb 9 13:48:51 2013 Feb 9 23:48:51 2013 krbtgt/mongodbuser@EXAMPLE.COM
29+
30+
#. After you obtain a ticket-granting ticket, set the following connection options:
31+
32+
- ``username``: The Kerberos principal to authenticate. Percent-encode this value
33+
before including it in a connection URI.
34+
- ``authMechanism``: Set to ``"GSSAPI"``.
35+
- ``authMechanismProperties``: Optional. By default, MongoDB uses ``mongodb`` as
36+
the authentication service name. To specify a different service name, set
37+
this option to ``"SERVICE_NAME:<authentication service name>"``.
38+
39+
You can set these options in two ways: by passing arguments to the
40+
``MongoClient`` constructor or through parameters in your connection
41+
string. Select the tab that corresponds to your connection method to learn how
42+
to set connection options.
43+
44+
.. include:: /includes/authentication/auth-properties-commas.rst
45+
46+
.. tabs::
47+
48+
.. tab:: MongoClient
49+
:tabid: mongoclient
50+
51+
.. code-block:: python
52+
53+
client = pymongo.MongoClient("mongodb://<hostname>:<port>",
54+
username="mongodbuser@EXAMPLE.COM",
55+
authMechanism="GSSAPI",
56+
authMechanismProperties="SERVICE_NAME:<authentication service name>")
57+
58+
.. tab:: Connection String
59+
:tabid: connectionstring
60+
61+
.. code-block:: python
62+
63+
uri = ("mongodb://mongodbuser%40EXAMPLE.COM@<hostname>:<port>/?"
64+
"&authMechanism=GSSAPI"
65+
"&authMechanismProperties=SERVICE_NAME:<authentication service name>")
66+
client = pymongo.MongoClient(uri)
67+
68+
.. tab:: MongoClient (Asynchronous)
69+
:tabid: mongoclient-async
70+
71+
.. code-block:: python
72+
73+
client = pymongo.AsyncMongoClient("mongodb://<hostname>:<port>",
74+
username="mongodbuser@EXAMPLE.COM",
75+
authMechanism="GSSAPI",
76+
authMechanismProperties="SERVICE_NAME:<authentication service name>")
77+
78+
.. tab:: Connection String (Asynchronous)
79+
:tabid: connectionstring-async
80+
81+
.. code-block:: python
82+
83+
uri = ("mongodb://mongodbuser%40EXAMPLE.COM@<hostname>:<port>/?"
84+
"&authMechanism=GSSAPI"
85+
"&authMechanismProperties=SERVICE_NAME:<authentication service name>")
86+
client = pymongo.AsyncMongoClient(uri)
87+
88+
API Documentation
89+
-----------------
90+
91+
To learn more about using authentication mechanisms with {+driver-short+},
92+
see the following API documentation:
93+
94+
- `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__

‎content/pymongo-driver/upcoming/source/includes/authentication/windows-sspi-kerberos.rst‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
.. include:: /includes/authentication/kerberos-intro.rst
2+
3+
Using GSSAPI Authentication in Your Application
4+
-----------------------------------------------
5+
6+
To use GSSAPI authentication in your application, follow the steps below.
7+
8+
1. Install the `winkerberos <https://pypi.python.org/pypi/winkerberos/>`__ module.
9+
#. Set the following connection options:
10+
11+
- ``username``: The Kerberos principal to authenticate. Percent-encode this value before including
12+
it in a connection URI.
13+
- ``authMechanism``: Set to ``"GSSAPI"``.
14+
- ``password``: Optional. If the user to authenticate is different from the user
15+
that owns the application process, set this option to the authenticating user's
16+
password.
17+
- ``authMechanismProperties``: Optional. This option includes multiple
18+
authentication properties. To specify more than one of the following properties,
19+
use a comma-delimited list.
20+
21+
- ``SERVICE_NAME``: By default, MongoDB uses ``mongodb`` as
22+
the authentication service name. Use this option to specify a different service name.
23+
- ``CANONICALIZE_HOST_NAME``: Whether to use the fully qualified domain name (FQDN)
24+
of the MongoDB host for the server principal.
25+
- ``SERVICE_REALM``: The service realm. Use this option when the user's
26+
realm is different from the service's realm.
27+
28+
You can set these options in two ways: by passing arguments to the
29+
``MongoClient`` constructor or through parameters in your connection string. Select the tab that corresponds to your connection method to learn how
30+
to set connection options.
31+
32+
.. tabs::
33+
34+
.. tab:: MongoClient
35+
:tabid: mongoclient
36+
37+
.. code-block:: python
38+
39+
client = pymongo.MongoClient("mongodb://<hostname>:<port>",
40+
username="mongodbuser@EXAMPLE.COM",
41+
authMechanism="GSSAPI",
42+
password="<user password>",
43+
authMechanismProperties="SERVICE_NAME:<authentication service name>,
44+
CANONICALIZE_HOST_NAME:true,
45+
SERVICE_REALM:<service realm>")
46+
47+
.. tab:: Connection String
48+
:tabid: connectionstring
49+
50+
.. code-block:: python
51+
52+
uri = ("mongodb://mongodbuser%40EXAMPLE.COM:<percent-encoded user password>"
53+
"@<hostname>:<port>/?"
54+
"&authMechanism=GSSAPI"
55+
"&authMechanismProperties="
56+
"SERVICE_NAME:<authentication service name>,"
57+
"CANONICALIZE_HOST_NAME:true,"
58+
"SERVICE_REALM:<service realm>")
59+
client = pymongo.MongoClient(uri)
60+
61+
.. tab:: MongoClient (Asynchronous)
62+
:tabid: mongoclient-async
63+
64+
.. code-block:: python
65+
66+
client = pymongo.AsyncMongoClient("mongodb://<hostname>:<port>",
67+
username="mongodbuser@EXAMPLE.COM",
68+
authMechanism="GSSAPI",
69+
password="<user password>",
70+
authMechanismProperties="SERVICE_NAME:<authentication service name>,
71+
CANONICALIZE_HOST_NAME:true,
72+
SERVICE_REALM:<service realm>")
73+
74+
.. tab:: Connection String (Asynchronous)
75+
:tabid: connectionstring-async
76+
77+
.. code-block:: python
78+
79+
uri = ("mongodb://mongodbuser%40EXAMPLE.COM:<percent-encoded user password>"
80+
"@<hostname>:<port>/?"
81+
"&authMechanism=GSSAPI"
82+
"&authMechanismProperties="
83+
"SERVICE_NAME:<authentication service name>,"
84+
"CANONICALIZE_HOST_NAME:true,"
85+
"SERVICE_REALM:<service realm>")
86+
client = pymongo.AsyncMongoClient(uri)
87+
88+
API Documentation
89+
-----------------
90+
91+
To learn more about using authentication mechanisms with {+driver-short+},
92+
see the following API documentation:
93+
94+
- `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__

0 commit comments

Comments
 (0)