From d11de3e3375536aadc425e728755b1832fea7ccf Mon Sep 17 00:00:00 2001 From: sshahcodes Date: Tue, 9 Jan 2024 14:26:18 -0500 Subject: [PATCH 1/6] add service provider with entity id and acs url. make entity descriptor optional config --- .../pages/access-controls/idps/saml-guide.mdx | 145 +++++++++++------- 1 file changed, 92 insertions(+), 53 deletions(-) diff --git a/docs/pages/access-controls/idps/saml-guide.mdx b/docs/pages/access-controls/idps/saml-guide.mdx index 11ba807661f29..bd4e027d6cf3b 100644 --- a/docs/pages/access-controls/idps/saml-guide.mdx +++ b/docs/pages/access-controls/idps/saml-guide.mdx @@ -15,69 +15,98 @@ authenticate to external services. - (!docs/pages/includes/tctl.mdx!) - If you're new to SAML, consider reviewing our [SAML Identity Provider -Reference](./saml-reference.mdx) before proceeding. - -## Example external application - -We'll be using [samltest.id](https://samltest.id/) to create a test consumer of -Teleport's SAML identity provider. - -## Step 1/4. Configure a Teleport role with access to SAML service provider objects - -First, ensure you are logged into Teleport as a user that has permissions -to read and modify `saml_idp_service_provider` objects. The default `editor` role -has access to this already, but in case you are using a more customized configuration, -create a role called `sp-manager.yaml` with the following contents: - + Reference](./saml-reference.mdx) before proceeding. +- User with preset `editor` role. We recommend creating a dedicated role to manage +Service Provider. + + +
+ First, ensure you are logged into Teleport as a user that has permissions + to read and modify `saml_idp_service_provider` objects. The default `editor` role + has access to this already, but in case you are using a more customized configuration, + create a role called `sp-manager.yaml` with the following contents: + + ```yaml + kind: role + metadata: + name: sp-manager + spec: + allow: + rules: + - resources: + - saml_idp_service_provider + verbs: + - list + - create + - read + - update + - delete + version: v7 + ``` + + Create the role with `tctl`: + + ```code + $ tctl create sp-manager.yaml + role 'saml-idp-service-provider-manager' has been created + ``` + + Add the role to your user. Replace `teleport-admin` with your user name: + + ```code + $ tctl users update --set-roles $(tctl get users/ --format=json | \ + jq -r '.[].spec.roles | join(",")'), sp-manager + User teleport-admin has been updated: + New roles: auditor,editor,access,sp-manager + ``` +
+ +- Test SAML application, also known as SAML Service Provider (SP). For this guide, we'll be using +[samltest.id](https://samltest.id/) to create a test consumer of Teleport's SAML IdP. + +## Step 1/3. Add samltest.id 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. +2. **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: ```yaml -kind: role +kind: saml_idp_service_provider metadata: - name: sp-manager + # 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 spec: - allow: - rules: - - resources: - - saml_idp_service_provider - verbs: - - list - - create - - read - - update - - delete -version: v7 -``` - -Create the role with `tctl`: - -```code -$ tctl create sp-manager.yaml -role 'saml-idp-service-provider-manager' has been created + # entity_id is the metadata endpoint of service provider + # that serves entity descriptor, aka SP metadata. + entity_id: https://samltest.id/saml/sp + # acs_url is the endpoint where users will be redirected after + # SAML authentication. + acs_url: https://samltest.id/idp/profile/SAML2/POST/SSO +version: v1 ``` -Add the role to your user. Replace `teleport-admin` with your user name: +Add the spec to Teleport using `tctl`: ```code -$ tctl users update --set-roles $(tctl get users/ --format=json | \ -jq -r '.[].spec.roles | join(",")'), sp-manager -User teleport-admin has been updated: - New roles: auditor,editor,access,sp-manager +$ tctl create saml-sp.yaml +# SAML IdP service provider 'samltest-id' has been created. ``` +Teleport now trusts the samltest.id service provider. -## Step 2/4. Configure samltest.id to recognize Teleport's identity provider - -The first step in configuring the application for SSO is retrieving Teleport's -SAML identity provider metadata. You can obtain this metadata in XML format by -navigating to `https:///enterprise/saml-idp/metadata`. Save -it in an easy to remember file name like `teleport-metadata.xml`. - -Navigate to https://samltest.id and click on "Upload Metadata." Next, choose to upload -`teleport-metadata.xml`. + +Teleport tries to fetch an entity descriptor by quering Entity ID endpoint. +If an entity descriptor is not found in that endpoint, Teleport will generate +a new entity descriptor with the given Entity ID and ACS URL values. -![Successful upload](../../../img/access-controls/saml-idp/samltestid-0-successful-upload.png) +If you need a manual control over configuring entity descriptor, you may also directly add +it in the `saml_idp_service_provider` spec. -## Step 3/4. Obtain the service provider metadata and add it to Teleport +
-Download the service provider metadata from samltest.id as `saml-sp.xml`: +First download the service provider metadata from samltest.id as `saml-sp.xml`: ```code $ curl -o saml-sp.xml https://samltest.id/saml/sp @@ -106,10 +135,20 @@ Add this to Teleport using `tctl`: $ tctl create saml-sp.yaml # SAML IdP service provider 'samltest-id' has been created. ``` +
+ -Teleport now trusts the samltest.id service provider. +## Step 2/3. Configure samltest.id to recognize Teleport's SAML IdP + +First, obtain Teleport SAML IdP metadata by navigating to `https:///enterprise/saml-idp/metadata`. +Save it in an easy to remember file name like `teleport-metadata.xml`. + +Now navigate to https://samltest.id and click on "Upload Metadata." Next, choose to upload +`teleport-metadata.xml`. + +![Successful upload](../../../img/access-controls/saml-idp/samltestid-0-successful-upload.png) -## Step 4/4. Verify samltest.id login works +## Step 3/3. Verify samltest.id login works 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, From 448992b88644f1111acec689f19c6aa848c7b08a Mon Sep 17 00:00:00 2001 From: sshahcodes Date: Tue, 9 Jan 2024 15:55:15 -0500 Subject: [PATCH 2/6] move dedicate role creation to end of the guide --- .../pages/access-controls/idps/saml-guide.mdx | 90 +++++++++---------- 1 file changed, 45 insertions(+), 45 deletions(-) diff --git a/docs/pages/access-controls/idps/saml-guide.mdx b/docs/pages/access-controls/idps/saml-guide.mdx index bd4e027d6cf3b..7316978b3a4e7 100644 --- a/docs/pages/access-controls/idps/saml-guide.mdx +++ b/docs/pages/access-controls/idps/saml-guide.mdx @@ -16,51 +16,7 @@ authenticate to external services. - (!docs/pages/includes/tctl.mdx!) - If you're new to SAML, consider reviewing our [SAML Identity Provider Reference](./saml-reference.mdx) before proceeding. -- User with preset `editor` role. We recommend creating a dedicated role to manage -Service Provider. - - -
- First, ensure you are logged into Teleport as a user that has permissions - to read and modify `saml_idp_service_provider` objects. The default `editor` role - has access to this already, but in case you are using a more customized configuration, - create a role called `sp-manager.yaml` with the following contents: - - ```yaml - kind: role - metadata: - name: sp-manager - spec: - allow: - rules: - - resources: - - saml_idp_service_provider - verbs: - - list - - create - - read - - update - - delete - version: v7 - ``` - - Create the role with `tctl`: - - ```code - $ tctl create sp-manager.yaml - role 'saml-idp-service-provider-manager' has been created - ``` - - Add the role to your user. Replace `teleport-admin` with your user name: - - ```code - $ tctl users update --set-roles $(tctl get users/ --format=json | \ - jq -r '.[].spec.roles | join(",")'), sp-manager - User teleport-admin has been updated: - New roles: auditor,editor,access,sp-manager - ``` -
- +- User with permission to create Service Provider resource. The preset `editor` role has this permission. - Test SAML application, also known as SAML Service Provider (SP). For this guide, we'll be using [samltest.id](https://samltest.id/) to create a test consumer of Teleport's SAML IdP. @@ -166,3 +122,47 @@ This has verified service provider initiated SSO. To verify identity provider in SSO, navigate to `https:///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. + + +## Optional: Creating dedicated role to manage Service Provider + +For production, we recommend creating a dedicated role to manage Service Provider. + +To create dedicated role, first, ensure you are logged into Teleport as a user that has +permissions to read and modify `saml_idp_service_provider` objects. The default `editor` role +has access to this already, but in case you are using a more customized configuration, +create a role called `sp-manager.yaml` with the following contents: + +```yaml +kind: role +metadata: + name: sp-manager +spec: + allow: + rules: + - resources: + - saml_idp_service_provider + verbs: + - list + - create + - read + - update + - delete +version: v7 +``` + +Create the role with `tctl`: + +```code +$ tctl create sp-manager.yaml +role 'saml-idp-service-provider-manager' has been created +``` + +Add the role to your user. Replace `teleport-admin` with your user name: + +```code +$ tctl users update --set-roles $(tctl get users/ --format=json | \ +jq -r '.[].spec.roles | join(",")'), sp-manager +User teleport-admin has been updated: + New roles: auditor,editor,access,sp-manager +``` \ No newline at end of file From 9eaa7ed116cb44b11ca7f10fcde654eae44f7951 Mon Sep 17 00:00:00 2001 From: sshahcodes Date: Mon, 15 Jan 2024 13:26:22 -0500 Subject: [PATCH 3/6] review comments: - copy edits - use add-role-to-user.mdx to reference role update --- .../pages/access-controls/idps/saml-guide.mdx | 29 ++++++++----------- 1 file changed, 12 insertions(+), 17 deletions(-) diff --git a/docs/pages/access-controls/idps/saml-guide.mdx b/docs/pages/access-controls/idps/saml-guide.mdx index 7316978b3a4e7..23bb7b7588a6b 100644 --- a/docs/pages/access-controls/idps/saml-guide.mdx +++ b/docs/pages/access-controls/idps/saml-guide.mdx @@ -17,7 +17,7 @@ authenticate to external services. - If you're new to SAML, consider reviewing our [SAML Identity Provider Reference](./saml-reference.mdx) before proceeding. - User with permission to create Service Provider resource. The preset `editor` role has this permission. -- Test SAML application, also known as SAML Service Provider (SP). For this guide, we'll be using +- Test SAML application, also known as SAML Service Provider (SP). For this guide, we'll be using [samltest.id](https://samltest.id/) to create a test consumer of Teleport's SAML IdP. ## Step 1/3. Add samltest.id Service Provider to Teleport @@ -35,8 +35,8 @@ metadata: # service provider as well as in identity provider initiated SSO. name: samltest-id spec: - # entity_id is the metadata endpoint of service provider - # that serves entity descriptor, aka SP metadata. + # entity_id is the metadata endpoint of service provider + # that serves entity descriptor, aka SP metadata. entity_id: https://samltest.id/saml/sp # acs_url is the endpoint where users will be redirected after # SAML authentication. @@ -53,14 +53,14 @@ $ tctl create saml-sp.yaml Teleport now trusts the samltest.id service provider. -Teleport tries to fetch an entity descriptor by quering Entity ID endpoint. -If an entity descriptor is not found in that endpoint, Teleport will generate +Teleport tries to fetch an entity descriptor by quering 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. -If you need a manual control over configuring entity descriptor, you may also directly add -it in the `saml_idp_service_provider` spec. +If you need more control over the entity descriptor, you may also add it directly +to the `saml_idp_service_provider` spec. -
+
First download the service provider metadata from samltest.id as `saml-sp.xml`: @@ -96,7 +96,7 @@ $ tctl create saml-sp.yaml ## Step 2/3. Configure samltest.id to recognize Teleport's SAML IdP -First, obtain Teleport SAML IdP metadata by navigating to `https:///enterprise/saml-idp/metadata`. +First, obtain your Teleport SAML IdP metadata by navigating to `https:///enterprise/saml-idp/metadata`. Save it in an easy to remember file name like `teleport-metadata.xml`. Now navigate to https://samltest.id and click on "Upload Metadata." Next, choose to upload @@ -128,7 +128,7 @@ You should be redirected to the same successful login page seen earlier. For production, we recommend creating a dedicated role to manage Service Provider. -To create dedicated role, first, ensure you are logged into Teleport as a user that has +To create a dedicated role, first, ensure you are logged into Teleport as a user that has permissions to read and modify `saml_idp_service_provider` objects. The default `editor` role has access to this already, but in case you are using a more customized configuration, create a role called `sp-manager.yaml` with the following contents: @@ -158,11 +158,6 @@ $ tctl create sp-manager.yaml role 'saml-idp-service-provider-manager' has been created ``` -Add the role to your user. Replace `teleport-admin` with your user name: +Next, add the role to your user. -```code -$ tctl users update --set-roles $(tctl get users/ --format=json | \ -jq -r '.[].spec.roles | join(",")'), sp-manager -User teleport-admin has been updated: - New roles: auditor,editor,access,sp-manager -``` \ No newline at end of file +(!docs/pages/includes/add-role-to-user.mdx role="(!docs/pages/includes/add-role-to-user.mdx role="sp-manager"!)"!) From 82414fb9e18a541cc212a3984cf2bc089d5c6959 Mon Sep 17 00:00:00 2001 From: sshahcodes Date: Fri, 19 Jan 2024 16:49:12 -0500 Subject: [PATCH 4/6] reference content of entity descrptor takes priority over other values --- .../pages/access-controls/idps/saml-guide.mdx | 22 ++++++++++++++----- 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/docs/pages/access-controls/idps/saml-guide.mdx b/docs/pages/access-controls/idps/saml-guide.mdx index 23bb7b7588a6b..4cfe563c7b62c 100644 --- a/docs/pages/access-controls/idps/saml-guide.mdx +++ b/docs/pages/access-controls/idps/saml-guide.mdx @@ -50,12 +50,11 @@ Add the spec to Teleport using `tctl`: $ tctl create saml-sp.yaml # SAML IdP service provider 'samltest-id' has been created. ``` -Teleport now trusts the samltest.id service provider. - -Teleport tries to fetch an entity descriptor by quering the Entity ID endpoint. +The above configuration shows creating Service Provider without an entity descriptor. +In this scenario, Teleport first tries to fetch an entity descriptor by quering 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. +a new entity descriptor with the given `entity_id` and `acs_url` values. If you need more control over the entity descriptor, you may also add it directly to the `saml_idp_service_provider` spec. @@ -92,11 +91,22 @@ $ tctl create saml-sp.yaml # SAML IdP service provider 'samltest-id' has been created. ```
+ + +If an entity descrpitor 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 descrpitor to be present in the Service Provider spec. As such, when updating +Service Provider, you should first fetch the spec that is stored in Teleport and only then edit the configruation. +```code +# get service provider spec +$ tctl get saml_idp_service_provider/ > service-provider.yml +``` ## Step 2/3. Configure samltest.id to recognize Teleport's SAML IdP -First, obtain your Teleport SAML IdP metadata by navigating to `https:///enterprise/saml-idp/metadata`. +First, obtain your Teleport SAML IdP metadata by navigating to `https:///enterprise/saml-idp/metadata`. Save it in an easy to remember file name like `teleport-metadata.xml`. Now navigate to https://samltest.id and click on "Upload Metadata." Next, choose to upload @@ -160,4 +170,4 @@ 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="(!docs/pages/includes/add-role-to-user.mdx role="sp-manager"!)"!) +(!docs/pages/includes/add-role-to-user.mdx role="sp-manager"!) From a746ab90fad3dc00b6698c18e784b460f8c0003c Mon Sep 17 00:00:00 2001 From: sshahcodes Date: Mon, 22 Jan 2024 19:33:59 -0500 Subject: [PATCH 5/6] copy edits: - use lower case for service provider - use generic service provider name instead of directly referencing samltest.id - update test saml application copy --- .../pages/access-controls/idps/saml-guide.mdx | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/pages/access-controls/idps/saml-guide.mdx b/docs/pages/access-controls/idps/saml-guide.mdx index 4cfe563c7b62c..caf8bea267b96 100644 --- a/docs/pages/access-controls/idps/saml-guide.mdx +++ b/docs/pages/access-controls/idps/saml-guide.mdx @@ -16,14 +16,14 @@ authenticate to external services. - (!docs/pages/includes/tctl.mdx!) - If you're new to SAML, consider reviewing our [SAML Identity Provider Reference](./saml-reference.mdx) before proceeding. -- User with permission to create Service Provider resource. The preset `editor` role has this permission. -- Test SAML application, also known as SAML Service Provider (SP). For this guide, we'll be using -[samltest.id](https://samltest.id/) to create a test consumer of Teleport's SAML IdP. +- 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. -## Step 1/3. Add samltest.id Service Provider to Teleport +## 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. +The minimum configuration values required to add a service provider are: +1. **Entity ID:** The SAML metadata endpoint of the service provider. 2. **ACS URL:** The endpoint where users will be redirected after SAML authentication. ACS URL is also referred to as SAML SSO URL. @@ -51,7 +51,7 @@ $ tctl create saml-sp.yaml # SAML IdP service provider 'samltest-id' has been created. ``` -The above configuration shows creating Service Provider without an entity descriptor. +The above configuration shows creating service provider without an entity descriptor. In this scenario, Teleport first tries to fetch an entity descriptor by quering 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. @@ -95,16 +95,16 @@ $ tctl create saml-sp.yaml If an entity descrpitor 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 descrpitor to be present in the Service Provider spec. As such, when updating -Service Provider, you should first fetch the spec that is stored in Teleport and only then edit the configruation. +Teleport only tries to fetch or generate entity descriptor when service provider is created for the first time. +Subsequent updates require an entity descrpitor to be present in the service provider spec. As such, when updating +service provider, you should first fetch the spec that is stored in Teleport and only then edit the configruation. ```code # get service provider spec $ tctl get saml_idp_service_provider/ > service-provider.yml ``` -## Step 2/3. Configure samltest.id to recognize Teleport's SAML IdP +## Step 2/3. Configure the service provider to recognize Teleport's SAML IdP First, obtain your Teleport SAML IdP metadata by navigating to `https:///enterprise/saml-idp/metadata`. Save it in an easy to remember file name like `teleport-metadata.xml`. @@ -134,9 +134,9 @@ where `samltest-id` is the friendly name of the service provider object created You should be redirected to the same successful login page seen earlier. -## Optional: Creating dedicated role to manage Service Provider +## Optional: Creating dedicated role to manage service provider -For production, we recommend creating a dedicated role to manage Service Provider. +For production, we recommend creating a dedicated role to manage service provider. To create a dedicated role, first, ensure you are logged into Teleport as a user that has permissions to read and modify `saml_idp_service_provider` objects. The default `editor` role From c219c7e8fb8442ff13ee7f4b0d89c0bac6274148 Mon Sep 17 00:00:00 2001 From: sshahcodes Date: Mon, 22 Jan 2024 19:47:07 -0500 Subject: [PATCH 6/6] fix typo --- docs/pages/access-controls/idps/saml-guide.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/pages/access-controls/idps/saml-guide.mdx b/docs/pages/access-controls/idps/saml-guide.mdx index caf8bea267b96..2ec16f7fcab5a 100644 --- a/docs/pages/access-controls/idps/saml-guide.mdx +++ b/docs/pages/access-controls/idps/saml-guide.mdx @@ -52,7 +52,7 @@ $ tctl create saml-sp.yaml ``` The above configuration shows creating service provider without an entity descriptor. -In this scenario, Teleport first tries to fetch an entity descriptor by quering the `entity_id` endpoint. +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. @@ -93,11 +93,11 @@ $ tctl create saml-sp.yaml
-If an entity descrpitor 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 descrpitor to be present in the service provider spec. As such, when updating -service provider, you should first fetch the spec that is stored in Teleport and only then edit the configruation. +Subsequent updates require an entity descriptor to be present in the service provider spec. As such, when updating +service provider, you should first fetch the spec that is stored in Teleport and only then edit the configuration. ```code # get service provider spec $ tctl get saml_idp_service_provider/ > service-provider.yml