[Improvement - July 2023]: Guidance on 2FA best practices for bot or service accounts #10051 (#38309)

Co-authored-by: github-actions <github-actions@github.com>
Co-authored-by: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com>
Co-authored-by: Hirsch Singhal <1666363+hpsin@users.noreply.github.com>

content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/index.md

@@ -13,5 +13,5 @@ children:
   - /viewing-whether-users-in-your-organization-have-2fa-enabled
   - /preparing-to-require-two-factor-authentication-in-your-organization
   - /requiring-two-factor-authentication-in-your-organization
+  - /managing-bots-and-service-accounts-with-two-factor-authentication
 ---
-

content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/managing-bots-and-service-accounts-with-two-factor-authentication.md

@@ -0,0 +1,47 @@
+---
+title: Managing bots and service accounts with two-factor authentication
+intro: 'You can manage shared access to bots and service accounts that have two-factor authentication enabled.'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghec: '*'
+topics:
+  - Organizations
+  - Teams
+shortTitle: Manage bots & service accounts
+---
+## About managing bots or service accounts with two-factor authentication (2FA)
+
+You should ensure that 2FA is enabled for unattended or shared access accounts in your organization, such as bots and service accounts, so that these accounts stay protected. Enabling 2FA for a bot or service account ensures that users must authenticate with 2FA to sign in to the account on {% data variables.location.product_location %}. It does not affect the account's ability to authenticate with its existing tokens in automations.
+
+{% note %}
+
+**Note:** When you require use of two-factor authentication for your organization, unattended accounts that do not use 2FA will be removed from the organization and will lose access to its repositories.
+
+{% endnote %}
+
+## Managing shared access to bots or service accounts with 2FA
+
+{% data variables.product.prodname_dotcom %} recommends the following steps for managing shared access to bots or service accounts with 2FA enabled. The steps ensure that only people who have access to a mailing list (controlled by you) and a centrally stored TOTP secret can sign in to the account.
+
+1. Set up a mailing list for the bot or service account which has all of the account owners as members of the alias.
+1. Add the new mailing list address as a verified email address in the settings of the shared account. For more information, see "[AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account)."
+1. If you haven't already done so, configure 2FA for the bot or service account using an authenticator app (TOTP). For more information, see "[AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa)."
+1. Store the TOTP secret that's offered during 2FA setup in the password manager used by your organization.
+   {% note %}
+
+   **Note:** Don't store the password for the shared account in the password manager. You will use the password reset functionality every time you need to sign in to the shared account.
+
+   {% endnote %}
+
+   If you have already configured 2FA using TOTP and you need to locate the TOTP secret, use the following steps:
+      1. In the shared account's settings, click **{% octicon "shield-lock" aria-hidden="true" %} Password and authentication**.
+      1. Under "Two-factor methods", to the right of "Authenticator app", click **Edit**.
+      1. In "Authenticator app", immediately below the QR code, click **setup key**.
+
+      ![Screenshot of the "Authenticator app" settings. An embedded link, titled "setup key", is highlighted in a dark orange outline.](/assets/images/help/2fa/2fa-totp-secret-setup-key-link.png)
+
+      1. Copy the secret that's displayed in the dialog box.
+      1. Reconfigure 2FA using the copied secret.
+1. Select a CLI app (such as oathtool) for generating TOTP codes from the TOTP secret. You will use the app to generate a new TOTP code from the TOTP secret every time you need to access the account. For more information, see [oathtool](https://www.nongnu.org/oath-toolkit/man-oathtool.html) in the OATH Toolkit documentation.
+1. When you need to access the account, use the password reset functionality to reset the password (via the mailing list), and use the CLI app to generate a TOTP code.

content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/preparing-to-require-two-factor-authentication-in-your-organization.md

@@ -19,7 +19,8 @@ We recommend that you notify {% ifversion fpt or ghec %}organization members, ou
 When you require use of two-factor authentication for your organization, members, outside collaborators, and billing managers (including bot accounts) who do not use 2FA will be removed from the organization and lose access to its repositories. They will also lose access to their forks of the organization's private repositories.
 
 Before requiring 2FA in your organization, we recommend that you:
-- [Enable 2FA](/authentication/securing-your-account-with-two-factor-authentication-2fa) on your personal account
+- Enable 2FA on your personal account. For more information, see "[AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa)."
 - Ask the people in your organization to set up 2FA for their accounts
-- See whether [users in your organization have 2FA enabled](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/viewing-whether-users-in-your-organization-have-2fa-enabled)
-- Warn users that once 2FA is enabled, those without 2FA are automatically removed from the organization
+- See whether users in your organization have 2FA enabled. For more information, see "[AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/viewing-whether-users-in-your-organization-have-2fa-enabled)."
+- Enable 2FA for unattended or shared access accounts, such as bots and service accounts. For more information, see "[AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/managing-bots-and-service-accounts-with-two-factor-authentication)."
+- Warn users that once 2FA is enabled, those without 2FA are automatically removed from the organization.

content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization.md

@@ -39,7 +39,8 @@ You can also require two-factor authentication for organizations in an enterpris
 
 **Warnings:**
 
-- When you require use of two-factor authentication for your organization, {% ifversion fpt or ghec %}members, outside collaborators, and billing managers{% else %}members and outside collaborators{% endif %} (including bot accounts) who do not use 2FA will be removed from the organization and lose access to its repositories. They will also lose access to their forks of the organization's private repositories. You can [reinstate their access privileges and settings](/organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization) if they enable two-factor authentication for their personal account within three months of their removal from your organization.
+- When you require use of two-factor authentication for your organization, {% ifversion fpt or ghec %}members, outside collaborators, and billing managers{% else %}members and outside collaborators{% endif %} who do not use 2FA will be removed from the organization and lose access to its repositories. They will also lose access to their forks of the organization's private repositories. You can reinstate their access privileges and settings if they enable two-factor authentication for their personal account within three months of their removal from your organization. For more information, see "[AUTOTITLE](/organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization)."
+- You will also need to enable 2FA for unattended or shared access accounts, such as bots and service accounts. If you do not configure 2FA for these unattended accounts after you've enabled required two-factor authentication, the accounts will be removed from the organization and lose access to their repositories. For more information, see "[AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/managing-bots-and-service-accounts-with-two-factor-authentication)."
 - If an organization owner, member,{% ifversion fpt or ghec %} billing manager,{% endif %} or outside collaborator disables 2FA for their personal account after you've enabled required two-factor authentication, they will automatically be removed from the organization.
 - If you're the sole owner of an organization that requires two-factor authentication, you won't be able to disable 2FA for your personal account without disabling required two-factor authentication for the organization.