---
type: api
title: Create SAML configuration
description: Creates a new SAML configuration.
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/cloud-enterprise/v4/operation/operation-create-saml-configuration
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/cloud-enterprise/v4/operation/operation-create-saml-configuration
products:
  - Elastic Cloud Enterprise
---

# Create SAML configuration

## Paths

- `POST` `/platform/configuration/security/realms/saml`

- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/cloud-enterprise/v4/authentication#basicauth)
- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/cloud-enterprise/v4/authentication#apikey)

## Description

Creates a new SAML configuration.

## Request Body

`application/json`

The SAML configuration

- `id` (string) — required
  The identifier for the security realm
- `name` (string) — required
  The friendly name of the security realm
- `idp` ({} SamlIdpSettings) — required
  The configuration for the Elasticsearch security SAML Identity Provider.
  - `entity_id` (string) — required
    The Entity ID of the SAML Identity Provider. An Entity ID is a URI with a maximum length of 1024 characters. It can be a URL or a URN and can be found in the configuration or the SAML metadata of the Identity Provider.
  - `metadata_path` (string) — required
    The URL to a SAML 2.0 metadata file describing the capabilities and configuration of the Identity Provider
  - `use_single_logout` (boolean) — optional
    Indicates whether to utilise the Identity Provider's Single Logout service
- `sp` ({} SamlSpSettings) — required
  The configuration for the Elasticsearch security SAML Service Provider.
  - `entity_id` (string) — required
    The Entity ID to use for this SAML Service Provider. This should be entered as a URI.
  - `acs` (string) — required
    The URL of the Assertion Consumer service
  - `logout` (string) — required
    The URL of the Single Logout service
- `attributes` ({} SamlAttributeSettings) — required
  The mapping configuration for the Elasticsearch security SAML attribute.
  - `principal` (string) — required
    The name of the SAML attribute that contains the user's principal (username). This name should map to a value that does not contain commas or slashes.
  - `groups` (string) — required
    The name of the SAML attribute that contains the user's groups
  - `name` (string) — optional
    The name of the SAML attribute that contains the user's full name
  - `mail` (string) — optional
    The name of the SAML attribute that contains the user's email address
  - `dn` (string) — optional
    The name of the SAML attribute that contains the user's X.50 Distinguished Name
- `nameid_format` (string) — optional
  The NameID format. If not specified the IdP default is used. Example: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
- `role_mappings` ({} SamlSecurityRealmRoleMappingRules) — optional
  The mapping ruleset for the Elasticsearch security SAML role.
  - `default_roles` ([] string) — required
    The default roles applied to all users
  - `rules` ([] SamlSecurityRealmRoleMappingRule) — required
    The role mapping rules to evaluate
    - `type` (enum) — required
      The type of role mapping rule
      Values: `username`, `groups`, `dn`
    - `roles` ([] string) — required
      The roles that are applied when the mapping rule is successfully evaluated
    - `value` (string) — required
      The value to match when evaluating this rule
- `enabled` (boolean) — optional
  When true, enables the security realm
- `order` (integer) — optional
  The order that the security realm is evaluated
- `force_authn` (boolean) — optional
  Specifies whether to set the ForceAuthn attribute when requesting that the IdP authenticate the current user. If set to true, the IdP is required to verify the user's identity, irrespective of any existing sessions they might have.
- `signing_certificate_url` (string) — optional
  The SAML signing certificate bundle URL. The bundle should be a zip file containing 'signing.key' and 'signing.pem' files in the directory '/saml/:id', where :id is the value of the [id] field.
- `signing_certificate_url_password` (string) — optional
  The password to the signing certificate bundle
- `signing_saml_messages` ([] string) — optional
  A list of SAML message types that should be signed. Each element in the list should be the local name of a SAML XML Element. Supported element types are AuthnRequest, LogoutRequest and LogoutResponse. Only valid if a signing certificate is also specified.
- `encryption_certificate_url` (string) — optional
  The SAML encryption certificate bundle URL. The bundle should be a zip file containing 'encryption.key' and 'encryption.pem' files in the directory '/saml/:id', where :id is the value of the [id] field.
- `encryption_certificate_url_password` (string) — optional
  The password to the encryption certificate bundle
- `ssl_certificate_url` (string) — optional
  The SSL trusted CA certificate bundle URL. The bundle should be a zip file containing a single keystore file 'keystore.ks' Note that all keys should omit the 'xpack.security.authc.realms.saml.{realm_id}' prefix. For example, when the realm ID is set to 'saml1', the advanced configuration 'xpack.security.authc.realms.saml.saml1.ssl.verification_mode: full' should be added as 'ssl.verification_mode: full'.
- `ssl_certificate_url_truststore_password` (string) — optional
  The password to the SSL certificate bundle URL truststore
- `ssl_certificate_url_truststore_type` (enum) — optional
  The format of the keystore file. Should be jks to use the Java Keystore format or PKCS12 to use PKCS#12 files. The default is jks.
  Values: `jks`, `PKCS12`
- `override_yaml` (string) — optional
  Advanced configuration options in YAML format. Any settings defined here will override any configuration set via the API. Note that all keys should omit 'xpack.security.authc.realms.{realm_type}.{realm_id}'.

## Responses

#### `201`

The SAML configuration was successfully created

`application/json`

Type: `EmptyResponse`

##### Response Headers

- `x-cloud-resource-version` (string)
  The resource version, which is used to avoid update conflicts with concurrent operations
- `x-cloud-resource-created` (string)
  The date-time when the resource was created (ISO format relative to UTC)
- `x-cloud-resource-last-modified` (string)
  The date-time when the resource was last modified (ISO format relative to UTC)

#### `400`

* The realm id is already in use. (code: `security_realm.id_conflict`)
* The selected id is not valid. (code: `security_realm.invalid_id`)
* Order must be greater than zero. (code: `security_realm.invalid_order`)
* Invalid Elasticsearch Security realm type. (code: `security_realm.invalid_type`)
* The realm order is already in use. (code: `security_realm.order_conflict`)
* Advanced YAML format is invalid. (code: `security_realm.invalid_yaml`)
* The SAML IDP metadata endpoint returned an error response code 200 OK. (code: `security_realm.saml.invalid_idp_metadata_url`)
* Invalid certificate bundle URL. (code: `security_realm.invalid_bundle_url`)

`application/json`

- `errors` ([] BasicFailedReplyElement)
  A list of errors that occurred in the failing request
  - `code` (string)
    A structured code representing the error type that occurred
  - `message` (string)
    A human readable message describing the error that occurred
  - `fields` ([] string)
    If the error can be tied to a specific field or fields in the user request, this lists those fields
##### Response Headers

- `x-cloud-error-codes` (enum)
  The error codes associated with the response

## Code Examples

#### Console

```console
POST /platform/configuration/security/realms/saml
```

#### curl

```curl
curl -X POST "/platform/configuration/security/realms/saml"
```