vault/website/content/api-docs/auth/saml.mdx

---
layout: api
page_title: SAML - Auth Methods - HTTP API
description: |-
  This is the API documentation for the Vault SAML auth method.
---

# SAML auth method (API)

<EnterpriseAlert />

This is the API documentation for the Vault SAML auth method. To learn more about the
usage and operation, see the [Vault SAML auth method documentation](/vault/docs/auth/saml).

This documentation assumes the SAML auth method is mounted at the `/auth/saml` path in
Vault. Since it is possible to enable auth methods at any location, please update your
API calls accordingly.

## Create or update configuration

Configures the auth method with a SAML identity provider.

| Method     | Path                |
|:-----------| :------------------ |
| `POST/PUT` | `/auth/saml/config` |

### Parameters

- `idp_metadata_url` `(string, <required>)` - The metadata URL of the identity provider.
  Mutually exclusive with `idp_sso_url`, `idp_issuer` and `idp_cert`. Must be a
  well-formatted URL.
- `idp_sso_url` `(string, <required if idp_metadata_url is not set>)` - The SSO URL of the
  identity provider. Mutually exclusive with `idp_metadata_url`. Must be a
  well-formatted URL.
- `idp_entity_id` `(string, <required if idp_metadata_url is not set>)` - The entity ID of
  the identity provider. Mutually exclusive with `idp_metadata_url`.
- `idp_cert` `(string, <required if idp_metadata_url is not set>)` - The PEM-encoded
  certificate of the identity provider used to verify response and assertion signatures.
  Mutually exclusive with `idp_metadata_url`.
- `entity_id` `(string, <required>)` - The entity ID of the SAML authentication
  service provider. Must match entity ID configured for the application in the
  SAML identity provider.
- `acs_urls` `(list, <required>)` - The well-formated URLs of your Assertion
  Consumer Service (ACS) that should receive a response from the identity
  provider. Vault returns a security warning if any of the given URLs lack TLS
  protection.
- `default_role` `(string, <optional>)` - The role to use if no role is provided during login.
  If not set, a role is required during login.
- `verbose_logging` `(bool, false)` - **Not recommended for production**. Log
  additional, **potentially sensitive** information during the SAML exchange
  according to the current logging level. When `verbose_logging` is `true`,
  debug-level logs provide user attributes and trace-level logs provide the full
  SAML response.

### Sample payload

```json
{
  "acs_urls": "https://my.vault/v1/auth/saml/callback",
  "default_role": "admin",
  "entity_id": "https://my.vault/v1/auth/saml",
  "idp_metadata_url": "https://company.okta.com/app/abc123eb9xnIfzlaf697/sso/saml/metadata"
}
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/saml/config
```

## Read configuration

Reads the auth method configuration.

| Method  | Path                |
| :------ | :------------------ |
| `GET`   | `/auth/saml/config` |

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/saml/config
```

### Sample response

```json
{
  "request_id": "09c907d2-2dbe-8a5c-ca97-fad83195738b",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "acs_urls": [
      "https://my.vault/v1/auth/saml/callback"
    ],
    "default_role": "admin",
    "entity_id": "https://my.vault/v1/auth/saml",
    "idp_metadata_url": "https://company.okta.com/app/abc123eb9xnIfzlaf697/sso/saml/metadata"
  },
  "warnings": null
}
```

## Create or update role

Configures a role in the auth method. Roles define specific constraints required for
authentication and properties of resulting Vault tokens.

| Method     | Path                     |
|:-----------|:-------------------------|
| `POST/PUT` | `/auth/saml/role/:name`  |

### Parameters

- `name` `(string: <required>)` - URL parameter that provides the name of the role to create.
- `bound_subjects` `(string: <optional>)` - The subject being asserted for SAML
  authentication. One of the provided values must match the subject returned in
  the SAML assertion from the identity provider.
- `bound_subjects_type` `(string: <optional>)` - The type of matching assertion to perform
  on `bound_subjects`. If `string`, requires a direct string match. If `glob`, allows for
  wildcard matching using the `*` character.
- `bound_attributes` `(map: <optional>)` - Mapping of attribute names to values that are
  expected to exist in the SAML assertion. The expected value may be a single string or a
  comma-separated list of strings. The user will be authenticated if the SAML attributes
  match at least one of the expected values.
- `bound_attributes_type` `(string: "string")` - The type of matching assertion to perform
  on the key-value pairs provided by `bound_attributes`. If set to `string`, a direct string
  match is required. If set to `glob`, allows for wildcard matching using the `*` character.
- `groups_attribute` `(string: <optional>)` - The attribute to use to identify the set of
  groups to which the user belongs. This will be used as the names for the Identity group
  aliases created due to a successful login.

@include 'tokenfields.mdx'

### Sample payload

```json
{
  "bound_attributes": "group=admin",
  "bound_subjects": "*@hashicorp.com",
  "bound_subjects_type": "glob",
  "token_policies": "writer",
  "ttl": "1h"
}
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/saml/role/admin
```

## Read role

Reads a configured role.

| Method | Path                    |
| :----- |:------------------------|
| `GET`  | `/auth/saml/role/:name` |

### Parameters

- `name` `(string: <required>)` - URL parameter that provides the name of the
  role to read.

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/auth/saml/role/admin
```

### Sample response

