Enforce 2FA documentation

data/nav.yml

@@ -314,6 +314,8 @@
           path: "team-management"
         - name: "User and team permissions"
           path: "team-management/permissions"
+        - name: "Enforce 2FA"
+          path: "team-management/enforce-2fa"
     - name: "Governance"
       children:
         - name: "Overview"

pages/apis/graphql/cookbooks/organizations.md

@@ -126,6 +126,27 @@ mutation UpdateSessionIPAddressPinning {
 }
 ```
 
+## Enforce two-factor authentication (2FA) for your organization
+
+Require users to have two-factor authentication enabled before they can access your organization's Buildkite dashboard.
+
+```graphql
+mutation EnableEnforced2FA {
+  organizationEnforceTwoFactorAuthenticationForMembersUpdate(
+    input: {
+      organizationId: "organization-id",
+      membersRequireTwoFactorAuthentication: true
+    }
+  ) {
+    organization {
+      id
+      membersRequireTwoFactorAuthentication
+      uuid
+    }
+  }
+}
+```
+
 ## Query the usage API
 
 Use the usage API to query your organization's usage by pipeline or test suite at daily granularity.

pages/team_management.md

@@ -7,4 +7,5 @@ toc: false
 Managing users and teams in CI/CD is fundamental to collaboration, streamlined processes, and ensuring adequate access controls. Buildkite provides features to manage team access:
 
 - [User and team permissions](/docs/team-management/permissions)
+- [Enforce 2FA](/docs/team-management/enforce-2fa)
 - [Managing API access tokens](/docs/apis/managing-api-tokens) (under the APIs section)

pages/team_management/enforce_2fa.md

@@ -0,0 +1,34 @@
+---
+keywords: docs, tutorials, 2fa
+---
+
+# Enforce two-factor authentication (2FA)
+
+Two-factor authentication can be enforced for the whole organization to ensure
+that all users who access the organization have two-factor authentication enabled.
+
+## Before enforcing two-factor authentication
+
+Before you enforce two-factor authentication for your organization, consider
+that users without 2FA enabled will immediately lose access to the organization
+and subsequent pipelines.
+
+Users can set up two-factor authentication by following this [tutorial].
+
+## Steps to enforce two-factor authentication
+
+To enforce two-factor authentication:
+
+- You must be logged in as an Administrator
+- Visit the Organization's [security settings]
+- Check **Enforce two-factor authentication**
+- Click **Update Access Control**
+
+## Programmatically enforcing two-factor authentication
+
+Please review the GraphQL [cookbook] for instructions on how to enable
+enforced 2fa via the GraphQL API.
+
+[cookbook]: </docs/apis/graphql/cookbooks/organizations#enforce-two-factor-authentication-2fa-for-your-organization>
+[security settings]: <https://buildkite.com/organizations/~/security>
+[tutorial]: </docs/tutorials/2fa>

pages/tutorials/2fa.md

@@ -54,12 +54,8 @@ You need to ask the administrator of your Buildkite organization to remove your
 
 ## Enforcing two-factor authentication for the whole organization
 
-Currently, it's not possible to enforce 2FA in Buildkite for members of an organization. However, you can check the current 2FA status using the [User Settings](https://buildkite.com/user/settings) page for your organization. You'll see a 2FA badge next to the users who have it enabled.
-
-<%= image "2fa-8.png", width: 866, height: 222, alt: "Checking Two-Factor Authentication Status of a User" %>
-
-If conducting a regular audit is not enough, many SSO providers can enforce 2FA. In turn, Buildkite can enforce SSO for members of an organization. If you're already using an SSO provider this may be a solution. Read more about [using SSO with Buildkite](/docs/integrations/sso).
-
+Organization administrators who would like to enforce two-factor authentication
+across their entire organization can do so following the [Enforce 2FA](/docs/team-management/enforce-2fa) guide.
 
 [1Password]: <https://support.1password.com/one-time-passwords/>
 [OTP Auth]: <https://cooperrs.de/otpauth.html>