{
  "id": "sso",
  "title": "Single sign-on requests",
  "url": "https://redis.io/docs/latest/operate/rs/8.0/references/rest-api/requests/cluster/sso/",
  "summary": "Single sign-on (SSO) configuration requests",
  "content": "\n| Method | Path | Description |\n|--------|------|-------------|\n| [GET](#get-cluster-sso) | `/v1/cluster/sso` | Get SSO configuration |\n| [PUT](#put-cluster-sso) | `/v1/cluster/sso` | Set or update SSO configuration |\n| [DELETE](#delete-cluster-sso) | `/v1/cluster/sso` | Clear SSO configuration |\n| [GET](#get-cluster-sso-saml-metadata) | `/v1/cluster/sso/saml/metadata/sp` | Get SAML service provider metadata |\n| [POST](#post-cluster-sso-saml-metadata) | `/v1/cluster/sso/saml/metadata/idp` | Upload SAML identity provider metadata |\n\n## Get SSO configuration {#get-cluster-sso}\n\n\tGET /v1/cluster/sso\n\nGet the single sign-on configuration as JSON.\n\n#### Required permissions\n\n| Permission name | Roles |\n|-----------------|-------|\n| [view_sso](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#view_sso) | admin\u003cbr /\u003euser_manager |\n\n### Request {#get-request}\n\n#### Example HTTP request\n\n\tGET /v1/cluster/sso\n\n#### Request headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n\n### Response {#get-response}\n\nReturns an [SSO object](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/sso).\n\n#### Example JSON body\n\n```json\n{\n   \"control_plane\": true,\n   \"protocol\": \"saml2\",\n   \"enforce_control_plane\": false,\n   \"issuer\": {\n         \"id\": \"urn:sso:example:idp\",\n         \"login_url\": \"https://idp.example.com/sso/saml\",\n         \"logout_url\": \"https://idp.example.com/sso/slo\",\n         \"metadata\": \"\u003cbase64 encoded metadata\u003e\"\n   },\n   \"service\": {\n         \"address\": \"https://hostname:port\",\n         \"saml2\": {\n             \"entity_id\": \"https://cnm.cluster.fqdn/sp\",\n             \"acs_url\": \"https://cnm.cluster.fqdn/v1/cluster/sso/saml/acs\",\n             \"slo_url\": \"https://cnm.cluster.fqdn/v1/cluster/sso/saml/slo\"\n         }\n   }\n}\n```\n\n### Status codes {#get-status-codes}\n\n| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success |\n\n## Update SSO configuration {#put-cluster-sso}\n\n\tPUT /v1/cluster/sso\n\nSet or update the cluster single sign-on configuration.\n\n#### Required permissions\n\n| Permission name | Roles |\n|-----------------|-------|\n| [config_sso](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#config_sso) | admin\u003cbr /\u003euser_manager |\n\n### Request {#put-request}\n\n#### Example HTTP request\n\n\tPUT /v1/cluster/sso\n\n#### Example JSON body\n\n```json\n{\n   \"control_plane\": false,\n   \"protocol\": \"saml2\",\n   \"enforce_control_plane\": false,\n   \"issuer\": {\n         \"id\": \"urn:sso:example:idp\",\n         \"login_url\": \"https://idp.example.com/sso/saml\",\n         \"logout_url\": \"https://idp.example.com/sso/slo\"\n   },\n   \"service\": {\n         \"address\": \"https://hostname:port\"\n   }\n}\n```\n\n#### Request headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n\n#### Request body\n\nInclude an [SSO object](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/sso) with updated fields in the request body.\n\n### Response {#put-response}\n\nReturns a status code. If an error occurs, the response body can include an error code and message with more details.\n\n### Error codes {#put-error-codes}\n\nPossible `error_code` values:\n\n| Code | Description |\n|------|-------------|\n| missing_param | A required parameter is missing while SSO is being enabled |\n| missing_certificate | SSO certificate is not found while SSO is being enabled |\n\n### Status codes {#put-status-codes}\n\n| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, SSO config has been set |\n| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad or missing configuration parameters |\n| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Missing required certificate |\n\n## Delete SSO configuration {#delete-cluster-sso}\n\n\tDELETE /v1/cluster/sso\n\nClear the single sign-on configuration.\n\n#### Required permissions\n\n| Permission name | Roles |\n|-----------------|-------|\n| [config_sso](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#config_sso) | admin\u003cbr /\u003euser_manager |\n\n### Request {#delete-request}\n\n#### Example HTTP request\n\n\tDELETE /v1/cluster/sso\n\n#### Request headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n\n### Response {#delete-response}\n\nReturns a status code.\n\n### Error codes {#delete-error-codes}\n\nPossible `error_code` values:\n\n| Code | Description |\n|------|-------------|\n| delete_certificate_error | An error occurred during SSO certificate deletion |\n\n### Status codes {#delete-status-codes}\n\n| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success |\n| [500 Internal Server Error](https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server-error) | Error during deletion |\n\n## Get SAML service provider metadata {#get-cluster-sso-saml-metadata}\n\n\tGET /v1/cluster/sso/saml/metadata/sp\n\nGenerates and returns the SAML2 service provider metadata XML.\n\n#### Required permissions\n\n| Permission name | Roles |\n|-----------------|-------|\n| [view_sso](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#view_sso) | admin\u003cbr /\u003euser_manager |\n\n### Request {#get-metadata-request}\n\n#### Example HTTP request\n\n\tGET /v1/cluster/sso/saml/metadata/sp\n\n#### Request headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/samlmetadata+xml | Accepted media type |\n\n### Response {#get-metadata-response}\n\nReturns SAML2 service provider metadata as XML.\n\n#### Example response body\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cmd:EntityDescriptor\nxmlns:md=\"urn:oasis:names:tc:SAML:2.0:metadata\"\u003e\n    ...\n\u003c/md:EntityDescriptor\u003e\n```\n\n### Error codes {#get-metadata-error-codes}\n\nPossible `error_code` values:\n\n| Code | Description |\n|------|-------------|\n| missing_certificate | Service certificate is missing |\n| saml_metadata_generation_error | An error occurred while generating the XML metadata |\n\n### Status codes {#get-metadata-status-codes}\n\n| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success |\n| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Missing required service certificate |\n| [500 Internal Server Error](https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server-error) | Unexpected error when generating metadata |\n\n## Upload SAML identity provider metadata {#post-cluster-sso-saml-metadata}\n\n\tPOST /v1/cluster/sso/saml/metadata/idp\n\nUploads and validates the SAML2 identity provider metadata XML.\n\n#### Required permissions\n\n| Permission name | Roles |\n|-----------------|-------|\n| [config_sso](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#config_sso) | admin\u003cbr /\u003euser_manager |\n\n### Request {#post-metadata-request}\n\n#### Example HTTP request\n\n\tPOST /v1/cluster/sso/saml/metadata/idp\n\n#### Example JSON body\n\n```json\n{\n   \"idp_metadata\": \"YWp3cjkwcHR1eWF3MHJ0eTkwYXc0eXQwOW4...\"\n}\n```\n\n#### Request headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n\n#### Request body\n\n| Name | Type/Value | Description |\n|------|------------|-------------|\n| idp_metadata | string | Base64-encoded SAML2 identity provider metadata XML |\n\n### Response {#post-metadata-response}\n\nReturns an [SSO object](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/sso) with the updated configuration.\n\n#### Example JSON body\n\n```json\n{\n   \"control_plane\": true,\n   \"protocol\": \"saml2\",\n   \"enforce_control_plane\": false,\n   \"issuer\": {\n         \"id\": \"urn:sso:example:idp\",\n         \"login_url\": \"https://idp.example.com/sso/saml\",\n         \"logout_url\": \"https://idp.example.com/sso/slo\"\n   },\n   \"service\": {\n         \"saml2\": {\n             \"entity_id\": \"https://cnm.cluster.fqdn/sp\",\n             \"acs_url\": \"https://cnm.cluster.fqdn/v1/cluster/sso/saml/acs\",\n             \"slo_url\": \"https://cnm.cluster.fqdn/v1/cluster/sso/saml/slo\"\n         }\n   }\n}\n```\n\n### Error codes {#post-metadata-error-codes}\n\nPossible `error_code` values:\n\n| Code | Description |\n|------|-------------|\n| saml_metadata_validation_error | IdP metadata failed configuration validation checks |\n| saml_metadata_parsing_error | IdP metadata is not a valid base64-encoded XML |\n| missing_certificate | SSO certificate is not found while SSO is being enabled |\n\n### Status codes {#post-metadata-status-codes}\n\n| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success |\n| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad or missing parameters |\n| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Missing required service certificate |\n",
  "tags": ["docs","operate","rs"],
  "last_updated": "2026-07-23T12:05:56-05:00"
}