Sso - Redis — ContextQMD

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-cluster-sso}

GET /v1/cluster/sso

Get the single sign-on configuration as JSON.

Required permissions

Permission name	Roles
[view_sso]({{< relref "/operate/rs/references/rest-api/permissions#view_sso" >}})	admin
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]({{< relref "/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	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]({{< relref "/operate/rs/references/rest-api/permissions#config_sso" >}})	admin
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]({{< relref "/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	Success, SSO config has been set
400 Bad Request	Bad or missing configuration parameters
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]({{< relref "/operate/rs/references/rest-api/permissions#config_sso" >}})	admin
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	Success
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]({{< relref "/operate/rs/references/rest-api/permissions#view_sso" >}})	admin
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	Success
406 Not Acceptable	Missing required service certificate
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]({{< relref "/operate/rs/references/rest-api/permissions#config_sso" >}})	admin
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]({{< relref "/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	Success
400 Bad Request	Bad or missing parameters
406 Not Acceptable	Missing required service certificate