Skip to content

Commit 12625a2

Browse files
mcmorisimcmorisi
authored
Merge pull request #127 from mcmorisi/DOCSP-45209-authentication
DOCSP-45209: Authentication landing + Authentication mechanisms
2 parents 6885e67 + 582daa8 commit 12625a2

File tree

10 files changed

+799
-1
lines changed

10 files changed

+799
-1
lines changed

‎snooty.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ toc_landing_pages = [
44
"/get-started",
55
"/connect",
66
"/write",
7-
"/indexes"
7+
"/indexes",
8+
"/security/authentication"
89
]
910

1011
intersphinx = ["https://www.mongodb.com/docs/manual/objects.inv"]

‎source/includes/authentication/aws-iam.rb

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
require 'bundler/inline'
2+
gemfile do
3+
source 'https://rubygems.org'
4+
gem 'mongo'
5+
end
6+
7+
# start-aws
8+
client = Mongo::Client.new(['<host>'],
9+
auth_mech: :aws,
10+
user: '<aws_access_key_id>',
11+
password: '<aws_secret_access_key>')
12+
# end-aws
13+
14+
# start-aws-connection-string
15+
client = Mongo::Client.new(
16+
'mongodb://<aws_access_key_id>:<aws_secret_access_key>@host/?authMechanism=MONGODB-AWS')
17+
# end-aws-connection-string
18+
19+
# start-aws-temp
20+
client = Mongo::Client.new(['<host>'],
21+
auth_mech: :aws,
22+
user: '<aws_access_key_id>',
23+
password: '<aws_secret_access_key>',
24+
auth_mech_properties: {
25+
aws_session_token: '<<aws_session_token>>',
26+
})
27+
# end-aws-temp
28+
29+
# start-aws-temp-connection-string
30+
client = Mongo::Client.new(
31+
'mongodb://<aws_access_key_id>:<aws_secret_access_key>@host/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<<aws_session_token>>')
32+
# end-aws-temp-connection-string
33+
34+
# start-aws-automatic-retrieval
35+
client = Mongo::Client.new(['<hostname>'],
36+
auth_mech: :aws)
37+
)
38+
# end-aws-automatic-retrieval
39+
40+
# start-aws-automatic-retrieval-connection-string
41+
client = Mongo::Client.new(
42+
'mongodb://host/?authMechanism=MONGODB-AWS')
43+
# end-aws-automatic-retrieval-connection-string

‎source/index.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
Read Data </read>
1919
Operations on Replica Sets </read-write-pref>
2020
Indexes </indexes>
21+
Security </security>
2122
Data Formats </data-formats>
2223
View the Source <https://github.com/mongodb/mongo-ruby-driver>
2324
API Documentation <{+api-root+}>

‎source/security.txt

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.. _ruby-security:
2+
3+
========
4+
Security
5+
========
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: community, security
19+
20+
.. toctree::
21+
:titlesonly:
22+
23+
Authentication </security/authentication>

