Document MFA over SSH and API (#4074)

AnouckColson · pjcdawkins · chadwcarlson · web-flow · commit 57118641afeb · 2024-07-09T14:27:11.000-04:00
* Document MFA over SSH and API * Updated procedures * Tweaks on both sides * Fix link * Improve consistency * Further tweaks * Clarity * Apply suggestions from review * Fix links * Fix more links * Last link * Last tweaks * Add consequence to PSH * Fix link * Update sites/upsun/src/development/ssh/troubleshoot-ssh.md Co-authored-by: Patrick Dawkins <pjcdawkins@users.noreply.github.com> * Apply suggestions from code review * Add feature availability banner to Upsun side * Add availability info on Upsun side * Update links now that #4079 is merged * Add note for use with tokens. * Test fixes: sites/platform. --------- Co-authored-by: Patrick Dawkins <pjcdawkins@users.noreply.github.com> Co-authored-by: Chad Carlson <chadwcarlson@users.noreply.github.com> Co-authored-by: chadcarlson <chad.carlson@platform.sh>
diff --git a/contributing/styles/config/vocabularies/Platform/accept.txt b/contributing/styles/config/vocabularies/Platform/accept.txt
@@ -188,6 +188,7 @@ transclusion
 [Uu]nencoded
 unencrypted
 unmerged
+Upsun
 Uvicorn
 Uvloop
 [Uu]nmount
diff --git a/sites/platform/src/administration/security/_index.md b/sites/platform/src/administration/security/_index.md
@@ -0,0 +1,4 @@
+---
+title: Security
+description: For enhanced security, enable Multi-Factor Authentication (MFA) or Single Sign-On (SSO).
+---
diff --git a/sites/platform/src/administration/security/mfa.md b/sites/platform/src/administration/security/mfa.md
@@ -0,0 +1,41 @@
+---
+title: Multi-Factor Authentication (MFA)
+weight: 4
+keywords: 
+- 2fa
+- twofactor
+- two factor
+- mfa
+- multifactor authentication
+description: Enhance your organizations' security with Multi-Factor Authentication (MFA).
+---
+
+Multi-Factor Authentication (MFA) enhances security by protecting both your organization and every user account that interacts with it
+through SSH or the {{% vendor/name %}} API.
+
+When MFA is enforced within an organization, every project contributor **must** enable MFA on their user account so they can run Git commands,
+SSH into an environment, or trigger actions through the {{% vendor/name %}} API.
+
+## Enable MFA on your user account
+
+To access an organization that enforces MFA or any of its projects,
+you **must** enable MFA on your user account.
+Failure to do so results in forbidden access to the organization from the Console or API,
+and an [error message](/development/ssh/troubleshoot-ssh.md#mfa-related-error-message) when trying to SSH into its environments.
+
+To enable MFA on your user account, follow these steps:
+
+1. In the Console, open the user menu (your name or profile picture).
+2. Click **My profile**
+3. Click **Security**.
+4. Click **Set up application**.
+5. Follow the instructions for the chosen authentication app.
+6. Click **Verify & save**.
+7. Refresh your SSH credentials by running `{{% vendor/cli %}} login -f` in the CLI.
+
+## Enforce MFA within your organization
+
+{{< premium-features/tiered "Elite and Enterprise" >}}
+
+As an **admin user**, to enable MFA, open a [support ticket](/learn/overview/get-support)
+and request for MFA to be enforced within your organization.
diff --git a/sites/platform/src/administration/security/sso.md b/sites/platform/src/administration/security/sso.md
@@ -1,5 +1,5 @@
 ---
-title: "Single sign-on (SSO)"
+title: "Single Sign-On (SSO)"
 weight: 4
 description: |
   {{% vendor/name %}} allows you to set up mandatory SSO with a third-party identity provider (IdP) for all your users.
diff --git a/sites/platform/src/administration/web/mfa.md b/sites/platform/src/administration/web/mfa.md
diff --git a/sites/platform/src/development/ssh/_index.md b/sites/platform/src/development/ssh/_index.md
@@ -164,13 +164,10 @@ There are three basic ways to authenticate with {{% vendor/name %}}:
   * Good for letting automation tools use the CLI.
   * Requires you to regularly change the tokens to maintain security.
 
-## Multifactor authentication (MFA) over SSH
+## SSH into an MFA-protected environment
 
-{{< premium-features/tiered "Enterprise and Elite" >}}
+For enhanced security, as an organization owner or admin user,
+you can [enforce Multi-Factor Authentication (MFA) within your organization](/administration/security/mfa.md#enforce-mfa-within-your-organization).
 
-To enhance security, Enterprise and Elite customers can enforce MFA over SSH within their organization.
-When this is enabled, every project contributor within your organization must enable MFA in their account
-to run Git commands or to SSH in an environment.
-To enable this feature, open a [support ticket](/learn/overview/get-support) and request for MFA over SSH to be enforced within your organization.
-
-If you have trouble accessing an environment with MFA enabled, see how to [add a second factor](./troubleshoot-ssh.md#add-a-second-authentication-factor).
+As a project contributor, if you haven't enabled MFA on your user account and SSH into an environment that is protected by MFA,
+you get an error message. See how you can [troubleshoot that error message](/development/ssh/troubleshoot-ssh.md#mfa-related-error-message).
diff --git a/sites/platform/src/development/ssh/troubleshoot-ssh.md b/sites/platform/src/development/ssh/troubleshoot-ssh.md
@@ -72,53 +72,11 @@ IdentityFile ~/.ssh/id_{{% vendor/alt-name %}}
 Be aware that, above, `{{% vendor/alt-name %}}` stands for a hostname.
 Each different hostname you connect to {{< vendor/name >}} at may have to be specified in the host line, separated by spaces.
 
-## Check your git integrations
+## Check your Git integrations
 
-If your project is integrated with another git provider (such as GitHub), that provider controls git operations.
+If your project is integrated with another Git provider (such as GitHub), that provider controls Git operations.
 Make sure you have added your public SSH key to your provider and that your user there has access.
 
-## Add a second authentication factor
-
-If your organization has [multifactor authentication set up](./_index.md#multifactor-authentication-mfa-over-ssh),
-you may get an error like the following when trying to log into your environment with SSH keys:
-
-```bash
-Hello {{< variable "NAME" >}} (UUID: {{< variable "USER_ID" >}}), you successfully authenticated, but could not connect to service {{< variable "USER_ID" >}} --app
-(reason: access requires MFA)
-{{< variable "ENVIRONMENT_ID" >}}@ssh.{{< variable "REGION" >}}.{{< vendor/urlraw "host" >}}: Permission denied (publickey)
-```
-
-If you are using just `ssh` and not `{{% vendor/cli %}} ssh`, you may see only the second half of the error:
-
-```bash
-{{< variable "ENVIRONMENT_ID" >}}@ssh.{{< variable "REGION" >}}.{{< vendor/urlraw "host" >}}: Permission denied (publickey)
-```
-
-To resolve this:
-
-{{< codetabs >}}
-+++
-title=Using the CLI
-+++
-
-Log in using the browser by running `{{% vendor/cli %}} login`.
-
-<--->
-
-+++
-title=In the Console
-+++
-
-1. Open the user menu (your name or profile picture).
-2. Click **My profile**
-3. Click **Security**.
-4. Click **Set up application**.
-5. Follow the instructions for the chosen authentication app.
-6. Click **Verify & save**.
-7. Refresh your SSH credentials by running `{{% vendor/cli %}} login -f` in the CLI.
-
-{{< /codetabs >}}
-
 ## Generate SSH debug information
 
 If your private key and public key both look OK but you don't have any luck logging in, print debugging information.
@@ -152,8 +110,41 @@ GIT_SSH_COMMAND="ssh -v" git clone {{< variable "REPO_URL" >}}
 
 You can use this information to make one last check of the private key file.
 
+## MFA-related error message
+
+If you haven't enabled MFA on your user account and try to SSH into an environment that is protected by MFA,
+you get the following error message:
+
+```bash
+Error: Access denied
+Service: abcdefg123456-main-bvxea6i--app
+User: {{< variable "USER NAME" >}} ({{< variable "USER ID" >}})
+Parameters: {"amr":["mfa","sso:acme"]}
+Detail: Additional authentication is required:
+	 - Multi-factor authentication (MFA)
+	 - Single sign-on (SSO), provider: "acme"
+```
+
+To solve this, [enable MFA on your user account](/administration/security/mfa.md#enable-mfa-on-your-user-account).
+
+Alternatively, open the Console and select the desired organization.
+Follow the instructions so you can effectively access its contents.
+
+Similarly for bot users and CLI tokens, you may see the message:
+
+```bash
+  [RequestException]                                           
+  Multi-factor authentication (MFA) is required.               
+  The API token may need to be re-created after enabling MFA.  
+```
+
+In this case, as described, it will be necessary to:
+
+1. Enable MFA on the (bot) user account associated with the token.
+2. Generate a new access token, and then replace its value in your workflow that requires the token (such as updating a GitHub workflow secret variable).
+
 ## Something still wrong?
 
 For more general information, see how to [troubleshoot development](/development/troubleshoot).
 
-If you're still stuck, open a [support ticket](/learn/overview/get-support) and provide the full SSH debug information.
+If you're still stuck, open a [support ticket](/learn/overview/get-support) and provide the full SSH debug information.
diff --git a/sites/platform/src/guides/ibexa/deploy.md b/sites/platform/src/guides/ibexa/deploy.md
@@ -7,9 +7,9 @@ description: Learn how to use Ibexa DXP on {{% vendor/name %}}.
 
 Ibexa DXP is a digital experience platform with a focus on delivering effective content, offering personalized customer journeys, and facilitating multi-channel purchases and customer service.
 
-Ibexa Cloud, based on Platform.sh, is the fastest solution to build and run Ibexa projects.
+Ibexa Cloud, based on {{% vendor/name %}}, is the fastest solution to build and run Ibexa projects.
 
-See how to [install Ibexa DXP on Platform.sh through Ibexa Cloud](https://doc.ibexa.co/en/latest/getting_started/install_on_ibexa_cloud/).
+See how to [install Ibexa DXP on {{% vendor/name %}} through Ibexa Cloud](https://doc.ibexa.co/en/latest/getting_started/install_on_ibexa_cloud/).
 
 ## Redis
 
diff --git a/sites/platform/src/learn/overview/get-support.md b/sites/platform/src/learn/overview/get-support.md
@@ -27,6 +27,7 @@ Once you submit a ticket, you see it in a list of all tickets created, for all p
 Note that once you submit the ticket, you can't modify or delete the submission.
 If you have any additional information, you can select the submitted ticket and write a message.
 
+<!-- vale off -->
 ## Slack
 
 To talk about app development or framework-related questions,
@@ -36,6 +37,7 @@ join other customers and engineers in the [public Slack channel](https://chat.pl
 
 The [{{% vendor/name %}} Community site](https://community.platform.sh/) has how-to guides with suggestions
 on how to get the most out of {{% vendor/name %}}.
+<!-- vale on -->
 
 ## Contact Sales
 
diff --git a/sites/upsun/src/administration/billing/add-on-subscription.md b/sites/upsun/src/administration/billing/add-on-subscription.md
@@ -20,7 +20,7 @@ The Standard User Management add-on gives you access to the following features:
 - Free [viewer permissions](../users.md)
 - Custom [organization permissions](../users.md#organization-permissions)
 - [Teams](/administration/teams.md)
-- [MFA enforcement within an organization](/administration/web/mfa.md)
+- [MFA enforcement within an organization](/administration/mfa.md)
 
 ### Upgrade to the Standard User Management add-on
 
diff --git a/sites/upsun/src/administration/mfa.md b/sites/upsun/src/administration/mfa.md
@@ -0,0 +1,82 @@
+---
+title: Multi-Factor Authentication (MFA)
+weight: 4
+keywords: 
+- 2fa
+- twofactor
+- two factor
+- mfa
+- multifactor authentication
+description: Enhance your organizations' security with Multi-Factor Authentication (MFA).
+---
+
+Multi-Factor Authentication (MFA) enhances security by protecting both your organization and every user account that interacts with it
+through SSH or the {{% vendor/name %}} API.
+
+When MFA is enforced within an organization, every project contributor **must** enable MFA on their user account so they can run Git commands,
+SSH into an environment, or trigger actions through the {{% vendor/name %}} API.
+
+## Enable MFA on your user account
+
+To access an organization that enforces MFA or any of its projects,
+you **must** enable MFA on your user account.
+Failure to do so results in forbidden access to the organization from the Console or API,
+and an [error message](/development/ssh/troubleshoot-ssh.md#mfa-related-error-message) when trying to SSH into its environments.
+
+To enable MFA on your user account, follow these steps:
+
+1. In the Console, open the user menu (your name or profile picture).
+2. Click **My profile**
+3. Click **Security**.
+4. Click **Set up application**.
+5. Follow the instructions for the chosen authentication app.
+6. Click **Verify & save**.
+7. Refresh your SSH credentials by running `{{% vendor/cli %}} login -f` in the CLI.
+
+## Enforce MFA within your organization
+
+{{< note theme="info" title="Feature availability and permissions">}}
+
+This feature is available as part of the Standard User Management add-on.
+To add it to your project, [administer your organization's billing](/administration/billing/billing-admin).
+
+Only **organization owners** and **admin users** can enable MFA within an organization.
+However, even if you have the required permissions,
+you **must** [enable MFA on your user account](#enable-mfa-on-your-user-account) prior to enforcing it within the whole organization.
+
+{{< /note >}}
+
+To enable MFA within your organization, follow these steps:
+
+1. In the Console, open the user menu (your name or profile picture).
+2. Click **Settings**.
+3. Click **Security**.
+4. In the **MFA required** area, set the **Enable** toggle on.
+
+{{< note >}}
+
+Under **User security settings**, you can view which users in your organization have [activated MFA for their user accounts](#enable-mfa-on-your-user-account).
+
+{{< /note >}}
+
+### Send email reminders
+
+You can send email reminders to users who haven't enabled MFA on their user account yet.
+To do so, follow these steps:
+
+1. In the Console, open the user menu (your name or profile picture).
+2. Click **Settings**.
+3. Click **Security**.
+4. In the **User security settings** area, find the user you want to send a reminder to.
+5. Click **{{< icon more >}} More** next to that user.
+6. Select **Remind**.</br>
+   An email is sent to the user with instructions on how to enable MFA on their user account.
+
+{{< note >}}
+
+You can send reminders to multiple users at once.</br>
+To do so, in the **User security settings** user list,
+select the desired users by checking the boxes in front of their names.
+Click **Remind** at the top of the list to trigger the reminder emails.
+
+{{< /note >}}
diff --git a/sites/upsun/src/administration/users.md b/sites/upsun/src/administration/users.md
@@ -11,7 +11,7 @@ When a user is added to a project, they are automatically added to your organiza
 {{< note title="Available add-on" >}}
 
 The Standard User Management add-on offers free viewer permissions, custom [organization permissions](#organization-permissions),
-[teams](/administration/teams.md), and [MFA enforcement within an organization](/administration/web/mfa.md).
+[teams](/administration/teams.md), and [MFA enforcement within an organization](/administration/mfa.md).
 See how to [subscribe to this add-on](/administration/billing/add-on-subscription.md#standard-user-management-add-on).
 
 {{< /note >}}
diff --git a/sites/upsun/src/administration/web/mfa.md b/sites/upsun/src/administration/web/mfa.md
diff --git a/sites/upsun/src/development/ssh/_index.md b/sites/upsun/src/development/ssh/_index.md
@@ -163,3 +163,11 @@ There are three basic ways to authenticate with {{% vendor/name %}}:
 * [Using API tokens](../../administration/cli/api-tokens.md)
   * Good for letting automation tools use the CLI.
   * Requires you to regularly change the tokens to maintain security.
+
+## SSH into an MFA-protected environment
+
+For enhanced security, as an organization owner or admin user,
+you can [enforce Multi-Factor Authentication (MFA) within your organization](/administration/mfa.md#enforce-mfa-within-your-organization).
+
+As a project contributor, if you haven't enabled MFA on your user account and SSH into an environment that is protected by MFA,
+you get an error message. See how you can [troubleshoot that error message](/development/ssh/troubleshoot-ssh.md#mfa-related-error-message).
diff --git a/sites/upsun/src/development/ssh/troubleshoot-ssh.md b/sites/upsun/src/development/ssh/troubleshoot-ssh.md

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +---
 +title: Security
 +description: For enhanced security, enable Multi-Factor Authentication (MFA) or Single Sign-On (SSO).
 +---