# Reference for the teleport\_saml\_idp\_service\_provider Terraform resource

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](#nested-schema-for-spec))
- `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](#nested-schema-for-metadata))
- `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](#nested-schema-for-specattribute_mapping))
- `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