‎source/security/auth-mechanisms/aws-iam.txt

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
.. _ruby-authentication-aws:
2+
3+
==================================
4+
AWS Identity and Access Management
5+
==================================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 3
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: amazon web services, code example
19+
20+
Overview
21+
--------
22+
23+
.. note::
24+
25+
AWS authentication is available only in the MongoDB Enterprise Edition for MongoDB 4.4
26+
and later.
27+
28+
The AWS authentication mechanism uses AWS `Identity and Access Management (IAM)
29+
<https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html>`_
30+
and AWS `Security Token Service (STS)
31+
<https://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html>`_
32+
to prove the client's identity to a MongoDB deployment. The following steps describe the
33+
AWS authentication process:
34+
35+
1. The client uses AWS IAM credentials to create a signature that is sent to
36+
the MongoDB deployment.
37+
2. The deployment uses the client's signature to send a request to AWS STS.
38+
3. If the request succeeds, STS returns the Amazon Resource Name (ARN) of
39+
the IAM user or role that corresponds to the client's credentials.
40+
4. The deployment uses the returned ARN to look up the user. The
41+
client is authenticated as this user.
42+
43+
.. note::
44+
45+
The client and server use different usernames. The client uses the AWS access key ID,
46+
but the server uses the ARN of the IAM user or role corresponding to the access key ID.
47+
48+
AWS credentials include the following components:
49+
50+
- Access key ID
51+
- Secret access key
52+
- Optional session token
53+
54+
Authentication with `AWS IAM credentials
55+
<https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html>`__
56+
uses the access key ID and the secret access key. Authentication with
57+
`temporary AWS IAM credentials
58+
<https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html>`__
59+
uses all three components.
60+
61+
.. note::
62+
63+
The driver never sends the secret access key or the session token over
64+
the network.
65+
66+
Temporary credentials are used with:
67+
68+
- STS `Assume Role <https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-api.html>`__
69+
requests.
70+
- `EC2 instance roles <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html>`__.
71+
- `ECS task roles <https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html>`__.
72+
- `AWS Lambda environment <https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html>`__.
73+
- `IAM roles for service accounts <https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html>`__.
74+
75+
Code Placeholders
76+
~~~~~~~~~~~~~~~~~
77+
78+
The code examples on this page use the following placeholders:
79+
80+
- ``<hostname>``: The network address of your MongoDB deployment
81+
- ``<aws-access-key-id>``: The AWS access key ID
82+
- ``<aws_secret_access_key>``: The AWS secret access key
83+
- ``<aws_session_token>``: The AWS session token
84+
85+
Using AWS IAM Authentication in Your Application
86+
------------------------------------------------
87+
88+
The following sections describe how to use the AWS IAM authentication mechanism in your
89+
application.
90+
91+
Providing Credentials Explicitly
92+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
93+
94+
You can provide regular (non-temporary) IAM credentials as client options or by using a URI.
95+
Select the :guilabel:`Connection String` or :guilabel:`Client Options` tab to
96+
see the corresponding syntax:
97+
98+
.. tabs::
99+
100+
.. tab:: Connection String
101+
:tabid: default-connection-string
102+
103+
.. literalinclude:: /includes/authentication/aws-iam.rb
104+
:start-after: start-aws-connection-string
105+
:end-before: end-aws-connection-string
106+
:language: ruby
107+
:copyable:
108+
:dedent:
109+
110+
.. tab:: Client Options
111+
:tabid: default-mongo-credential
112+
113+
.. literalinclude:: /includes/authentication/aws-iam.rb
114+
:start-after: start-aws
115+
:end-before: end-aws
116+
:language: ruby
117+
:copyable:
118+
:dedent:
119+
120+
.. note::
121+
122+
If you provide credentials in a URI, you must percent-encode them.
123+
124+
Providing Temporary Credentials
125+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126+
127+
To provide temporary credentials, specify the session token in the
128+
client options or by using a URI. Select the :guilabel:`Connection String`
129+
or :guilabel:`Client Options` tab to see the corresponding syntax:
130+
131+
.. tabs::
132+
133+
.. tab:: Connection String
134+
:tabid: default-connection-string
135+
136+
.. literalinclude:: /includes/authentication/aws-iam.rb
137+
:start-after: start-aws-temp-connection-string
138+
:end-before: end-aws-temp-connection-string
139+
:language: ruby
140+
:copyable:
141+
:dedent:
142+
143+
.. tab:: Client Options
144+
:tabid: default-mongo-credential
145+
146+
.. literalinclude:: /includes/authentication/aws-iam.rb
147+
:start-after: start-aws-temp
148+
:end-before: end-aws-temp
149+
:language: ruby
150+
:copyable:
151+
:dedent:
152+
153+
Automatically Retrieving Credentials
154+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
155+
156+
The client can retrieve credentials from the environment or from EC2 or ECS
157+
metadata endpoints. To retrieve credentials automatically, specify the
158+
AWS authentication mechanism but do not specify a username or a password. Select the
159+
:guilabel:`Connection String` or :guilabel:`Client Options` tab to see the corresponding syntax:
160+
161+
.. tabs::
162+
163+
.. tab:: Connection String
164+
:tabid: default-connection-string
165+
166+
.. literalinclude:: /includes/authentication/aws-iam.rb
167+
:start-after: start-aws-automatic-retrieval-connection-string
168+
:end-before: end-aws-automatic-retrieval-connection-string
169+
:language: ruby
170+
:copyable:
171+
:dedent:
172+
173+
.. tab:: Client Options
174+
:tabid: default-mongo-credential
175+
176+
.. literalinclude:: /includes/authentication/aws-iam.rb
177+
:start-after: start-aws-automatic-retrieval
178+
:end-before: end-aws-automatic-retrieval
179+
:language: ruby
180+
:copyable:
181+
:dedent:
182+
183+
The driver tries to obtain credentials from the following sources, in
184+
the specified order:
185+
186+
- ``AWS_ACCESS_KEY_ID``, ``AWS_SECRET_ACCESS_KEY`` and ``AWS_SESSION_TOKEN``
187+
environment variables. These environment variables are recognized by
188+
a variety of AWS-related libraries and tools, such as the official
189+
AWS Ruby SDK and the AWS CLI. They are also defined when running in an
190+
AWS Lambda environment.
191+
- AWS STS `AssumeRoleWithWebIdentity action
192+
<https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html>`__.
193+
This mechanism returns credentials associated with the service account token, and
194+
requires the following environment variables to be set:
195+
196+
- ``AWS_WEB_IDENTITY_TOKEN_FILE``: Path to a file containing the service
197+
account token.
198+
- ``AWS_ROLE_ARN``: The Amazon Resource Name (ARN) of the role that the
199+
caller is assuming.
200+
- ``AWS_ROLE_SESSION_NAME`` (optional): Identifier for the assumed role
201+
session. If this variable is empty, the driver generates a random identifier.
202+
203+
- The AWS `ECS task metadata
204+
<https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html>`__ endpoint.
205+
This endpoint returns credentials associated with the ECS task role assigned to
206+
the container.
207+
- The AWS `EC2 instance metadata
208+
<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html>`__ endpoint.
209+
This endpoint returns credentials associated with the EC2 instance role assigned to
210+
the instance.
211+
212+
.. important::
213+
214+
A credentials source must provide a complete
215+
set of credentials. For example, if your application uses the ``AWS_ACCESS_KEY_ID``
216+
and ``AWS_SECRET_ACCESS_KEY`` environment variables, the driver raises an error if only
217+
one of these variables has a value.
218+
219+
.. note::
220+
221+
If an application runs in an ECS container on an EC2 instance and
222+
the container is allowed access to the instance metadata,
223+
the driver attempts to retrieve AWS credentials from the EC2 instance metadata endpoint.
224+
If the driver retrieves credentials in this way, your application can authenticate as the IAM
225+
role assigned to the EC2 instance.
226+
227+
To learn how to prevent containers from accessing EC2 instance metadata,
228+
see the `AWS documentation <https://aws.amazon.com/premiumsupport/knowledge-center/ecs-container-ec2-metadata>`__.
229+
230+
API Documentation
231+
-----------------
232+
233+
To learn more about any of the methods or types discussed on this
234+
page, see the following API documentation:
235+
236+
- `Mongo::Client <{+api-root+}/Mongo/Client.html>`__

0 commit comments

Comments
 (0)