From e27685fef1dd6dc7902974930237cb2c803a1c0e Mon Sep 17 00:00:00 2001 From: James Hill Date: Tue, 19 Sep 2023 22:18:12 +1000 Subject: [PATCH 1/2] Add Enforce 2FA documentation Enforce 2FA is a feature for all organizations who want to ensure that all users of their organization have 2FA enabled before they can access their organiztion. Enforce 2FA is part of the Q3 releas. --- data/nav.yml | 2 ++ pages/apis/graphql/cookbooks/organizations.md | 21 ++++++++++++ pages/team_management.md | 1 + pages/team_management/enforce_2fa.md | 34 +++++++++++++++++++ pages/tutorials/2fa.md | 8 ++--- 5 files changed, 60 insertions(+), 6 deletions(-) create mode 100644 pages/team_management/enforce_2fa.md diff --git a/data/nav.yml b/data/nav.yml index b9a4037608..30f340438e 100644 --- a/data/nav.yml +++ b/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" diff --git a/pages/apis/graphql/cookbooks/organizations.md b/pages/apis/graphql/cookbooks/organizations.md index 23eb3ba60a..6921c08015 100644 --- a/pages/apis/graphql/cookbooks/organizations.md +++ b/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. diff --git a/pages/team_management.md b/pages/team_management.md index 4126663c81..86703e8d64 100644 --- a/pages/team_management.md +++ b/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) diff --git a/pages/team_management/enforce_2fa.md b/pages/team_management/enforce_2fa.md new file mode 100644 index 0000000000..7989b3e8c7 --- /dev/null +++ b/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]: +[security settings]: +[tutorial]: <../tutorials/2fa> diff --git a/pages/tutorials/2fa.md b/pages/tutorials/2fa.md index 1982ddca95..5820f765c3 100644 --- a/pages/tutorials/2fa.md +++ b/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](../team-management/enforce-2fa) guide. [1Password]: [OTP Auth]: From 493762260f1be55f011f3c1832f718620cdf2553 Mon Sep 17 00:00:00 2001 From: James Hill Date: Thu, 21 Sep 2023 08:52:13 +1000 Subject: [PATCH 2/2] Use absolute paths for referencing other docs --- pages/team_management/enforce_2fa.md | 2 +- pages/tutorials/2fa.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/team_management/enforce_2fa.md b/pages/team_management/enforce_2fa.md index 7989b3e8c7..b32f5e5c8f 100644 --- a/pages/team_management/enforce_2fa.md +++ b/pages/team_management/enforce_2fa.md @@ -31,4 +31,4 @@ enforced 2fa via the GraphQL API. [cookbook]: [security settings]: -[tutorial]: <../tutorials/2fa> +[tutorial]: diff --git a/pages/tutorials/2fa.md b/pages/tutorials/2fa.md index 5820f765c3..4b512f2fb9 100644 --- a/pages/tutorials/2fa.md +++ b/pages/tutorials/2fa.md @@ -55,7 +55,7 @@ You need to ask the administrator of your Buildkite organization to remove your ## Enforcing two-factor authentication for the whole organization Organization administrators who would like to enforce two-factor authentication -across their entire organization can do so following the [Enforce 2FA](../team-management/enforce-2fa) guide. +across their entire organization can do so following the [Enforce 2FA](/docs/team-management/enforce-2fa) guide. [1Password]: [OTP Auth]: