[v12] Docs: Update Okta SSO Guide

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

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>

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.