Skip to content

Commit 98ef5db

Browse files
steverensteveren
authored
DOCSP-11447: [mongocli] atlas dbuser describe command (#162)
1 parent 510a3f0 commit 98ef5db

File tree

3 files changed

+244
-3
lines changed

3 files changed

+244
-3
lines changed

‎source/includes/atlas-dbuser-output-fields.rst

Lines changed: 34 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,7 @@
3030
:widths: 20 80
3131

3232
* - ``NONE``
33-
- |service| authenticates this user through
34-
:manual:`SCRAM-SHA </core/security-scram>`, not |ldap|.
33+
- This user does not use |ldap| authentication.
3534
* - ``USER``
3635
- |ldap| server authenticates this user through the user's
3736
|ldap| user.
@@ -41,8 +40,40 @@
4140
group. To learn more about |ldap| security, see
4241
:atlas:`Set up User Authentication and Authorization with
4342
LDAP </security-ldaps>`.
43+
44+
* - ``x509Type``
45+
- Method by which the specified ``username`` is
46+
authenticated. Valid values are:
47+
48+
.. list-table::
49+
:stub-columns: 1
50+
:widths: 20 80
51+
52+
* - ``NONE``
53+
- This user does not use X.509 authentication.
54+
* - ``MANAGED``
55+
- This user authenticates with :atlas:`Atlas-managed X.509 certificates
56+
</security-add-mongodb-users/#database-user-authentication>`.
57+
* - ``CUSTOMER``
58+
- This user authenticates with :atlas:`Self-managed X.509 certificates
59+
</security-self-managed-x509/#self-managed-x509>`.
60+
61+
* - ``awsIAMType``
62+
- Method by which the specified ``username`` is
63+
authenticated. Valid values are:
4464

45-
The default value is ``NONE``.
65+
.. list-table::
66+
:stub-columns: 1
67+
:widths: 20 80
68+
69+
* - ``NONE``
70+
- This user does not use AWS IAM authentication.
71+
* - ``USER``
72+
- This user authenticates with :atlas:`AWS IAM user credentials
73+
</security-add-mongodb-users/#database-user-authentication>`.
74+
* - ``ROLE``
75+
- This user authenticates with :atlas:`AWS IAM role credentials
76+
</security-add-mongodb-users/#database-user-authentication>`.
4677

4778
* - ``roles``
4879
- User's roles and the databases or collections on which the

‎source/reference/atlas/dbuser-commands.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Atlas ``dbuser`` Commands
1010
:titlesonly:
1111

1212
List Database Users </reference/atlas/dbuser-list>
13+
Describe a Database user </reference/atlas/dbuser-describe>
1314
Create a Database User </reference/atlas/dbuser-create>
1415
Modify a Database User </reference/atlas/dbuser-update>
1516
Delete a Database User </reference/atlas/dbuser-delete>

‎source/reference/atlas/dbuser-describe.txt

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
.. _mcli-atlas-dbuser-describe-command:
2+
3+
==============================
4+
mongocli atlas dbuser describe
5+
==============================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
The ``dbuser describe`` command retrieves one MongoDB database user
16+
on the specified |service| cluster. You can also retrieve a MongoDB
17+
database user through the |service| :atlas:`API
18+
</reference/api/database-users-get-single-user/>`.
19+
20+
Syntax
21+
------
22+
23+
.. code-block:: text
24+
25+
mongocli atlas dbuser describe <username>
26+
[ --authDB <auth-db> ]
27+
[ --profile|-P <profile-name> ]
28+
[ --projectId <project-ID> ]
29+
30+
.. include:: /includes/fact-command-line-help.rst
31+
32+
.. _dbuser-atlas-describe-options:
33+
34+
Options
35+
-------
36+
37+
.. list-table::
38+
:header-rows: 1
39+
:widths: 25 10 45 20
40+
41+
* - Option
42+
- Type
43+
- Description
44+
- Required?
45+
46+
* - ``<username>``
47+
- string
48+
- Username of the database user to retrieve.
49+
- yes
50+
51+
* - ``--authDB <auth-db>``
52+
- string
53+
- Authentication database to use. Defaults to ``admin``.
54+
55+
Acceptable values are:
56+
57+
- ``admin`` for users who use :atlas:`password authentication
58+
</security-add-mongodb-users/#database-user-authentication>`.
59+
- ``$external`` for users who authenticate with :atlas:`X.509
60+
certificates </security-add-mongodb-users/#database-user-authentication>`,
61+
:atlas:`LDAP </security-ldaps/>`, or :atlas:`AWS IAM
62+
</security-add-mongodb-users/#database-user-authentication>`.
63+
- no
64+
65+
* - ``--profile``, ``-P``
66+
- string
67+
- Name of the profile where the public and private
68+
keys for the project are saved. If omitted, uses the
69+
{+default-profile+}. To learn more about creating a
70+
profile, see :ref:`mcli-configure`.
71+
- no
72+
73+
* - ``--projectId``
74+
- string
75+
- Unique identifier of the project that contains the
76+
cluster to update. If omitted, uses the project ID in
77+
the profile or :ref:`environment variable <mcli-env-var>`.
78+
- no
79+
80+
.. _dbuser-atlas-describe-command-output:
81+
82+
Output
83+
------
84+
85+
.. include:: /includes/command-output-intro.rst
86+
87+
.. include:: /includes/atlas-dbuser-output-fields.rst
88+
89+
Examples
90+
--------
91+
92+
.. tabs::
93+
94+
tabs:
95+
- id: scram
96+
name: Password Authentication
97+
content: |
98+
The following example uses the ``mongocli atlas dbuser describe`` command to
99+
retrieve a MongoDB database user named ``myDbUser`` on an |service| cluster.
100+
The command uses the {+default-profile+}, which contains the |svc-api-key|\s
101+
and the project ID.
102+
103+
.. code-block:: sh
104+
:copyable: false
105+
106+
mongocli atlas dbuser describe myDbUser --authDB admin
107+
108+
The previous command prints the following fields to the terminal. To
109+
learn more about these fields, see :ref:`Output
110+
<dbuser-atlas-describe-command-output>`.
111+
112+
.. code-block:: json
113+
:copyable: false
114+
115+
{
116+
"databaseName": "admin",
117+
"ldapAuthType": "NONE",
118+
"x509Type": "NONE",
119+
"awsIAMType": "NONE",
120+
"groupId": "5dd5a6b6f10fab1d71a58495",
121+
"roles": [
122+
{
123+
"roleName": "atlasAdmin",
124+
"databaseName": "admin"
125+
}
126+
],
127+
"username": "myDbUser"
128+
}
129+
130+
- id: x509
131+
name: X.509 Certificates
132+
content: |
133+
The following example uses the ``mongocli atlas dbuser describe`` command to
134+
retrieve a MongoDB database user with ``X.509`` authentication on an |service|
135+
cluster. The command uses the {+default-profile+}, which contains the
136+
|svc-api-key|\s and the project ID.
137+
138+
.. note::
139+
140+
When passing ``$external`` as a command line option, prepend it with
141+
a ``\`` character to escape the special-use ``$`` character.
142+
143+
.. code-block:: sh
144+
:copyable: false
145+
146+
mongocli atlas dbuser describe [email protected],OU=users,DC=example,DC=com --authDB \$external
147+
148+
The previous command prints the following fields to the terminal. To
149+
learn more about these fields, see :ref:`Output
150+
<dbuser-atlas-describe-command-output>`.
151+
152+
.. code-block:: json
153+
:copyable: false
154+
155+
{
156+
"databaseName": "admin",
157+
"ldapAuthType": "NONE",
158+
"x509Type": "USER",
159+
"awsIAMType": "NONE",
160+
"groupId": "5dd5a6b6f10fab1d71a58495",
161+
"roles": [
162+
{
163+
"roleName": "atlasAdmin",
164+
"databaseName": "admin"
165+
}
166+
],
167+
"username": "[email protected],OU=users,DC=example,DC=com"
168+
}
169+
170+
- id: aws-iam
171+
name: AWS IAM Authentication
172+
content: |
173+
174+
The following example uses the ``mongocli atlas dbuser describe`` command to
175+
retrieve a MongoDB database user with ``AWS IAM`` authentication on an |service|
176+
cluster. The command uses the {+default-profile+}, which contains the
177+
|svc-api-key|\s and the project ID.
178+
179+
.. note::
180+
181+
When passing ``$external`` as a command line option, prepend it with
182+
a ``\`` character to escape the special-use ``$`` character.
183+
184+
.. code-block:: sh
185+
:copyable: false
186+
187+
mongocli atlas dbuser describe arn:aws:iam::772401394250:user/my-test-user --authDB \$external
188+
189+
The previous command prints the following fields to the terminal. To
190+
learn more about these fields, see :ref:`Output
191+
<dbuser-atlas-describe-command-output>`.
192+
193+
.. code-block:: json
194+
:copyable: false
195+
196+
{
197+
"databaseName": "admin",
198+
"ldapAuthType": "NONE",
199+
"x509Type": "NONE",
200+
"awsIAMType": "USER",
201+
"groupId": "5dd5a6b6f10fab1d71a58495",
202+
"roles": [
203+
{
204+
"roleName": "atlasAdmin",
205+
"databaseName": "admin"
206+
}
207+
],
208+
"username": "arn:aws:iam::772401394250:user/my-test-user"
209+
}

0 commit comments

Comments
 (0)