Update SAML IdP getting started guide

docs/cspell.json

@@ -500,6 +500,7 @@
     "hsm-ppzzfxbleki",
     "httpout",
     "iamserviceaccount",
+    "iamshowcase",
     "idfile",
     "idps",
     "importcert",

docs/pages/access-controls/idps/saml-guide.mdx

@@ -18,56 +18,105 @@ authenticate to external services.
   Reference](./saml-reference.mdx) before proceeding.
 - User with permission to create service provider resource. The preset `editor` role has this permission.
 - SAML application (also known as a SAML service provider or SP) for testing. For this guide, we'll be using
-[samltest.id](https://samltest.id/) as a service provider for Teleport's SAML IdP.
+[RSA Simple Test Service Provider](https://sptest.iamshowcase.com/) - a free test service that
+lets us test Teleport SAML IdP. The test service has a protected page, which can be accessed only after a
+user is federated to the site with a valid SAML assertion flow.
+![iamshowcase protected page](../../../img/access-controls/saml-idp/iamshowcase-protected-page.png)
 
 ## Step 1/3. Add a service provider to Teleport
 
-The minimum configuration values required to add a service provider are:
-1. **Entity ID:** The SAML metadata endpoint of the service provider.
+To add a service provider to Teleport, you must configure a service provider
+metadata. This can be configured by either providing an **Entity ID** and **ACS URL** values of the
+service provider or by providing an entity descriptor value (also known as metadata file, which is an XML file)
+of the service provider.
+
+Below we'll show both of the configuration options.
+
+First, in the Web UI, under **Access Management**, click **Enroll New Resource** menu.
+In the search box, enter "saml", which will show the SAML application
+integration tile. Click the tile.
+
+![Enroll SAML app](../../../img/access-controls/saml-idp/enroll-saml-app.png)
+
+The first configuration step, **Configure Service Provider with Teleport's Identity Provider Metadata**
+shows Teleport SAML IdP metadata values. For this guide, you can move to next step by clicking **Next** button
+which takes to **Add Service Provider To Teleport** step.
+
+### Option 1: Configure with Entity ID and ACS URL
+
+With this option, the minimum configuration values required to add a service provider are:
+1. **Entity ID:** The SAML metadata value or an endpoint of the service provider.
 1. **ACS URL:** The endpoint where users will be redirected after SAML authentication. ACS URL
 is also referred to as SAML SSO URL.
 
-The following `saml_idp_service_provider` spec is a reference for adding samltest.id to Teleport:
+To configure Simple Test Service Provider, the values you need to provide are the following:
+- **App Name:** `iamshowcase`
+- **Entity ID:** `iamshowcase`
+- **ACS URL:** `https://sptest.iamshowcase.com/acs`
+
+Click **Finish** button, the `iamshowcase` app is now added to Teleport.
+
+<Details title="Reference `tctl` based configuration" closed>
+
+The following `saml_idp_service_provider` spec is a reference for adding Simple Test
+Service Provider to Teleport:
 ```yaml
 kind: saml_idp_service_provider
 metadata:
   # The friendly name of the service provider. This is used to manage the
   # service provider as well as in identity provider initiated SSO.
-  name: samltest-id
+  name: iamshowcase
 spec:
-  # entity_id is the metadata endpoint of service provider
+  # entity_id is the metadata value or an endpoint of service provider
   # that serves entity descriptor, aka SP metadata.
-  entity_id: https://samltest.id/saml/sp
+  entity_id: iamshowcase
   # acs_url is the endpoint where users will be redirected after
   # SAML authentication.
-  acs_url: https://samltest.id/idp/profile/SAML2/POST/SSO
+  acs_url: https://sptest.iamshowcase.com/acs
 version: v1
 ```
 
 Add the spec to Teleport using `tctl`:
 
 ```code
-$ tctl create saml-sp.yaml
-# SAML IdP service provider 'samltest-id' has been created.
+$ tctl create iamshowcase.yaml
+# SAML IdP service provider 'iamshowcase' has been created.
 ```
+</Details>
 
-The above configuration shows creating service provider without an entity descriptor.
-In this scenario, Teleport first tries to fetch an entity descriptor by querying the `entity_id` endpoint.
-If an entity descriptor is not found at that endpoint, Teleport will generate
-a new entity descriptor with the given `entity_id` and `acs_url` values.
+<Admonition type="note">
+With this configuration method, Teleport first tries to fetch an entity descriptor by
+querying the `entity_id` endpoint. If an entity descriptor is not found at that endpoint,
+Teleport will generate a new entity descriptor with the given `entity_id` and `acs_url` values.
+</Admonition>
+
+### Option 2: Configure with Entity Descriptor file
+
+If the service provider provides an option to download an entity descriptor file or you
+need more control over the entity descriptor, this is the recommended option to add a service provider
+to Teleport.
+
+With this option, you provide service provider entity descriptor file, which has all the details
+required to configure service provider metadata.
+
+![add entity descriptor](../../../img/access-controls/saml-idp/add-entity-descriptor.png)
 
-If you need more control over the entity descriptor, you may also add it directly
-to the `saml_idp_service_provider` spec.
+In the **Add Service Provider To Teleport** page, provide a SAML service provider name (`iamshowcase`).
+Now click **+ Add Entity Descriptor (optional)** button, which will expand entity descriptor editor.
+Copy Simple Test Service Provider metadata file, which is available at the URL `https://sptest.iamshowcase.com/testsp_metadata.xml`
+and paste it to entity descriptor editor in Teleport Web UI.
 
-<Details title="(Optional) Manually add entity descriptor" closed>
+Click **Finish** button, the `iamshowcase` app is now added to Teleport.
 
-First download the service provider metadata from samltest.id as `saml-sp.xml`:
+<Details title="Reference `tctl` based configuration" closed>
+
+First download the service provider metadata from Simple Test Service Provider as `iamshowcase.xml`:
 
 ```code
-$ curl -o saml-sp.xml https://samltest.id/saml/sp
+$ curl -o iamshowcase.xml https://sptest.iamshowcase.com/testsp_metadata.xml
 ```
 
-Using the template below, create a file called `saml-sp.yaml`. Assign the
+Using the template below, create a file called `iamshowcase.yaml`. Assign the
 metadata you just downloaded to the `entity_descriptor` field in the
 `saml_idp_service_provider` object:
 
@@ -76,7 +125,7 @@ kind: saml_idp_service_provider
 metadata:
   # The friendly name of the service provider. This is used to manage the
   # service provider as well as in identity provider initiated SSO.
-  name: samltest-id
+  name: iamshowcase
 spec:
   # The entity_descriptor is the service provider XML.
   entity_descriptor: |
@@ -87,13 +136,13 @@ version: v1
 Add this to Teleport using `tctl`:
 
 ```code
-$ tctl create saml-sp.yaml
+$ tctl create iamshowcase.yaml
 # SAML IdP service provider 'samltest-id' has been created.
 ```
 </Details>
 
 <Admonition type="important">
-If an entity descriptor is provided, it's content takes preference over values provided in `entity_id` and `acs_url`.
+If an `entity_descriptor` is provided, it's content takes preference over values provided in `entity_id` and `acs_url`.
 
 Teleport only tries to fetch or generate entity descriptor when service provider is created for the first time.
 Subsequent updates require an entity descriptor to be present in the service provider spec. As such, when updating
@@ -106,35 +155,39 @@ $ tctl get saml_idp_service_provider/<service provider name> > service-provider.
 
 ## Step 2/3. Configure the service provider to recognize Teleport's SAML IdP
 
-First, obtain your Teleport SAML IdP metadata by navigating to `https://<proxy-address>/enterprise/saml-idp/metadata`.
-Save it in an easy to remember file name like `teleport-metadata.xml`.
+This step varies from service provider to service provider. Some service provider may ask to
+provide Teleport SAML IdP Entity ID, SSO URL and X.509 certificate. Other's may ask to upload
+an Teleport SAML IdP metadata file.
+
+You will find these values in the Teleport Web UI under the
+**Configure Service Provider with Teleport's Identity Provider Metadata** UI which is the first step
+shown in the SAML app enrollment flow.
+
+![Teleport IdP metadata](../../../img/access-controls/saml-idp/teleport-idp-metadata.png)
 
-Now navigate to https://samltest.id and click on "Upload Metadata." Next, choose to upload
-`teleport-metadata.xml`.
+In the case of Simple Test Service Provider, which this guide is based on, the sample app is designed to grant access protected page
+for any well formatted IdP federated SAML assertion data.
 
-![Successful upload](../../../img/access-controls/saml-idp/samltestid-0-successful-upload.png)
+As such, when you click **Finish** button in the previous step, the protected page of the Simple Test Service Provider is
+already available to access under resources page.
 
-## Step 3/3. Verify samltest.id login works
+## Step 3/3. Verify access to iamshowcase protected page
 
-To verify everything works, navigate back to samltest.id's home page and select
-"Test Your IdP." From there, enter the entity ID of Teleport's identity provider,
-which is the same as the metadata URL: `https://<proxy-address>/enterprise/saml-idp/metadata`
-and click "Go!"
+To verify everything works, navigate to **Resources** page in Teleport Web UI.
 
-![Test the IdP](../../../img/access-controls/saml-idp/samltestid-1-test-idp.png)
+![Access app](../../../img/access-controls/saml-idp/access-app.png)
 
-If you are not already logged into Teleport, you will be prompted to login. Once you
-are logged in, you should be re-routed to a success page on samltest.id.
+The "iamshowcase" app will now appear under resources tile. Inside this tile,
+click **Login** button, which will now forward you to iamshowcase protected page.
 
-![Successful login](../../../img/access-controls/saml-idp/samltestid-2-successful-login.png)
+![Protected page access](../../../img/access-controls/saml-idp/protected-page-access.png)
 
-This has verified service provider initiated SSO. To verify identity provider initiated
-SSO, navigate to `https://<proxy-address>/enterprise/saml-idp/login/samltest-id`,
-where `samltest-id` is the friendly name of the service provider object created earlier.
-You should be redirected to the same successful login page seen earlier.
+This page shows Teleport user details along with other attributes such as roles are
+federated by Teleport SAML IdP.
 
+This demonstrates adding a service provider to Teleport configured with a working idp-initiated SSO login flow.
 
-## Optional: Creating dedicated role to manage service provider
+## Recommended: Creating dedicated role to manage service provider
 
 For production, we recommend creating a dedicated role to manage service provider.
 
@@ -171,3 +224,7 @@ role 'saml-idp-service-provider-manager' has been created
 Next, add the role to your user.
 
 (!docs/pages/includes/add-role-to-user.mdx role="sp-manager"!)
+
+
+## Next steps
+- Configure [SAML Attribute Mapping](./saml-attribute-mapping.mdx).