Skip to content

Commit 2429947

Browse files
kayayaraipsionnKaylyn
authored
DOCS-1126 draft auth mapping UI docs (DataDog#8164)
* DOCS-1126 draft auth mapping UI docs * DOCS-1126 add screen cap * DOCS-1126 add screen cap * Note about 'bouncing' users without mapping * small reword * feedback Co-authored-by: Kaylyn <kaylyn.sigler@datadoghq.com> * change important note Co-authored-by: Ali Sajjadi <github@artificialsanity.net> Co-authored-by: Kaylyn <kaylyn.sigler@datadoghq.com>
1 parent b3afe0b commit 2429947

File tree

4 files changed

+61
-27
lines changed

4 files changed

+61
-27
lines changed

‎content/en/account_management/authn_mapping/_index.md

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ If you are using Federated Authentication mechanisms, this API allows you to aut
1414

1515
**Note**: If you are a SAML user, and you have been using the existing beta Federated Mapping mechanism (`roles_v2_saml`), Datadog strongly recommends that you transition to using this API.
1616

17+
You can also create and manage mappings in the Datadog app UI, on the **Mappings** tab in User Management. See [Mapping SAML attributes to Datadog roles][1] for more information.
18+
1719
## Requests
1820

1921
{{< site-region region="us" >}}
@@ -43,7 +45,7 @@ Create a new AuthN Mapping from a JSON body. Returns the newly created AuthN Map
4345

4446
* **`role["data"]["id"]`** [*required*, no default]:
4547
The `ID` of the Role to map to. The Roles API can be used to create and manage Datadog roles, what global permissions they grant, and which users belong to them.
46-
**Note**: This attribute should be presented as part of a `role` relationship block in requests. See the example below for more details. When you create a Role, it is assigned an ID. For more information about finding the `ID` for the role you want to map to, see the [Role API documentation][1].
48+
**Note**: This attribute should be presented as part of a `role` relationship block in requests. See the example below for more details. When you create a Role, it is assigned an ID. For more information about finding the `ID` for the role you want to map to, see the [Role API documentation][2].
4749
* **`attributes["attribute_key"]`** [*required*, no default]:
4850
The `attribute_key` is the key portion of a key/value pair that represents an attribute sent from your Identity Provider. You can define these for your own use case. For example, `attribute_key` could be `member-of` and the `attribute_value` could be `Development`.
4951
* **`attributes["attribute_value"]`** [*required*, no default]:
@@ -420,7 +422,7 @@ Updates the AuthN Mapping `role`, `saml_assertion_attribute_id`, or both from a
420422
Replace `{authn_mapping_id}` with the ID of the AuthN Mapping you want to update. This is required in both the path of the request and the body of the request.
421423
* **`role["data"]["id"]`** [*optional*, *default*=none]:
422424
The `ID` of the Role to map to. The Roles API can be used to create and manage Datadog roles, what global permissions they grant, and which users belong to them.
423-
**Note**: This attribute should be presented as part of a `role` relationship block in requests. See the example below for more details. When you create a Role, it is assigned an ID. For more information about finding the `ID` for the role you want to map to, see the [Role API documentation][1].
425+
**Note**: This attribute should be presented as part of a `role` relationship block in requests. See the example below for more details. When you create a Role, it is assigned an ID. For more information about finding the `ID` for the role you want to map to, see the [Role API documentation][2].
424426
* **`attributes["attribute_key"]`** [*optional*, *default*=none]:
425427
The `attribute_key` is the key portion of a key/value pair that represents an attribute sent from your Identity Provider. You can define these for your own use case. For example, `attribute_key` could be `member-of` and the `attribute_value` could be `Development`.
426428
* **`attributes["attribute_value"]`** [*optional*, *default*=none]:
@@ -755,4 +757,5 @@ Replace the `<YOUR_DATADOG_API_KEY>` and `<YOUR_DATADOG_APPLICATION_KEY>` placeh
755757

756758
{{< partial name="whats-next/whats-next.html" >}}
757759

758-
[1]: /api/v2/roles/#list-roles
760+
[1]: /account_management/saml/#mapping-saml-attributes-to-datadog-roles
761+
[2]: /api/v2/roles/#list-roles

‎content/en/account_management/rbac/_index.md

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -17,27 +17,32 @@ further_reading:
1717
- link: '/account_management/rbac/permissions'
1818
tag: 'Documentation'
1919
text: 'Discover the list of permissions available.'
20+
- link: '/account_management/saml/'
21+
tag: 'Documentation'
22+
text: 'Enable single sign on with SAML'
2023
---
2124

2225
Roles categorize users and define what account permissions those users have, such as what data they can read or what account assets they can modify. By default, Datadog offers three roles, and you can create [custom roles](#custom-roles) so you can define a better mapping between your users and their permissions.
2326

2427
By granting permissions to roles, any user who is associated with that role receives that permission. When users are associated with multiple roles, they receive all the permissions granted to each of their roles. The more roles a user is associated with, the more access they have within a Datadog account.
2528

29+
**Note** If you use a SAML identity provider, you can integrate it with Datadog for authentication, and you can map identity attributes to Datadog default and custom roles. For more information, see [Single Sign On With SAML][1].
30+
2631
## Datadog Default Roles
2732

2833
| Role | Description |
2934
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
30-
| **Datadog Admin Role** | Users have access to billing information and the ability to revoke API keys. They can manage users and configure [read-only dashboards][1]. They can also promote standard users to administrators. |
31-
| **Datadog Standard Role** | Users are allowed to view and modify all monitoring features that Datadog offers, such as [dashboards][1], [monitors][2], [events][3], and [notebooks][4]. Standard users can also invite other users to organizations. |
32-
| **Datadog Read Only Role** | Users do not have access to edit within Datadog. This comes in handy when you'd like to share specific read-only views with a client, or when a member of one business unit needs to share a [dashboard][1] with someone outside their unit. |
35+
| **Datadog Admin Role** | Users have access to billing information and the ability to revoke API keys. They can manage users and configure [read-only dashboards][2]. They can also promote standard users to administrators. |
36+
| **Datadog Standard Role** | Users are allowed to view and modify all monitoring features that Datadog offers, such as [dashboards][2], [monitors][3], [events][4], and [notebooks][5]. Standard users can also invite other users to organizations. |
37+
| **Datadog Read Only Role** | Users do not have access to edit within Datadog. This comes in handy when you'd like to share specific read-only views with a client, or when a member of one business unit needs to share a [dashboard][2] with someone outside their unit. |
3338

3439
## Custom Roles
3540

3641
<div class="alert alert-warning">
3742
Creating and modifying custom roles is an Enterprise feature and is in private beta. <a href="/help">Contact Datadog support</a> to get it enabled for your account.
3843
</div>
3944

40-
Manage your custom roles through the Datadog application, the [Datadog Role API][5], or SAML directly. Find below how to create, update, delete a role. See the [Datadog Role permissions][6] documentation for more information about available permissions.
45+
Manage your custom roles through the Datadog application, the [Datadog Role API][6], or SAML directly. Find below how to create, update, delete a role. See the [Datadog Role permissions][7] documentation for more information about available permissions.
4146

4247
### Create a custom role
4348

@@ -133,9 +138,10 @@ Find an example of how to delete a Role in the [Datadog Create Role API document
133138

134139
{{< partial name="whats-next/whats-next.html" >}}
135140

136-
[1]: /dashboards/
137-
[2]: /monitors/
138-
[3]: /events/
139-
[4]: /notebooks/
140-
[5]: /api/v2/roles/
141-
[6]: /account_management/rbac/permissions/
141+
[1]: /account_management/saml/
142+
[2]: /dashboards/
143+
[3]: /monitors/
144+
[4]: /events/
145+
[5]: /notebooks/
146+
[6]: /api/v2/roles/
147+
[7]: /account_management/rbac/permissions/

‎content/en/account_management/saml/_index.md

Lines changed: 39 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,30 @@ The Single Sign-on URL is also displayed on the [Team page][6]. Loading this URL
4545

4646
**Note**: If you want to configure SAML for a multi-org, see the [multi-org documentation][7].
4747

48+
## Mapping SAML attributes to Datadog roles
49+
50+
You can assign or remove Datadog roles based on a user's SAML-assigned attributes:
51+
52+
1. Go to Account Management and click the Mappings tab.
53+
54+
2. Click the **New Mapping** button.
55+
56+
3. Specify the SAML identity provider key-value pair that you want to associate with an existing Datadog role (either default or custom). For example, if you want all users whose `member_of` attribute has a value of `Development` to be assigned to a custom Datadog role called `Devs`:
57+
58+
{{< img src="account_management/saml/create_mapping.png" alt="Creating a SAML mapping to Datadog Role" >}}
59+
60+
4. If you have not already done so, enable mappings by clicking **Enable Mappings**.
61+
62+
When a user logs in who has the specified identity provider attribute, they will automatically be assigned the Datadog role. Likewise, if someone has that identity provider attribute removed, they will also lose access to the role (unless another mapping adds it).
63+
64+
<div class="alert alert-warning">
65+
Important: If a user does _not_ match any mapping, they lose any roles they had previously, and are prevented from logging into the org with SAML. Double-check your mapping definitions.
66+
</div>
67+
68+
You can make changes to a mapping by clicking the pencil icon, or remove it by clicking the garbage icon. These actions affect only the mapping, not the identity provider attributes or the Datadog roles.
69+
70+
Alternatively, you can create and change mappings of SAML attributes to Datadog roles by using the `authn_mappings` endpoint. See [Federated Authentication to Role Mapping API][8] for more information.
71+
4872
## Datadog Service Provider Details
4973

5074
* Datadog supports the **HTTP-POST** binding for **SAML2**:
@@ -84,13 +108,13 @@ If **sn** and **givenName** are provided, they are used to update the user's nam
84108

85109
For more information about configuring specific IdP's, refer to the following documentation:
86110

87-
* [Active Directory][8]
88-
* [Auth0][9]
89-
* [Azure][10]
90-
* [Google][11]
91-
* [NoPassword][12]
92-
* [Okta][13]
93-
* [SafeNet][14]
111+
* [Active Directory][9]
112+
* [Auth0][10]
113+
* [Azure][11]
114+
* [Google][12]
115+
* [NoPassword][13]
116+
* [Okta][14]
117+
* [SafeNet][15]
94118

95119
## Additional Features
96120

@@ -129,10 +153,11 @@ With SAML Strict mode enabled, all users must log in with SAML. An existing user
129153
[5]: https://app.datadoghq.com/account/saml/metadata.xml
130154
[6]: https://app.datadoghq.com/account/team
131155
[7]: /account_management/multi_organization/#setting-up-saml
132-
[8]: /account_management/saml/activedirectory/
133-
[9]: /account_management/saml/auth0/
134-
[10]: /account_management/saml/azure/
135-
[11]: /account_management/saml/google/
136-
[12]: /account_management/saml/nopassword/
137-
[13]: /account_management/saml/okta/
138-
[14]: /account_management/saml/safenet/
156+
[8]: /account_management/authn_mapping/
157+
[9]: /account_management/saml/activedirectory/
158+
[10]: /account_management/saml/auth0/
159+
[11]: /account_management/saml/azure/
160+
[12]: /account_management/saml/google/
161+
[13]: /account_management/saml/nopassword/
162+
[14]: /account_management/saml/okta/
163+
[15]: /account_management/saml/safenet/

‎static/images/account_management/saml/create_mapping.png

36 KB
Loading

0 commit comments

Comments
 (0)