Add automatic team provisioning instructions (#27413)

* Add automatic team provisioning instructions

* Apply suggestions from code review

Co-authored-by: Nick Moy <[email protected]>

* Add unlinking instructions

* Cleanup

* Add clarifications based on feedback

* Add a period

Co-authored-by: Brett Blue <[email protected]>

* Use more professional screenshots

* Update alt text

---------

Co-authored-by: Nick Moy <[email protected]>
Co-authored-by: Brett Blue <[email protected]>

Author: 3 people

content/en/account_management/scim/_index.md

@@ -25,6 +25,9 @@ The System for Cross-domain Identity Management, or SCIM, is an open standard th
 - Remove users in Datadog when they no longer require access
 - Keep user attributes synchronized between the identity provider and Datadog
 - Single sign-on to Datadog (recommended)
+- Managed Teams: Create Datadog Teams from identity provider groups and keep membership of the Datadog Teams synchronized with group membership in the identity provider.
+
+**Note:** To use managed teams, you must use the Okta IdP and request access to the feature from [support][8].
 
 Datadog supports using SCIM with the Microsoft Entra ID and Okta identity providers. To configure SCIM, see the documentation for your IdP:
 - [Microsoft Entra ID][2]
@@ -63,3 +66,4 @@ Creating a new user with SCIM triggers an email to the user. For first time acce
 [5]: /account_management/api-app-keys
 [6]: /account_management/org_settings/service_accounts
 [7]: https://app.datadoghq.com/organization-settings/users
+[8]: /help/

content/en/account_management/scim/okta.md

@@ -2,6 +2,13 @@
 title: Configure SCIM with Okta
 algolia:
   tags: ["scim", "identity provider", "IdP", "Okta"]
+further_reading:
+    - link: '/account_management/scim/'
+      tag: 'Documentation'
+      text: 'User Provisioning with SCIM'
+    - link: 'account_management/saml/mapping/#map-saml-attributes-to-datadog-roles'
+      tag: 'Documentation'
+      text: 'Group Attribute Mapping'
 ---
 
 See the following instructions to synchronize your Datadog users with Okta using SCIM.
@@ -31,9 +38,9 @@ When using SAML and SCIM together, Datadog strongly recommends disabling SAML ju
 ## Configure automatic user provisioning
 
 1. In the application management screen, select **Provisioning** in the left panel
-2. Click **Configuration API integration**.
+2. Click **Configure API integration**.
 3. Select **Enable API integration**.
-3. Complete the **Credentials** section as follows:
+4. Complete the **Credentials** section as follows:
     - **Base URL**: `https://{{< region-param key="dd_full_site" >}}/api/v2/scim` **Note:** Use the appropriate subdomain for your site. To find your URL, see [Datadog sites][3].
     - **API Token**: Use a valid Datadog application key. You can create an application key on [your organization settings page][4]. To maintain continuous access to your data, use a [service account][5] application key.
 
@@ -47,12 +54,81 @@ When using SAML and SCIM together, Datadog strongly recommends disabling SAML ju
     - **Deactivate Users**
 8. Under **Datadog Attribute Mappings**, find the mapping of Okta attributes to Datadog attributes already pre-configured. You can re-map them if needed, but map the Okta values to the same set of Datadog values.
 
-### Group attributes
+## Configure automatic team provisioning
 
-Group mapping is not supported.
+{{< callout url="/help/" header="false" >}}
+The Managed Teams feature is turned off by default. Request access by contacting support.
+{{< /callout >}}
+
+With [Managed Teams][6], you control the core provisioning of a Datadog Team — its name, handle, and membership — through the identity provider. The setup process differs depending on whether the team already exists in Datadog.
+
+**Note:** Users must exist in Datadog before you can add them to a team. Therefore, you must assign users to the Datadog app in Okta to ensure that they are created in Datadog through SCIM. Assign the Datadog application to your Okta group to ensure that all team members are created in Datadog automatically.
+
+### Create a new team in Datadog
+
+1. In your Datadog application in Okta, navigate to the **Push Groups** tab.
+{{< img src="/account_management/scim/okta/pushed-groups.png" alt="Okta pushed groups configuration interface">}}
+1. Click the **Push Groups** button. The pushed groups interface opens.
+1. Select the Okta group you want to push to Datadog.
+1. In the **Match result & push action** column, ensure **Create group** is selected.
+1. Click **Save**.
+
+To verify that the operation completed successfully, navigate to the [Teams list][7] in Datadog. Search for a Datadog Team matching the Okta group you configured. Verify that the team exists in Datadog and is managed externally. It may take a minute or two before the team appears in Datadog.
+
+{{< img src="/account_management/scim/okta/managed-externally.png" alt="Datadog team list showing a team called Identity team that is managed externally.">}}
+
+### Synchronize an existing Datadog Team with an Okta group
+
+You can map an existing Datadog Team to an Okta group. Establishing a link from the Okta group to the Datadog Team causes the Datadog Team to be managed by Okta going forward.
+
+**Note:** In order to synchronize an existing Datadog Team with an Okta group, the two names must match exactly.
+
+1. In your Datadog application in Okta, navigate to the **Push Groups** tab.
+1. Click the **Push Groups** button. The pushed groups interface opens.
+1. Select the Okta group you want to synchronize with a Datadog Team.
+1. In the **Match result & push action** column, ensure **Create group** is selected.
+1. Click **Save**.
+
+**Note:** When you select **Create group**, Okta displays a **No match found** message. You can ignore this message and proceed with creating the group to establish synchronization.
+
+### Delete the connection between an Okta group and a Datadog Team
+
+You have two options for disconnecting an Okta group from a Datadog Team, with different impacts on the Datadog Team membership.
+
+#### Keep team members in Datadog
+
+This procedure allows you to manage team membership in Datadog instead of Okta. The team members stay unchanged.
+
+1. In your Datadog application in Okta, navigate to the **Push Groups** tab.
+1. Click the **Push Groups** button. The pushed groups interface opens.
+1. Select the Okta group you want to unlink from its Datadog Team.
+1. In the **Match result & push action** column, select **Unlink Pushed Group**. A dialog box appears.
+1. Select **Leave the group in the target app**.
+1. Click **Unlink**.
+1. Click **Save**.
+
+#### Remove team members from Datadog
+
+This procedure allows you to manage team membership in Datadog instead of Okta and removes the team members from the Datadog Team.
+
+1. In your Datadog application in Okta, navigate to the **Push Groups** tab.
+1. Click the **Push Groups** button. The pushed groups interface opens.
+1. Select the Okta group you want to unlink from its Datadog Team.
+1. In the **Match result & push action** column, select **Unlink Pushed Group**. A dialog box appears.
+1. Select **Delete the group in the target app (recommended)**.
+1. Click **Unlink**.
+1. Click **Save**.
+
+**Note:** Contrary to the name of the option, selecting **Delete the group in the target app** does _not_ delete the team in Datadog. Instead, it removes all members from the team and removes the link between the group in Okta and the Datadog Team.
+
+## Further Reading
+
+{{< partial name="whats-next/whats-next.html" >}}
 
 [1]: /account_management/scim/
 [2]: /account_management/scim/#using-a-service-account-with-scim
 [3]: /getting_started/site
 [4]: https://app.datadoghq.com/organization-settings/application-keys
 [5]: /account_management/org_settings/service_accounts
+[6]: /account_management/teams/manage/#manage-teams-through-an-identity-provider
+[7]: https://app.datadoghq.com/teams

content/en/account_management/teams/manage.md

@@ -58,6 +58,23 @@ Under the team's settings, specify which users can modify the team membership. T
 
 Users with the `user_access_manage` permission can set default rules on who can add or remove members, or edit team details. Set default rules with the **Default Settings** button on the team directory page. Override these policies for an individual team on the team details panel.
 
+## Manage teams through an identity provider
+
+{{< callout url="/help/" header="false" >}}
+The Managed Teams feature is turned off by default. Request access by contacting support.
+{{< /callout >}}
+
+When you set up a managed team, you configure the following properties of the team externally through an identity provider integration:
+ - Team name
+ - Team handle
+ - Team membership (synchronized from the corresponding identity provider group)
+
+To ensure that managed teams stay consistent with their configuration in your identity provider, you must make changes to managed properties in the identity provider, not through the Datadog site or API.
+
+Datadog supports Okta and other SCIM-compliant identity providers for managed teams.
+
+For more information on the capabilities of managed teams and how to set them up, see [SCIM][3].
+
 ## SAML attribute mapping
 
 To manage teams and team membership using SAML attributes, see [Map SAML attributes to Teams][2].
@@ -72,3 +89,4 @@ To enforce a strict membership model, configure your default team settings so **
 
 [1]: https://app.datadoghq.com/organization-settings/teams
 [2]: /account_management/saml/mapping/#map-saml-attributes-to-teams
+[3]: /account_management/scim/