Update SAML configuration

PUT /platform/configuration/security/realms/saml/{realm_id}

Updates an existing SAML configuration.

Path parameters

realm_id string Required

The Elasticsearch Security realm identifier.

Query parameters

version string

When specified, checks for conflicts against the version stored in the persistent store (returned in 'x-cloud-resource-version' of the GET request)

Body Required

The SAML configuration

id string Required

The identifier for the security realm
name string Required

The friendly name of the security realm
idp object Required

The SAML Identity Provider configuration

Additional properties are allowed.
Hide idp attributes Show idp attributes object
- 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
  
  Indicates whether to utilise the Identity Provider's Single Logout service
sp object Required

The SAML Service Provider configuration

Additional properties are allowed.
Hide sp attributes Show sp attributes object
- 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 object Required

The SAML attribute mapping configuration

Additional properties are allowed.
Hide attributes attributes Show attributes attributes object
- 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
  
  The name of the SAML attribute that contains the user's full name
- mail string
  
  The name of the SAML attribute that contains the user's email address
- dn string
  
  The name of the SAML attribute that contains the user's X.50 Distinguished Name
nameid_format string

The NameID format. If not specified the IdP default is used. Example: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
role_mappings object

The role mapping rules associated with the security realm

Additional properties are allowed.
Hide role_mappings attributes Show role_mappings attributes object
- default_roles array[string] Required
  
  The default roles applied to all users
- rules array[object] Required
  
  The role mapping rules to evaluate
  Hide rules attributes Show rules attributes object
  
  type string Required
  
  The type of role mapping rule
  
  Values are username, groups, or dn.
  
  roles array[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

When true, enables the security realm
order integer(int32)

The order that the security realm is evaluated
force_authn boolean

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

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

The password to the signing certificate bundle
signing_saml_messages array[string]

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

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

The password to the encryption certificate bundle
ssl_certificate_url string

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

The password to the SSL certificate bundle URL truststore
ssl_certificate_url_truststore_type string

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 are jks or PKCS12.
override_yaml string

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

200

The SAML configuration was successfully updated
Hide headers attributes Show headers attributes
- 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)
Additional properties are allowed.
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)
Hide headers attribute Show headers attribute
- x-cloud-error-codes string
  
  The error codes associated with the response
  
  Values are security_realm.id_conflict, security_realm.invalid_id, security_realm.invalid_order, security_realm.invalid_type, security_realm.order_conflict, security_realm.invalid_yaml, security_realm.saml.invalid_idp_metadata_url, or security_realm.invalid_bundle_url.
Hide response attribute Show response attribute object
- errors array[object] Required
  
  A list of errors that occurred in the failing request
  
  Hide errors attributes Show errors attributes object
  
  code string Required
  
  A structured code representing the error type that occurred
  
  message string Required
  
  A human readable message describing the error that occurred
  
  fields array[string]
  
  If the error can be tied to a specific field or fields in the user request, this lists those fields
404

The realm specified by {realm_id} cannot be found. (code: security_realm.not_found)
Hide headers attribute Show headers attribute
- x-cloud-error-codes string
  
  The error codes associated with the response
  
  Value is security_realm.not_found.
Hide response attribute Show response attribute object
- errors array[object] Required
  
  A list of errors that occurred in the failing request
  
  Hide errors attributes Show errors attributes object
  
  code string Required
  
  A structured code representing the error type that occurred
  
  message string Required
  
  A human readable message describing the error that occurred
  
  fields array[string]
  
  If the error can be tied to a specific field or fields in the user request, this lists those fields
409

There is a version conflict. (code: security_realm.version_conflict)
Hide headers attribute Show headers attribute
- x-cloud-error-codes string
  
  The error codes associated with the response
  
  Value is security_realm.version_conflict.
Hide response attribute Show response attribute object
- errors array[object] Required
  
  A list of errors that occurred in the failing request
  
  Hide errors attributes Show errors attributes object
  
  code string Required
  
  A structured code representing the error type that occurred
  
  message string Required
  
  A human readable message describing the error that occurred
  
  fields array[string]
  
  If the error can be tied to a specific field or fields in the user request, this lists those fields

PUT /platform/configuration/security/realms/saml/{realm_id}

curl \
 -X PUT https://{{hostname}}/api/v1/platform/configuration/security/realms/saml/{realm_id} \
 -d '{"id":"string","name":"string","idp":{"entity_id":"string","metadata_path":"string","use_single_logout":true},"sp":{"entity_id":"string","acs":"string","logout":"string"},"attributes":{"principal":"string","groups":"string","name":"string","mail":"string","dn":"string"},"nameid_format":"string","role_mappings":{"default_roles":["string"],"rules":[{"type":"username","roles":["string"],"value":"string"}]},"enabled":true,"order":42,"force_authn":true,"signing_certificate_url":"string","signing_certificate_url_password":"string","signing_saml_messages":["string"],"encryption_certificate_url":"string","encryption_certificate_url_password":"string","ssl_certificate_url":"string","ssl_certificate_url_truststore_password":"string","ssl_certificate_url_truststore_type":"jks","override_yaml":"string"}'

Request examples

{
  "id": "string",
  "name": "string",
  "idp": {
    "entity_id": "string",
    "metadata_path": "string",
    "use_single_logout": true
  },
  "sp": {
    "entity_id": "string",
    "acs": "string",
    "logout": "string"
  },
  "attributes": {
    "principal": "string",
    "groups": "string",
    "name": "string",
    "mail": "string",
    "dn": "string"
  },
  "nameid_format": "string",
  "role_mappings": {
    "default_roles": [
      "string"
    ],
    "rules": [
      {
        "type": "username",
        "roles": [
          "string"
        ],
        "value": "string"
      }
    ]
  },
  "enabled": true,
  "order": 42,
  "force_authn": true,
  "signing_certificate_url": "string",
  "signing_certificate_url_password": "string",
  "signing_saml_messages": [
    "string"
  ],
  "encryption_certificate_url": "string",
  "encryption_certificate_url_password": "string",
  "ssl_certificate_url": "string",
  "ssl_certificate_url_truststore_password": "string",
  "ssl_certificate_url_truststore_type": "jks",
  "override_yaml": "string"
}

Response examples (200)

# Headers
x-cloud-resource-version: string
x-cloud-resource-created: string
x-cloud-resource-last-modified: string

# Payload
{}

Response examples (400)

# Headers
x-cloud-error-codes: security_realm.id_conflict

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Response examples (404)

# Headers
x-cloud-error-codes: security_realm.not_found

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Response examples (409)

# Headers
x-cloud-error-codes: security_realm.version_conflict

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}