---
type: api
title: Authenticate SAML
description: Submit a SAML response message to Elasticsearch for consumption.
url: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/v8/operation/operation-security-saml-authenticate
resource: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/v8/operation/operation-security-saml-authenticate
products:
  - Elasticsearch
---

# Authenticate SAML

Availability: Generally available since 7.5

## Paths

- `POST` `/_security/saml/authenticate`

## Description

Submit a SAML response message to Elasticsearch for consumption.

NOTE: This API is intended for use by custom web applications other than Kibana.
If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.

The SAML message that is submitted can be:

* A response to a SAML authentication request that was previously created using the SAML prepare authentication API.
* An unsolicited SAML message in the case of an IdP-initiated single sign-on (SSO) flow.

In either case, the SAML message needs to be a base64 encoded XML document with a root element of `<Response>`.

After successful validation, Elasticsearch responds with an Elasticsearch internal access token and refresh token that can be subsequently used for authentication.
This API endpoint essentially exchanges SAML responses that indicate successful authentication in the IdP for Elasticsearch access and refresh tokens, which can be used for authentication against Elasticsearch.

[Read the reference documentation](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/saml-guide-stack.html)

## Authentication

- Api key: `Authorization: <value>`
  Elasticsearch APIs support key-based authentication.
  You must create an API key and use the encoded value in the request header.
  For example:
  
  
  ```
  curl -X GET "${ES_URL}/_cat/indices?v=true" \
    -H "Authorization: ApiKey ${API_KEY}"
  ```
  
  To get API keys, use the `/_security/api_key` APIs.
- Basic: `Authorization: Basic <credentials>`
- Bearer: `Authorization: Bearer <token>`
  Elasticsearch APIs support the use of bearer tokens in the `Authorization` HTTP header to authenticate with the API.
  For examples, refer to [Token-based authentication services](https://www.elastic.co/guide/en/elasticsearch/reference/current/token-authentication-services.html)

## Request body

`application/json`

- `content` (string) — required
  The SAML response as it was sent by the user's browser, usually a Base64 encoded XML document.
- `ids` (string) — required
  A JSON array with all the valid SAML Request Ids that the caller of the API has for the current user.
- `realm` (string) — optional
  The name of the realm that should authenticate the SAML response. Useful in cases where many SAML realms are defined.

## Response

`application/json`

- `access_token` (string)
  The access token that was generated by Elasticsearch.
- `username` (string)
  The authenticated user's name.
- `expires_in` (number)
  The amount of time (in seconds) left until the token expires.
- `refresh_token` (string)
  The refresh token that was generated by Elasticsearch.
- `realm` (string)
  The name of the realm where the user was authenticated.
## Code examples

#### Console

```console
POST /_security/saml/authenticate
{
  "content" : "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....",
  "ids" : ["4fee3b046395c4e751011e97f8900b5273d56685"]
}
```

#### JavaScript

```javascript
const response = await client.security.samlAuthenticate({
  content:
    "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....",
  ids: ["4fee3b046395c4e751011e97f8900b5273d56685"],
});
```

#### Python

```python
resp = client.security.saml_authenticate(
    content="PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....",
    ids=[
        "4fee3b046395c4e751011e97f8900b5273d56685"
    ],
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/_security/saml/authenticate" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....",
    "ids": [
      "4fee3b046395c4e751011e97f8900b5273d56685"
    ]
  }'
```

#### Java

```java
client.security().samlAuthenticate(s -> s
    .content("PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....")
    .ids("4fee3b046395c4e751011e97f8900b5273d56685")
);
```

#### C#

```c#
var response = await client.Security
    .SamlAuthenticateAsync(d1 => d1
        .Content("PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....")
        .Ids(new[] { "4fee3b046395c4e751011e97f8900b5273d56685" })
    );
```

#### PHP

```php
$resp = $client->security()->samlAuthenticate([
    "body" => [
        "content" => "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....",
        "ids" => array(
            "4fee3b046395c4e751011e97f8900b5273d56685",
        ),
    ],
]);
```

#### Ruby

```ruby
response = client.security.saml_authenticate(
  body: {
    "content": "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....",
    "ids": [
      "4fee3b046395c4e751011e97f8900b5273d56685"
    ]
  }
)
```

## Response examples

#### Saml authenticate response example1

A successful response from `POST /_security/saml/authenticate`.

```json
{
  "access_token" : "46ToAxZVaXVVZTVKOVF5YU04ZFJVUDVSZlV3",
  "username" : "Bearer",
  "expires_in" : 1200,
  "refresh_token": "mJdXLtmvTUSpoLwMvdBt_w",
  "realm": "saml1"
}
```