diff --git a/docs/img/sso/okta/setup-redirection.png b/docs/img/sso/okta/setup-redirection.png
index 026d926d5fe58..b70d53c96595c 100644
Binary files a/docs/img/sso/okta/setup-redirection.png and b/docs/img/sso/okta/setup-redirection.png differ
diff --git a/docs/pages/access-controls/sso/okta.mdx b/docs/pages/access-controls/sso/okta.mdx
index 14de1ab57b606..365a47d7923fc 100644
--- a/docs/pages/access-controls/sso/okta.mdx
+++ b/docs/pages/access-controls/sso/okta.mdx
@@ -23,7 +23,16 @@ Teleport administrators to define policies like:
 
 - A Teleport role with access to edit and maintain `saml` resources. This is
   available in the default `editor` role.
-- (!docs/pages/includes/tctl.mdx!)
+
+<Tabs>
+<TabItem label="Teleport Enterprise (Self-Hosted)" scope="enterprise">
+- (!docs/pages/includes/enterprise/tctl-tsh-prerequisite.mdx!)
+</TabItem>
+<TabItem label="Teleport Cloud" scope="cloud">
+- (!docs/pages/includes/cloud/tctl-tsh-prerequisite.mdx!)
+</TabItem>
+</Tabs>
+
 
 (!docs/pages/includes/enterprise/samlauthentication.mdx!)
 
@@ -67,13 +76,14 @@ Provide the following values to their respective fields:
 
 #### General
 
-- Single sign on URL: `https://<cluster-url>/v1/webapi/saml/acs/new_saml_connector`
-- Audience URI (SP Entity ID): <nobr>`https://<cluster-url>/v1/webapi/saml/acs/new_saml_connector`</nobr>
+- Single sign on URL: `https://<cluster-url>:<port>/v1/webapi/saml/acs/okta`
+- Audience URI (SP Entity ID): <nobr>`https://<cluster-url>:<port>/v1/webapi/saml/acs/okta`</nobr>
 - Name ID format `EmailAddress`
 - Application username `Okta username`
 
 Replace `<cluster-url>` with your Teleport Proxy Service address or Enterprise
-Cloud tenant (e.g. `mytenant.teleport.sh`).
+Cloud tenant (e.g. `mytenant.teleport.sh`). Replace `<port>` with your Proxy
+Service listening port (`443` by default).
 
 #### Attribute Statements
 
@@ -134,22 +144,98 @@ You can also right click on the "View IdP metadata" link and select
 
 ## Step 3/4. Create a SAML connector
 
