/
kerberos.txt
206 lines (150 loc) · 6.82 KB
/
kerberos.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
=======================
Kerberos Authentication
=======================
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
.. versionadded:: 2.4
Overview
--------
MongoDB Enterprise provides support for Kerberos authentication of
MongoDB clients to :binary:`~bin.mongod` and :binary:`~bin.mongos`. Kerberos is
an industry standard authentication protocol for large client/server
systems. Kerberos allows MongoDB and applications to take advantage of
existing authentication infrastructure and processes.
Kerberos Components and MongoDB
-------------------------------
Principals
~~~~~~~~~~
In a Kerberos-based system, every participant in the authenticated
communication is known as a "principal", and every principal must have
a unique name.
Principals belong to administrative units called *realms*. For each
realm, the Kerberos Key Distribution Center (KDC) maintains a database
of the realm's principal and the principals' associated "secret keys".
For a client-server authentication, the client requests from the KDC a
"ticket" for access to a specific asset. KDC uses the client's
secret and the server's secret to construct the ticket which allows the
client and server to mutually authenticate each other, while keeping
the secrets hidden.
For the configuration of MongoDB for Kerberos support, two kinds of
principal names are of interest: :ref:`user principals
<kerberos-user-principal>` and :ref:`service principals
<kerberos-service-principal>`.
.. _kerberos-user-principal:
User Principal
``````````````
To authenticate using Kerberos, you must add the Kerberos user
principals to MongoDB to the ``$external`` database. User principal
names have the form:
.. code-block:: none
<username>@<KERBEROS REALM>
For every user you want to authenticate using Kerberos, you must create
a corresponding user in MongoDB in the ``$external`` database.
For examples of adding a user to MongoDB as well as authenticating as
that user, see
:doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication`
and
:doc:`/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication`.
.. seealso:: :ref:`user-management-guide` for
general information regarding creating and managing users in
MongoDB.
.. _kerberos-service-principal:
Service Principal
`````````````````
Every MongoDB :binary:`~bin.mongod` and :binary:`~bin.mongos` instance (or
:binary:`~bin.mongod.exe` or :binary:`~bin.mongos.exe` on Windows) must have an
associated service principal. Service principal names have the form:
.. code-block:: none
<service>/<fully qualified domain name>@<KERBEROS REALM>
For MongoDB, the ``<service>`` defaults to ``mongodb``. For example, if
``m1.example.com`` is a MongoDB server, and ``example.com`` maintains
the ``EXAMPLE.COM`` Kerberos realm, then ``m1`` should have the service
principal name ``mongodb/m1.example.com@EXAMPLE.COM``.
To specify a different value for ``<service>``, use
:setting:`~security.sasl.serviceName` during the start up of :binary:`~bin.mongod` or
:binary:`~bin.mongos` (or :binary:`~bin.mongod.exe` or :binary:`~bin.mongos.exe`).
:binary:`~bin.mongo` shell or other clients may also specify a different
service principal name using :setting:`~security.sasl.serviceName`.
Service principal names must be reachable over the network using the
fully qualified domain name (FQDN) part of its service principal name.
By default, Kerberos attempts to identify hosts using the
``/etc/krb5.conf`` file before using DNS to resolve hosts.
On Windows, if running MongoDB as a service, see
:ref:`assign-service-principal-name`.
.. _keytab-files:
Linux Keytab Files
~~~~~~~~~~~~~~~~~~
Linux systems can store Kerberos authentication keys for a
:ref:`service principal <kerberos-service-principal>` in *keytab*
files. Each Kerberized :binary:`~bin.mongod` and :binary:`~bin.mongos` instance
running on Linux must have access to a keytab file containing keys for
its :ref:`service principal <kerberos-service-principal>`.
To keep keytab files secure, use file permissions that restrict access
to only the user that runs the :binary:`~bin.mongod` or :binary:`~bin.mongos`
process.
.. _linux-init-mongodb-clients:
Tickets
~~~~~~~
On Linux, MongoDB clients can use Kerberos's ``kinit`` program to
initialize a credential cache for authenticating the user principal to
servers.
Windows Active Directory
~~~~~~~~~~~~~~~~~~~~~~~~
Unlike on Linux systems, :binary:`~bin.mongod` and :binary:`~bin.mongos`
instances running on Windows do not require access to keytab files.
Instead, the :binary:`~bin.mongod` and :binary:`~bin.mongos` instances read
their server credentials from a credential store specific to the
operating system.
However, from the Windows Active Directory, you can export a keytab
file for use on Linux systems. See `Ktpass
<http://technet.microsoft.com/en-us/library/cc753771.aspx>`_ for more
information.
Authenticate With Kerberos
~~~~~~~~~~~~~~~~~~~~~~~~~~
To configure MongoDB for Kerberos support and authenticate, see
:doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication`
and
:doc:`/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication`.
Operational Considerations
--------------------------
The HTTP Console
~~~~~~~~~~~~~~~~
The MongoDB :ecosystem:`HTTP Console
</tools/http-interfaces/#http-console>` interface does not support
Kerberos authentication.
DNS
~~~
Each host that runs a :binary:`~bin.mongod` or :binary:`~bin.mongos` instance
must have both ``A`` and ``PTR`` DNS records to provide forward and
reverse lookup.
Without ``A`` and ``PTR`` DNS records, the host cannot resolve the
components of the Kerberos domain or the Key Distribution Center (KDC).
System Time Synchronization
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To successfully authenticate, the system time for each
:binary:`~bin.mongod` and :binary:`~bin.mongos` instance must be within
5 minutes of the system time of the other hosts in the Kerberos
infrastructure.
Kerberized MongoDB Environments
-------------------------------
.. _kerberos-and-drivers:
Driver Support
~~~~~~~~~~~~~~
The following MongoDB drivers support Kerberos authentication:
- :ecosystem:`Java </tutorial/authenticate-with-java-driver/>`
- :ecosystem:`C# </tutorial/authenticate-with-csharp-driver/>`
- :ecosystem:`C++ </tutorial/authenticate-with-cpp-driver/>`
- `Python <http://api.mongodb.org/python/current/examples/authentication.html>`_
Use with Additional MongoDB Authentication Mechanism
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Although MongoDB supports the use of Kerberos authentication with other
authentication mechanisms, only add the other mechanisms as necessary.
See the ``Incorporate Additional Authentication Mechanisms`` section in
:doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication`
and
:doc:`/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication`
for details.