# Single sign-on requests

```json metadata
{
  "title": "Single sign-on requests",
  "description": "Single sign-on (SSO) configuration requests",
  "categories": ["docs","operate","rs"],
  "tableOfContents": {"sections":[{"children":[{"id":"request-get-request","title":"Request {#get-request}"},{"id":"response-get-response","title":"Response {#get-response}"},{"id":"status-codes-get-status-codes","title":"Status codes {#get-status-codes}"}],"id":"get-sso-configuration-get-cluster-sso","title":"Get SSO configuration {#get-cluster-sso}"},{"children":[{"id":"request-put-request","title":"Request {#put-request}"},{"id":"response-put-response","title":"Response {#put-response}"},{"id":"error-codes-put-error-codes","title":"Error codes {#put-error-codes}"},{"id":"status-codes-put-status-codes","title":"Status codes {#put-status-codes}"}],"id":"update-sso-configuration-put-cluster-sso","title":"Update SSO configuration {#put-cluster-sso}"},{"children":[{"id":"request-delete-request","title":"Request {#delete-request}"},{"id":"response-delete-response","title":"Response {#delete-response}"},{"id":"error-codes-delete-error-codes","title":"Error codes {#delete-error-codes}"},{"id":"status-codes-delete-status-codes","title":"Status codes {#delete-status-codes}"}],"id":"delete-sso-configuration-delete-cluster-sso","title":"Delete SSO configuration {#delete-cluster-sso}"},{"children":[{"id":"request-get-metadata-request","title":"Request {#get-metadata-request}"},{"id":"response-get-metadata-response","title":"Response {#get-metadata-response}"},{"id":"error-codes-get-metadata-error-codes","title":"Error codes {#get-metadata-error-codes}"},{"id":"status-codes-get-metadata-status-codes","title":"Status codes {#get-metadata-status-codes}"}],"id":"get-saml-service-provider-metadata-get-cluster-sso-saml-metadata","title":"Get SAML service provider metadata {#get-cluster-sso-saml-metadata}"},{"children":[{"id":"request-post-metadata-request","title":"Request {#post-metadata-request}"},{"id":"response-post-metadata-response","title":"Response {#post-metadata-response}"},{"id":"error-codes-post-metadata-error-codes","title":"Error codes {#post-metadata-error-codes}"},{"id":"status-codes-post-metadata-status-codes","title":"Status codes {#post-metadata-status-codes}"}],"id":"upload-saml-identity-provider-metadata-post-cluster-sso-saml-metadata","title":"Upload SAML identity provider metadata {#post-cluster-sso-saml-metadata}"}]}

,
  "codeExamples": []
}
```
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-cluster-sso) | `/v1/cluster/sso` | Get SSO configuration |
| [PUT](#put-cluster-sso) | `/v1/cluster/sso` | Set or update SSO configuration |
| [DELETE](#delete-cluster-sso) | `/v1/cluster/sso` | Clear SSO configuration |
| [GET](#get-cluster-sso-saml-metadata) | `/v1/cluster/sso/saml/metadata/sp` | Get SAML service provider metadata |
| [POST](#post-cluster-sso-saml-metadata) | `/v1/cluster/sso/saml/metadata/idp` | Upload SAML identity provider metadata |

## Get SSO configuration {#get-cluster-sso}

	GET /v1/cluster/sso

Get the single sign-on configuration as JSON.

#### Required permissions

| Permission name | Roles |
|-----------------|-------|
| [view_sso](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#view_sso) | admin<br />user_manager |

### Request {#get-request}

#### Example HTTP request

	GET /v1/cluster/sso

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

### Response {#get-response}

Returns an [SSO object](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/sso).

#### Example JSON body

```json
{
   "control_plane": true,
   "protocol": "saml2",
   "enforce_control_plane": false,
   "issuer": {
         "id": "urn:sso:example:idp",
         "login_url": "https://idp.example.com/sso/saml",
         "logout_url": "https://idp.example.com/sso/slo",
         "metadata": "<base64 encoded metadata>"
   },
   "service": {
         "address": "https://hostname:port",
         "saml2": {
             "entity_id": "https://cnm.cluster.fqdn/sp",
             "acs_url": "https://cnm.cluster.fqdn/v1/cluster/sso/saml/acs",
             "slo_url": "https://cnm.cluster.fqdn/v1/cluster/sso/saml/slo"
         }
   }
}
```

### Status codes {#get-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success |

## Update SSO configuration {#put-cluster-sso}

	PUT /v1/cluster/sso

Set or update the cluster single sign-on configuration.

#### Required permissions

| Permission name | Roles |
|-----------------|-------|
| [config_sso](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#config_sso) | admin<br />user_manager |

### Request {#put-request}

#### Example HTTP request

	PUT /v1/cluster/sso

#### Example JSON body

```json
{
   "control_plane": false,
   "protocol": "saml2",
   "enforce_control_plane": false,
   "issuer": {
         "id": "urn:sso:example:idp",
         "login_url": "https://idp.example.com/sso/saml",
         "logout_url": "https://idp.example.com/sso/slo"
   },
   "service": {
         "address": "https://hostname:port"
   }
}
```

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Request body

Include an [SSO object](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/sso) with updated fields in the request body.

### Response {#put-response}

Returns a status code. If an error occurs, the response body can include an error code and message with more details.

### Error codes {#put-error-codes}

Possible `error_code` values:

| Code | Description |
|------|-------------|
| missing_param | A required parameter is missing while SSO is being enabled |
| missing_certificate | SSO certificate is not found while SSO is being enabled |

### Status codes {#put-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, SSO config has been set |
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad or missing configuration parameters |
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Missing required certificate |

## Delete SSO configuration {#delete-cluster-sso}

	DELETE /v1/cluster/sso

Clear the single sign-on configuration.

#### Required permissions

| Permission name | Roles |
|-----------------|-------|
| [config_sso](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#config_sso) | admin<br />user_manager |

### Request {#delete-request}

#### Example HTTP request

	DELETE /v1/cluster/sso

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

### Response {#delete-response}

Returns a status code.

### Error codes {#delete-error-codes}

Possible `error_code` values:

| Code | Description |
|------|-------------|
| delete_certificate_error | An error occurred during SSO certificate deletion |

### Status codes {#delete-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success |
| [500 Internal Server Error](https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server-error) | Error during deletion |

## Get SAML service provider metadata {#get-cluster-sso-saml-metadata}

	GET /v1/cluster/sso/saml/metadata/sp

Generates and returns the SAML2 service provider metadata XML.

#### Required permissions

| Permission name | Roles |
|-----------------|-------|
| [view_sso](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#view_sso) | admin<br />user_manager |

### Request {#get-metadata-request}

#### Example HTTP request

	GET /v1/cluster/sso/saml/metadata/sp

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/samlmetadata+xml | Accepted media type |

### Response {#get-metadata-response}

Returns SAML2 service provider metadata as XML.

#### Example response body

```xml
<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor
xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
    ...
</md:EntityDescriptor>
```

### Error codes {#get-metadata-error-codes}

Possible `error_code` values:

| Code | Description |
|------|-------------|
| missing_certificate | Service certificate is missing |
| saml_metadata_generation_error | An error occurred while generating the XML metadata |

### Status codes {#get-metadata-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success |
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Missing required service certificate |
| [500 Internal Server Error](https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server-error) | Unexpected error when generating metadata |

## Upload SAML identity provider metadata {#post-cluster-sso-saml-metadata}

	POST /v1/cluster/sso/saml/metadata/idp

Uploads and validates the SAML2 identity provider metadata XML.

#### Required permissions

| Permission name | Roles |
|-----------------|-------|
| [config_sso](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#config_sso) | admin<br />user_manager |

### Request {#post-metadata-request}

#### Example HTTP request

	POST /v1/cluster/sso/saml/metadata/idp

#### Example JSON body

```json
{
   "idp_metadata": "YWp3cjkwcHR1eWF3MHJ0eTkwYXc0eXQwOW4..."
}
```

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Request body

| Name | Type/Value | Description |
|------|------------|-------------|
| idp_metadata | string | Base64-encoded SAML2 identity provider metadata XML |

### Response {#post-metadata-response}

Returns an [SSO object](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/sso) with the updated configuration.

#### Example JSON body

```json
{
   "control_plane": true,
   "protocol": "saml2",
   "enforce_control_plane": false,
   "issuer": {
         "id": "urn:sso:example:idp",
         "login_url": "https://idp.example.com/sso/saml",
         "logout_url": "https://idp.example.com/sso/slo"
   },
   "service": {
         "saml2": {
             "entity_id": "https://cnm.cluster.fqdn/sp",
             "acs_url": "https://cnm.cluster.fqdn/v1/cluster/sso/saml/acs",
             "slo_url": "https://cnm.cluster.fqdn/v1/cluster/sso/saml/slo"
         }
   }
}
```

### Error codes {#post-metadata-error-codes}

Possible `error_code` values:

| Code | Description |
|------|-------------|
| saml_metadata_validation_error | IdP metadata failed configuration validation checks |
| saml_metadata_parsing_error | IdP metadata is not a valid base64-encoded XML |
| missing_certificate | SSO certificate is not found while SSO is being enabled |

### Status codes {#post-metadata-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success |
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad or missing parameters |
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Missing required service certificate |