-Define a SAML connector resource in a local file named `okta-connector.yaml`:
+Define an Okta SAML connector using `tctl`. Update this example command with
+the path to your metadata file, and edit the `--attributes-to-roles` values for
+custom group assignment to roles. See [tctl sso configure
+saml](../../reference/cli.mdx#tctl-sso-configure-saml) for a full reference of
+flags for this command:
 
-```yaml
-(!examples/resources/saml-connector.yaml!)
+```code
+$ tctl sso configure saml --preset=okta \
+--entity-descriptor <Var name="https://example.okta.com/app/000000/sso/saml/metadata"/> \
+--attributes-to-roles=groups,okta-admin,editor \
+--attributes-to-roles=groups,okta-dev,access > okta.yaml
 ```
 
-Update the value of `acs` with your Teleport Proxy address or Enterprise Cloud tenant
-(e.g. `mytenant.teleport.sh`), and replace the value of `entity_descriptor_url`
-with the path you copied in the previous step.
+The contents of `okta.yaml` should resemble the following:
+
+```yaml
+kind: saml
+metadata:
+  name: okta
+spec:
+  acs: https://teleport.example.com:443/v1/webapi/saml/acs/okta
+  attributes_to_roles:
+  - name: groups
+    roles:
+    - editor
+    value: okta-admin
+  - name: groups
+    roles:
+    - access
+    value: okta-dev
+  audience: https://teleport.example.com:443/v1/webapi/saml/acs/okta
+  cert: ""
+  display: "Okta"
+  entity_descriptor: ""
+  entity_descriptor_url: https://example.okta.com/app/000000/sso/saml/metadata
+  issuer: ""
+  service_provider_issuer: https://teleport.example.com:443/v1/webapi/saml/acs/okta
+  sso: ""
+version: v2
+```
 
 The `attributes_to_roles` field in the connector resource maps key/value-like attributes of
 the assertion from Okta into a list of Teleport roles to apply to the session.
 
 (!docs/pages/includes/sso/idp-initiated.mdx!)
 
-Create the connector using `tctl` tool:
+You can test the connector before applying it to your cluster. This is strongly
+encouraged to avoid interruption to active clusters:
+
+```code
+$ cat okta.yaml | tctl sso test
+If browser window does not open automatically, open it by clicking on the link:
+ http://127.0.0.1:52519/0222b1ca...
+Success! Logged in as: alice@example.com
+--------------------------------------------------------------------------------
+Authentication details:
+   roles:
+   - editor
+   - access
+   traits:
+     groups:
+     - Everyone
+     - okta-admin
+     - okta-dev
+     username:
+     - alice@example.com
+   username: alice@example.com
+--------------------------------------------------------------------------------
+[SAML] Attributes to roles:
+- name: groups
+  roles:
+  - editor
+  value: okta-admin
+- name: groups
+  roles:
+  - access
+  value: okta-dev
+
+--------------------------------------------------------------------------------
+[SAML] Attributes statements:
+groups:
+- Everyone
+- okta-admin
+- okta-dev
+username:
+- alice@example.com
+
+--------------------------------------------------------------------------------
+For more details repeat the command with --debug flag.
+```
+
+Create the connector using `tctl`:
 
 ```code
 $ tctl create okta-connector.yaml
diff --git a/docs/pages/includes/enterprise/samlauthentication.mdx b/docs/pages/includes/enterprise/samlauthentication.mdx
index b9b8fbb8b247a..f105e636f6ef6 100644
--- a/docs/pages/includes/enterprise/samlauthentication.mdx
+++ b/docs/pages/includes/enterprise/samlauthentication.mdx
@@ -8,18 +8,7 @@ user database.
   </ScopedBlock>
 
   <Tabs>
-  <TabItem label="Static Config (Self-Hosted)" scope={["oss", "enterprise"]}>
-
-  Update `/etc/teleport.yaml` in the `auth_service` section and restart the `teleport` daemon.
-
-  ```yaml
-  auth_service:
-    authentication:
-      type: saml
-  ```
-
-  </TabItem>
-  <TabItem scope={["cloud"]} label="Dynamic Resources (All Editions)">
+  <TabItem scope={["cloud", "oss", "enterprise"]} label="Dynamic Resources (All Editions)">
 
   Use `tctl` to edit the `cluster_auth_preference` value:
 
@@ -47,5 +36,22 @@ user database.
   cluster auth preference has been updated
   ```
 
+  </TabItem>
+  <TabItem label="Static Config (Self-Hosted)" scope={["oss", "enterprise"]}>
+
+  Update `/etc/teleport.yaml` in the `auth_service` section and restart the `teleport` daemon.
+
+  ```yaml
+  auth_service:
+    authentication:
+      type: saml
+  ```
+
   </TabItem>
   </Tabs>
+
+  <Admonition type="tip">
+
+  If you need to log in again before configuring your SAML provider, use the flag <nobr>`--auth=local`</nobr>.
+
+  </Admonition>
diff --git a/docs/pages/includes/sso/idp-initiated.mdx b/docs/pages/includes/sso/idp-initiated.mdx
index 9af9706df51ce..9003c75652bba 100644
--- a/docs/pages/includes/sso/idp-initiated.mdx
+++ b/docs/pages/includes/sso/idp-initiated.mdx
@@ -1,5 +1,5 @@
 <Details title="IdP-initiated SSO">
-    Enabling the `allow_idp_initiated` flag in SAML connectors allows users to
+    Enabling the `spec.allow_idp_initiated` flag in SAML connectors allows users to
     log in to Teleport with one click from the dashboard provided by the IdP.
 
     This feature is potentially unsafe and should be used with caution.