[docs] Guide how to add SAML to a deployment (#523)

* [docs] Guide how to add SAML to a deployment

* Update docs/guides/configuring-sso-ec-deployment.md

Co-authored-by: Toby Brain <[email protected]>

* Update docs/guides/configuring-sso-ec-deployment.md

Co-authored-by: Toby Brain <[email protected]>

* Update docs/guides/configuring-sso-ec-deployment.md

Co-authored-by: Toby Brain <[email protected]>

* Update docs/guides/configuring-sso-ec-deployment.md

Co-authored-by: Toby Brain <[email protected]>

* Update docs/guides/configuring-sso-ec-deployment.md

Co-authored-by: Toby Brain <[email protected]>

* Update docs/guides/configuring-sso-ec-deployment.md

Co-authored-by: Toby Brain <[email protected]>

* fixing cla

Co-authored-by: Toby Brain <[email protected]>

docs/guides/configuring-sso-ec-deployment.md

@@ -0,0 +1,104 @@
+---
+subcategory: ""
+page_title: "Configuring an SSO provider for a deployment"
+description: |-
+    An example of how to create a deployment preconfigured with a SAML provider
+---
+
+# Configuring a SAML provider for an Elastic Cloud Deployment
+
+A common use case for the Elastic Cloud Terraform provider is to spin up an Elastic Cloud deployment preconfigured with an SSO Identity provider (SAML2.0 or OIDC based) 
+
+Relying on the URL generated by Elastic Cloud creates a cyclic dependency, where the Elasticsearch cluster configuration requires the Kibana URL, which only exists after the deployment is created. You can avoid the cyclic dependency by configuring the deployment with an alias, which allows you to know the final Kibana URL before the deployment is created.
+
+*Please note, this guide doesn't go through what's needed to be configured on the IDP side, as this can change for different identity providers*
+
+First, create a "random_uuid" resource:
+
+```hcl
+resource "random_uuid" "uuid" {}
+```
+
+This will allow you to use a randomly generated `uuid` in the deployment name, so that you can later use it within the alias and retrieve a unique deployment name and URL alias, even before the deployment is actually created.
+
+Here is an example on how to create the "ec_deployment" resource:
+
+```hcl
+resource "ec_deployment" "elastic-sso" {
+  name                   = format("%s-%s", var.name, substr("${random_uuid.uuid.result}", 0, 6))
+  alias                  = format("%s-%s", var.name, substr("${random_uuid.uuid.result}", 0, 6))
+  region                 = "us-east-1"
+  version                = "7.17.5"
+  deployment_template_id = "aws-compute-optimized-v3"
+
+  elasticsearch {
+    topology {
+      id         = "hot_content"
+      size       = "8g"
+      zone_count = 2
+    }
+
+    topology {
+      id         = "warm"
+      size       = "8g"
+      zone_count = 2
+    }
+
+    config {
+      # The URL domain suffix that is used in this example is often different for other Elasticsearch Service regions. Please check the appropriate domain suffix for your used region.
+      user_settings_yaml = templatefile("./es.yml", { kibana_url = format("https://%s-%s.kb.us-east-1.aws.found.io:9243", var.name, substr("${random_uuid.uuid.result}", 0, 6)) })
+    }
+  }
+
+  kibana {
+    config {
+      user_settings_yaml = file("./kb.yml")
+    }
+  }
+}
+
+```
+
+Let's take a closer look at one specific argument here:
+
+```hcl
+format("%s-%s",var.name,substr("${random_uuid.uuid.result}",0,6))
+```
+
+This will tell terraform to create a string, that looks like  `<deployment-name>-<6-digits-of-uuid>`
+You will configure the deployment alias field to be the same, so if the deployment is named "elastic-sso" it gets created as follows: `elastic-sso-8f9f6s`
+
+Then, by using a variable in the `es.yml` file and a terraform templating mechanism, you can generate your own `es.yml` file. Your variable is named kibana_url, as seen in the ec_deployment resource:
+
+```hcl
+    config{
+           user_settings_yaml = templatefile("./es.yml",{kibana_url=format("https://%s-%s.kb.us-east-1.aws.found.io:9243",var.name,substr("${random_uuid.uuid.result}",0,6))})
+        }
+```
+
+This specific template uses your name and UUID to determine the URL for the Elasticsearch deployment before it is even created, and stores it in the `es.yml` file.
+
+```yaml
+xpack.security.authc.realms.saml.auth0:
+  order: 2
+  idp.metadata.path: "https://<url-for-provider's metadata>"
+  idp.entity_id: "urn:myproject.us.auth0.com"
+  sp.entity_id:  "${kibana_url}/"
+  sp.acs: "${kibana_url}/api/security/saml/callback"
+  sp.logout: "${kibana_url}/logout"
+  attributes.principal: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"
+  attributes.groups: "http://schemas.xmlsoap.org/claims/Group"
+```
+
+The kibana file should also contain the SSO provider configuration for Kibana to display it as a login option:
+
+```yaml
+xpack.security.authc.providers:
+    saml.auth0:
+        order: 1
+        realm: auth0
+        icon: logoSecurity
+        description: "Log in with Auth0"
+```
+
+And that's it! Spinning up the ec_deployment resource will create a deployment on Elastic Cloud, with a preconfigured name and an additional Auth0 SSO identity provider and login option, that's already configured when the deployment is spun up.