```json
{
  "request_id": "3148ca9a-286e-a0a4-5a4b-31b6abb63d37",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "bound_attributes": {
      "group": [
        "admin"
      ]
    },
    "bound_attributes_type": "string",
    "bound_subjects": [
      "*@hashicorp.com"
    ],
    "bound_subjects_type": "glob",
    "groups_attribute": "",
    "token_bound_cidrs": [],
    "token_explicit_max_ttl": 0,
    "token_max_ttl": 0,
    "token_no_default_policy": false,
    "token_num_uses": 0,
    "token_period": 0,
    "token_policies": [
      "writer"
    ],
    "token_ttl": 0,
    "token_type": "default"
  },
  "warnings": null
}
```

## List roles

Lists all the configured roles.

| Method | Path              |
| :----- | :---------------- |
| `LIST` | `/auth/saml/role` |

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/auth/saml/role?list=true
```

### Sample response

```json
[
  "admin",
  "operations"
]
```

## Delete Role

Deletes a configured role.

| Method   | Path                    |
| :------- | :---------------------- |
| `DELETE` | `/auth/saml/role/:name` |

### Parameters

- `name` `(string: <required>)` - URL parameter that provides the name of the
  role to delete.

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/auth/saml/role/admin
```

## Obtain SSO service URL

Starts a login flow by providing a SAML Single Sign-On (SSO) Service URL for the
configured identity provider. The returned `token_poll_id` can be used to obtain
the Vault token after the user is authenticated with the identity provider and the
SAML response has passed validation.

<Note title="Unauthenticated">
A Vault token is not required to interact with this API.
</Note>

| Method  | Path                         |
|:--------|:-----------------------------|
| `POST`  | `/auth/saml/sso_service_url` |

### Parameters

- `role` `(string, <optional>)` - The role name to use for the login flow.
  Defaults to the role configured with `default_role`.
- `client_challenge` `(string, <required>)` - The client challenge value. Must be the
  output of a base64-encoded, sha256 digest of the `client_verifier` eventually provided
  to the [Token API](/vault/api-docs/auth/saml#obtain-vault-token). Must be at least 44
  bytes in length.
- `client_type` `(string, <required>)` - The type of the requesting client. The response
  from the Assertion Consumer Service [Callback API](/vault/api-docs/auth/saml#assertion-consumer-service-callback)
  will differ based on the provided type. If `cli`, an HTML success page will be returned
  in the response. If `browser`, a blank HTML page will be returned in the response.
- `acs_url` `(string, <required>)` - The URL where the identity provider will send its
  SAML response. Must be in the set of configured [`acs_urls`](/vault/api-docs/auth/saml#acs_urls).

### Sample payload

```json
{
  "acs_url": "https://my.vault/v1/auth/saml/callback",
  "client_challenge": "Z6+7owP80d1aHTha1kdixtT99JkvmG4TPSgbvDwZ70A=",
  "client_type": "cli",
  "role": "admin"
}
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/saml/sso_service_url
```

### Sample response

```json
{
  "sso_service_url": "https://example.okta.com/app/abc123eb9xnIfzlaf697/id/sso/saml?RelayState=...&SAMLRequest=...",
  "token_poll_id": "ee442348-159b-df10-4c59-63050069df4d"
}
```

## Assertion consumer service callback

The assertion consumer service URL of the auth method. Completes the round trip from
the identity provider and performs validations on the SAML response.

<Note title="Unauthenticated">
A Vault token is not required to interact with this API.
</Note>

| Method  | Path                  |
|:--------|:----------------------|
| `POST`  | `/auth/saml/callback` |

### Parameters

- `RelayState` `(string, <required>)` - The relay state from the original SAML
  authentication request that was returned by the identity provider.
- `SAMLResponse` `(string, <required>)` - The signed SAML response from the identity
  provider.

### Sample payload

```json
{
  "RelayState": "0afe62a9-7b83-a182-0650-c749badfb900",
  "SAMLResponse": "..."
}
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/saml/callback
```

## Obtain vault token

The token endpoint completes the login flow by returning a Vault token.

<Note title="Unauthenticated">
A Vault token is not required to interact with this API.
</Note>

| Method  | Path               |
|:--------|:-------------------|
| `POST`  | `/auth/saml/token` |

### Parameters

- `client_verifier` `(string, <required>)` - The value which produced the `client_challenge`
  provided to the [SSO Service URL API](/vault/api-docs/auth/saml#obtain-sso-service-url)
  at the start of the authentication flow. Its base64-encoded, sha256 digest must match the
  `client_challenge` value.
- `token_poll_id` `(string, <required>)` - The `token_poll_id` value returned from the
  [SSO Service URL API](/vault/api-docs/auth/saml#obtain-sso-service-url) at the start of
  the authentication flow.

### Sample payload

```json
{
  "client_verifier": "59634224-5869-6002-e0b1-35370b8f6b82",
  "token_poll_id": "ee442348-159b-df10-4c59-63050069df4d"
}
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/saml/token
```

### Sample response

```json
{
  "request_id": "b16f7cf9-0970-2e64-69d6-f00d055e93c4",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": null,
  "warnings": null,
  "auth": {
    "client_token": "hvs.CAES...",
    "accessor": "Rl4gU4amxzBFpFBJixv8xJBK",
    "policies": [
      "default",
      "writer"
    ],
    "token_policies": [
      "default",
      "writer"
    ],
    "identity_policies": null,
    "metadata": {
      "role": "admin"
    },
    "orphan": true,
    "entity_id": "afd74442-6c48-3d2f-9449-689ce050ba88",
    "lease_duration": 3600,
    "renewable": true,
    "mfa_requirement": null
  }
}
```