Skip to main content
Version: 19.x (unreleased)

Reference for the teleport_saml_idp_service_provider Terraform resource

Report an IssueView as Markdown

This page describes the supported values of the teleport_saml_idp_service_provider resource of the Teleport Terraform provider. The Teleport API allows providing an XML entity_descriptor, an entity_id, an acs_url. However, the entity_descriptor contains both the entity_id and acs_url values. The API disallows mutations if entity_id doesn't match the copy in entity_descriptor. It does not check acs_url, but will use the copy in entity_descriptor if they disagree. We therefore recommend using either entity_id and acs_url or entity_descriptor, but not both. However, the Terraform provider doesn't explicitly block using all 3 in order to match the underlying API.

The API also rewrites entity_descriptor with values from attribute_mapping. If they differ, this will cause the Terraform resource to be recreated on the next apply. To avoid this, either use attribute_mapping with entity_id+acs_url rather than entity_descriptor.

To prevent similar idempotency issues, the Terraform provider also requires full URNs for the attribute mapping name_format fields.

Example Usage​

resource "teleport_saml_idp_service_provider" "from_descriptor" {
  version = "v1"
  metadata = {
    name = "my-sp"
  }
  spec = {
    entity_descriptor = <<-EOT
      <?xml version="1.0" encoding="UTF-8"?>
      <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
          entityID="https://sp.example.com/saml/metadata">
        <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
          <md:AssertionConsumerService
              Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
              Location="https://sp.example.com/saml/acs"
              index="0"/>
        </md:SPSSODescriptor>
      </md:EntityDescriptor>
    EOT
    // If you set both entity_descriptor and attribute_mapping, the Teleport API
    // will add the attribute_mapping to the entity_descriptor, causing
    // the resource to change on every apply
    attribute_mapping = null
  }
}

resource "teleport_saml_idp_service_provider" "from_entity_id" {
  version = "v1"
  metadata = {
    name = "my-sp-2"
  }
  spec = {
    entity_id = "https://sp.example.com/saml/metadata"
    acs_url   = "https://sp.example.com/saml/acs"
    attribute_mapping = [
      {
        name = "username"
        // Note: the short forms (i.e. just "basic") are not supported by the
        // Terraform provider.
        name_format = "urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
        value       = "external.username"
      },
    ]
  }
}

Schema​

Required​

  • spec (Attributes) Spec is the SAML IdP service provider spec. (see below for nested schema)
  • version (String) Version is the API version used to create the resource. It must be specified. Based on this version, Teleport will apply different defaults on resource creation or deletion. It must be an integer prefixed by "v". For example: v1

Optional​

  • metadata (Attributes) Metadata is resource metadata (see below for nested schema)
  • sub_kind (String) SubKind is an optional resource sub kind, used in some resources

Nested Schema for spec​

Optional:

  • acs_url (String) ACSURL is the endpoint where SAML authentication response will be redirected.
  • attribute_mapping (Attributes List) AttributeMapping is used to map service provider requested attributes to username, role and traits in Teleport. (see below for nested schema)
  • entity_descriptor (String) EntityDescriptor is the entity descriptor for the service provider
  • entity_id (String) EntityID is the entity ID for the entity descriptor. If entity descriptor is provided, this value is checked that it matches the entity ID in the entity descriptor at upsert time to avoid having to parse the XML blob in the entity descriptor every time we need to use this resource.
  • launch_urls (List of String) LaunchURLs is used to configure custom landing URLs for service provider. It is useful in the following scenarios: 1. If a service provider does not support IdP initiated authentication, launch url can be configured to launch users directly into the service provider authentication endpoint. 2. If a service provider does support IdP initiated authentication, it can be useful if that service provider acts as a master authentication service provider for internal services. In such case, Teleport administrator can configure launch URL, that lets user pick a specific internal service URL from the Log In tile in the UI, which would take them to that particular service for authentication instead of directly launching to the master service provider. Each launch URL value must be an HTTPs endpoint.
  • preset (String) Preset is used to define service provider profile that will have a custom behavior processed by Teleport.
  • relay_state (String) RelayState is used to add custom value in the SAML response as a relay_state HTTP parameter. The value can contain service provider specific redirect URL, static state token etc. The value is only applied in the IdP initiated SSO flow.

Nested Schema for spec.attribute_mapping​

Optional:

  • name (String) name is an attribute name.
  • name_format (String) name_format is an attribute name format.
  • value (String) value is an attribute value definable with predicate expression.

Nested Schema for metadata​

Required:

  • name (String) Name is an object name

Optional:

  • description (String) Description is object description
  • expires (String) Expires is a global expiry time header can be set on any resource in the system.
  • labels (Map of String) Labels is a set of labels