fix: okta idp instructions (#197)

aiven · May 14, 2024 · b005634 · b005634
1 parent b1284cc
commit b005634
Showing 1 changed file with 18 additions and 20 deletions.
diff --git a/docs/platform/howto/saml/add-okta-idp.md b/docs/platform/howto/saml/add-okta-idp.md
@@ -2,25 +2,22 @@
 title: Add Okta as an identity provider
 ---
 
-Use [Okta](https://www.okta.com/) to give your organization users single sign-on (SSO) access to Aiven.
-Aiven also supports
-[user provisioning for Okta](/docs/platform/howto/okta-user-provisioning-with-scim)
-with SCIM.
+Use [Okta](https://www.okta.com/) to give your organization users single sign-on (SSO) access to Aiven. Aiven also supports [user provisioning for Okta](/docs/platform/howto/okta-user-provisioning-with-scim) with SCIM.
 
 ## Prerequisite steps in Aiven Console
 
 Add Okta as an
-[identity provider](/docs/platform/howto/saml/add-identity-providers#add-idp-aiven-console) in the Console.
+[identity provider (IdP)](/docs/platform/howto/saml/add-identity-providers#add-idp-aiven-console).
 
 ## Configure SAML on Okta {#configure-saml-okta}
 
-Create the SAML SP-Initiated authentication flow and create a bookmark app that will
-redirect to the Aiven Console's login page:
+Create the SAML SP-Initiated authentication flow and a bookmark app that redirects
+to the Aiven Console's login page:
 
-1.  Log in to the [Okta administrator console](https://login.okta.com/).
-1.  Go to the **Applications** tab.
+1.  In the [Okta administrator console](https://login.okta.com/), go to the
+     **Applications** tab.
 1.  Click **Create an app integration**.
-1.  Select **SAML 1.0** for the **Sign on method** and click **Next**.
+1.  Select **SAML 2.0** for the **Sign on method** and click **Next**.
 1.  Enter a name for the app and add a logo.
 1.  Set its visibility for your Okta users and click **Next**.
 1.  Set the following values in the app configuration:
@@ -29,11 +26,11 @@ redirect to the Aiven Console's login page:
     | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
     | `Single sign on URL`       | ACS URL                                                                                                                                                                                                                                                                         |
     | `AudienceURI (SPEntityId)` | Metadata URL                                                                                                                                                                                                                                                                    |
-    | `Default RelayState`       | <ul><li><code>https://console.aiven.io/</code> when using the Aiven Console</li> <li><code>https://console.gcp.aiven.io/</code> when using Aiven GCP Marketplace Console</li> <li><code>https://console.aws.aiven.io/</code> when using Aiven AWS Marketplace Console</li></ul> |
+    | `Default RelayState`       | <ul><li><code>https://console.aiven.io/</code> for the Aiven Console</li> <li><code>https://console.gcp.aiven.io/</code> for the Aiven Google Cloud Marketplace Console</li> <li><code>https://console.aws.aiven.io/</code> for the Aiven AWS Marketplace Console</li></ul> |
 
-    :::important
+    :::note
     The `Default RelayState` is the homepage of the Aiven Console and is
-    fundamental for IdP initiated sign on to function correctly.
+    necessary for IdP-initiated login to function correctly.
     :::
 
 1.  Add an entry to **Attribute statements** with:
@@ -43,13 +40,13 @@ redirect to the Aiven Console's login page:
     | `name`    | `email`      |
     | `value`   | `user.email` |
 
-1.  Click **Next** and click **Finish**. You are redirected to your
+1.  Click **Next** and **Finish**. You are redirected to your
     application in Okta.
 
-1. Click the **View Setup Instructions** for the application.
+1. Click **View Setup Instructions** for the application.
 
-1. Go to the **Sign On** tab and copy the application data to be used
-    in the final configuration in Aiven:
+1. Go to the **Sign On** tab and copy the following. You will use these to configure
+    the IdP in Aiven:
 
     -   `Identity Provider Signle Sign-On URL`
     -   `Identity Provider Issuer`
@@ -60,14 +57,15 @@ redirect to the Aiven Console's login page:
 1. Click **Assign** to assign users or groups to the Okta application.
 
 :::note
-New users need to be assigned to the Aiven application in Okta for the
-login to be successful.
+You have to assign new users to the Aiven application in Okta for the SSO
+login to work.
 :::
 
 ## Finish the configuration in Aiven
 
 Go back to the Aiven Console to
-[configure the IdP](/docs/platform/howto/saml/add-identity-providers#configure-idp-aiven-console) and complete the setup.
+[configure the IdP](/docs/platform/howto/saml/add-identity-providers#configure-idp-aiven-console)
+and complete the setup.
 
 ## Troubleshooting