Add OneLogin entity descriptor URL instructions (#44948)

Closes #24803 Show how to include the entity descriptor URL for OneLogin when configuring the authentication connector. In `tctl sso configure`, the flag is the same if you are using a URL or a local file. The current guide includes a separate H3 for downloading the XML file. This change uses a single set of numbered steps to make the instructions easier to follow.
gravitational · Aug 13, 2024 · 3f7da83 · 3f7da83
1 parent 9b2bd40
commit 3f7da83
Showing 1 changed file with 49 additions and 42 deletions.
diff --git a/docs/pages/access-controls/sso/one-login.mdx b/docs/pages/access-controls/sso/one-login.mdx
@@ -25,69 +25,76 @@ to define policies like:
 
 ## Step 1/3. Create Teleport application in OneLogin
 
-In the OneLogin control panel's main menu navigate to **Applications** ->
-**Add App**. Using the search box, select "SAML Custom Connector (SP Shibboleth)":
+1. In the OneLogin control panel's main menu navigate to **Applications** ->
+   **Add App**. Using the search box, select "SAML Custom Connector (SP
+   Shibboleth)":
 
-![SAML Custom Connector (SP Shibboleth)](../../../img/sso/onelogin/onelogin-saml-1.png)
+   ![SAML Custom Connector (SP Shibboleth)](../../../img/sso/onelogin/onelogin-saml-1.png)
 
-Define the new application:
+1. Define the new application:
 
-![SAML Config](../../../img/sso/onelogin/onelogin-saml-1a.png)
+   ![SAML Config](../../../img/sso/onelogin/onelogin-saml-1a.png)
 
-You can find Teleport icons to upload from the following links:
+   You can find Teleport icons to upload from the following links:
 
-- [Square Icon](../../../img/sso/onelogin/teleport.png)
-- [Rectangular Icon](../../../img/sso/onelogin/teleportlogo@2x.png)
+   - [Square Icon](../../../img/sso/onelogin/teleport.png)
+   - [Rectangular Icon](../../../img/sso/onelogin/teleportlogo@2x.png)
 
-From the application's **Configuration** page, set the following values:
+1. From the application's **Configuration** page, set the following values:
 
-<Admonition type="tip">
-Set <Var name="teleport.example.com:443" description="Your Teleport Proxy Service address and port, or cloud tenant." />
-here with your Teleport Proxy Service address and port, or Teleport Enterprise
-Cloud tenant (e.g. `company.teleport.sh:443`) to fill out the values below.
-</Admonition>
+   <Admonition type="tip">
+   Set <Var name="teleport.example.com:443" description="Your Teleport Proxy Service address and port, or cloud tenant." />
+   here with your Teleport Proxy Service address and port, or Teleport Enterprise
+   Cloud tenant (e.g. `company.teleport.sh:443`) to fill out the values below.
+   </Admonition>
+
+   - **Login URL**:
+     - `https://`<Var name="teleport.example.com:443"/>`/web/login`
+   - **ACS (Consumer) URL**, **SAML Recipient**, **ACS (Consumer) URL Validator**, & **Audience**:
+     - `https://`<Var name="teleport.example.com:443"/>`/v1/webapi/saml/acs/onelogin`
 
-- **Login URL**:
-  - `https://`<Var name="teleport.example.com:443"/>`/web/login`
-- **ACS (Consumer) URL**, **SAML Recipient**, **ACS (Consumer) URL Validator**, & **Audience**:
-  - `https://`<Var name="teleport.example.com:443"/>`/v1/webapi/saml/acs/onelogin`
+   ![Configure SAML](../../../img/sso/onelogin/onelogin-saml-2.png)
 
-![Configure SAML](../../../img/sso/onelogin/onelogin-saml-2.png)
+1. Teleport needs to assign groups to users. From the **Parameters** page,
+   configure the application with some parameters exposed as SAML attribute
+   statements:
 
-Teleport needs to assign groups to users. From the **Parameters** page, configure
-the application with some parameters exposed as SAML attribute statements:
+   ![New Field](../../../img/sso/onelogin/onelogin-saml-3.png)
+
+   ![New Field Group](../../../img/sso/onelogin/onelogin-saml-4.png)
+
+   <Admonition
+     type="warning"
+     title="Important"
+   >
+     Make sure to check `Include in SAML assertion` checkbox.
+   </Admonition>
 
-![New Field](../../../img/sso/onelogin/onelogin-saml-3.png)
+1. Add users to the application:
 
-![New Field Group](../../../img/sso/onelogin/onelogin-saml-4.png)
+   ![Add User](../../../img/sso/onelogin/onelogin-saml-5.png)
 
-<Admonition
-  type="warning"
-  title="Important"
->
-  Make sure to check `Include in SAML assertion` checkbox.
-</Admonition>
+1. Obtain SAML metadata for your authentication connector. Once the application
+   is set up, navigate to the the **More Actions** menu and find the **SAML
+   Metadata** option:
 
-Add users to the application:
+   ![Download XML](../../../img/sso/onelogin/saml-download.png)
 
-![Add User](../../../img/sso/onelogin/onelogin-saml-5.png)
-
-### Download SAML XML metadata
-
-Once the application is set up, download `SAML Metadata` from the
-**More Actions** menu:
-
-![Download XML](../../../img/sso/onelogin/saml-download.png)
+   You can either left-click the option and download the XML document as a local
+   file or right-click the option and copy the link address. The Teleport Auth
+   Service either reads the provided document or queries the address to obtain
+   SAML metadata. We recommend copying the address so the Auth Service can use
+   the most up-to-date information.
 
 ## Step 2/3. Create a SAML connector
 
-Create a SAML connector using `tctl`. Update
-<Var name="./onelogin_metadata_1234567.xml"/> with the path to the XML metadata
-file downloaded in the previous step:
+Create a SAML connector using `tctl`. Update <Var name="xml-path"/> to the URL
+of the XML document that you copied in the previous step. If you downloaded the
+XML document instead, use the path to the XML metadata file:
 
 ```code
 $ tctl sso configure saml --preset onelogin \
---entity-descriptor <Var name="./onelogin_metadata_1234567.xml"/> \
+--entity-descriptor <Var name="xml-path"/> \
 --attributes-to-roles groups,admin,editor \
 --attributes-to-roles groups,dev,access > onelogin.yaml
 ```