Single sign-on requests

Single sign-on (SSO) configuration requests

Redis Enterprise Software
Method Path Description
GET /v1/cluster/sso Get SSO configuration
PUT /v1/cluster/sso Set or update SSO configuration
DELETE /v1/cluster/sso Clear SSO configuration
GET /v1/cluster/sso/saml/metadata/sp Get SAML service provider metadata
POST /v1/cluster/sso/saml/metadata/idp Upload SAML identity provider metadata

Get SSO configuration 

GET /v1/cluster/sso

Get the single sign-on configuration as JSON.

Required permissions

Permission name Roles
view_sso admin
user_manager

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

Returns an SSO object.

Example JSON body 

{
   "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

Code Description
200 OK Success

Update SSO configuration 

PUT /v1/cluster/sso

Set or update the cluster single sign-on configuration.

Required permissions

Permission name Roles
config_sso admin
user_manager

Request

Example HTTP request 

PUT /v1/cluster/sso

Example JSON body 

{
   "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 with updated fields in the request body.

Response

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

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

Code Description
200 OK Success, SSO config has been set
400 Bad Request Bad or missing configuration parameters
406 Not Acceptable Missing required certificate

Delete SSO configuration 

DELETE /v1/cluster/sso

Clear the single sign-on configuration.

Required permissions

Permission name Roles
config_sso admin
user_manager

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

Returns a status code.

Error codes

Possible error_code values:

Code Description
delete_certificate_error An error occurred during SSO certificate deletion

Status codes

Code Description
200 OK Success
500 Internal Server Error Error during deletion

Get SAML service provider metadata 

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

Generates and returns the SAML2 service provider metadata XML.

Required permissions

Permission name Roles
view_sso admin
user_manager

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

Returns SAML2 service provider metadata as XML.

Example response body 

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

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

Code Description
200 OK Success
406 Not Acceptable Missing required service certificate
500 Internal Server Error Unexpected error when generating metadata

Upload SAML identity provider metadata 

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

Uploads and validates the SAML2 identity provider metadata XML.

Required permissions

Permission name Roles
config_sso admin
user_manager

Request

Example HTTP request 

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

Example JSON body 

{
   "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

Returns an SSO object with the updated configuration.

Example JSON body 

{
   "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

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

Code Description
200 OK Success
400 Bad Request Bad or missing parameters
406 Not Acceptable Missing required service certificate
RATE THIS PAGE
Back to top ↑