update(platform): auth policy settings

docs/platform/concepts/managed-users.md

@@ -4,10 +4,19 @@ title: Managed users
 
 import ActionsIcon from "@site/static/images/icons/more.svg";
 
-The managed users feature lets you centrally manage your organization's users, including editing their profiles, resetting passwords, and [setting authentication policies](/docs/platform/howto/set-authentication-policies).
+The managed users feature lets you centrally manage your organization's users and helps you to secure your organization in Aiven.
 
-A managed user cannot create new organizations
-unless they are a [super admin](/docs/platform/howto/make-super-admin) of the organization.
+With managed users, you can:
+
+- Control how users log in with [authentication policies](/docs/platform/howto/set-authentication-policies),
+  not just how they access the organization
+- Have visibility of all users in your domain even if they weren't added to the Aiven
+  organization
+- Set their state, including deactivating and deleting user accounts
+
+Managed users are also restricted from making changes to their profiles and creating new
+organizations. Only [super admin](/docs/platform/howto/make-super-admin)
+can create organizations.
 
 ## Make organizations user managed users
 
@@ -22,7 +31,6 @@ Users in an organization with a verified domain automatically become managed use
 
 1. Click **Admin**.
 1. Select **Users**.
-1. Find the user that you want to deactivate.
-1. Click <ActionsIcon className="icon"/> **Actions** > **Deactivate**.
+1. Find the user and click <ActionsIcon className="icon"/> **Actions** > **Deactivate**.
 
 You can follow the same process to reactivate the user.

docs/platform/howto/manage-domains.md

@@ -4,19 +4,18 @@ title: Manage domains
 
 import ActionsIcon from "@site/static/images/icons/more.svg";
 
-Verified domains let you manage users in your organization.
+Adding a verified domain in Aiven adds an extra layer of security to managing your organization's users. When you verify a domain, your organization users automatically become
+[managed users](/docs/platform/concepts/managed-users).
+
 
 There are two ways you can verify a domain:
 
 -   by adding a DNS TXT record to the domain (recommended)
 -   by uploading an HTML file to your website
 
-After adding a domain, organization users automatically become
-[managed users](/docs/platform/concepts/managed-users).
-
 ## Add a domain using a DNS TXT record
 
-1. In the organization you want to add a domain to, click **Admin**.
+1. In the organization, click **Admin**.
 
 1. Click **Domains**.
 
@@ -55,8 +54,7 @@ can retry it by repeating the last step.
 
 ## Add a domain using an HTML file
 
-1. In the organization that you want to add a domain to, click
-    **Admin**.
+1. In the organization, click **Admin**.
 1. Click **Domains**.
 1. Click **Add domain**.
 1. Enter a **Domain name**.
@@ -74,8 +72,7 @@ can retry it by repeating the last step.
 Removing a domain is an irreversible action.
 :::
 
-1. In the organization that you want to remove a domain from, click
-    **Admin**.
+1. In the organization, click **Admin**.
 1. Click **Domains**.
-1. Find the domain you want to remove and click <ActionsIcon className="icon"/>
+1. Find the domain and click <ActionsIcon className="icon"/>
    **Actions** > **Remove** and confirm.

docs/platform/howto/set-authentication-policies.md

@@ -2,43 +2,73 @@
 title: Set authentication policies for organization users
 ---
 
-The authentication policy for your organization specifies the ways that
-users can access your organization on the Aiven platform: with a
-password, third-party authentication, or organization single sign-on
-(SSO).
+The authentication policy for your organization specifies the ways that users in your organization and their personal tokens can access the organization on the Aiven platform.
 
 ## Authentication types
 
+When creating an authentication policy, you select the authentication methods to allow
+for all users in your organization. For increased security, it's a good idea to always
+[verify your organization's domains](/docs/platform/howto/manage-domains).
+
 ### Passwords and two-factor authentication
 
 With password authentication enabled, users log in with their email
 address and password. For an added layer of security, you can enforce
 two-factor authentication (2FA) for password logins for all users in
 your organization.
 
-When 2FA is required, users won't be able to
-access any resources in your organization until they set up 2FA.
+When 2FA is required, users can't access any resources in your organization until they
+set up 2FA.
 
 :::note
-Authentication tokens are not affected and continue to work when you make 2FA required.
-However, when users [enable 2FA](/docs/platform/howto/user-2fa) their existing authentication tokens are revoked.
+Personal tokens are not affected and continue to work when you make 2FA required.
+However, when users [enable 2FA](/docs/platform/howto/user-2fa) their existing tokens
+might stop working.
 :::
 
 ### Third-party authentication
 
 Users can choose to log in using Google, Microsoft, or GitHub.
 
-### Organization identity providers (SSO)
+### SSO with an organization identity provider
 
-Organization users are restricted to logging in using SSO through an
-[identity provider](/docs/platform/howto/saml/add-identity-providers).
+Users that are part of multiple Aiven organizations can log in using single sign-on (SSO)
+and access your organization’s resources with an
+[identity provider](/docs/platform/howto/saml/add-identity-providers) that is configured
+for any of those organizations.
 
-## Set an authentication policy
+You can further restrict access by requiring users to log in with one of your
+organization’s identity providers. This means that they cannot
+log in to your organization using another Aiven organization's identity provider. It's
+strongly recommended to enable this if you only have one Aiven organization.
+
+### Personal tokens
+
+Users can generate their own
+[personal tokens](/docs/platform/howto/create_authentication_token) for use with
+the Aiven API.
 
-To set an authentication policy for all users in an organization:
+To regularly manage your resources programmatically with the API, CLI, Terraform,
+or other applications, it's best to create an [application user](/docs/platform/howto/manage-application-users) with its own tokens.
+
+Personal tokens are generated with the authentication method that the user logged in with.
+Tokens are linked to the authentication method they are created with. You can ensure that
+access to your organization using tokens conforms to the authentication policy by
+requiring users to be logged in with an allowed authentication method when they
+use a token. If your authentication policy changes, tokens that don’t conform to the
+new policy stop working.
+
+For example, if you have an authentication policy that allows users to log in with a
+password, a user can log in with their email and password, and create a personal token.
+This token is tied to the password authentication method they logged in with.
+If the authentication policy changes later to only allow logging on with an identity
+provider, then the token generated when the user was logged in with their password will
+not work. After logging in with an allowed method on the new authentication policy
+the user can create a new token.
+
+## Set an authentication policy
 
 1.  In the organization, click **Admin**.
-2.  Click **Authentication**.
-3.  Click the toggle for each authentication method that you want to
-    allow.
-4.  Click **Save changes**.
+1.  Click **Authentication**.
+1.  Configure the settings for your authentication policy.
+1.  Click **Save changes**.