Skip to content

Commit b60236a

Browse files
rrelledgerrelledge
committed
DOC-5858 RS: Added SSO requests and objects to RS REST API reference
1 parent 4ce39e1 commit b60236a

File tree

2 files changed

+360
-0
lines changed
  • content/operate/rs/references/rest-api

2 files changed

+360
-0
lines changed

‎content/operate/rs/references/rest-api/objects/sso.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
Title: SSO object
3+
alwaysopen: false
4+
categories:
5+
- docs
6+
- operate
7+
- rs
8+
description: An object for single sign-on (SSO) configuration
9+
linkTitle: sso
10+
weight: $weight
11+
---
12+
13+
An API object that represents single sign-on (SSO) configuration in the cluster.
14+
15+
| Name | Type/Value | Description |
16+
|------|------------|-------------|
17+
| control_plane | boolean (default: false) | If `true`, enables single sign-on (SSO) for the control plane. |
18+
| enforce_control_plane | boolean (default: false) | Enforce SSO login for the control plane for non-admin users. |
19+
| protocol | "saml2" | SSO protocol to use. |
20+
| issuer | complex object | Issuer related configuration.<br>Contains the following fields:<br>**id**: Unique ID of the issuer side (example: "urn:sso:example:idp")<br>**login_url**: SSO login URL (example: "https://idp.example.com/sso/saml")<br>**logout_url**: SSO logout URL (example: "https://idp.example.com/sso/slo") |
21+
| service | complex object | Service related configuration.<br />For SAML2 service configuration:<br />{{<code>}}{
22+
"saml2": {
23+
"entity_id": "string",
24+
"acs_url": "string",
25+
"slo_url": "string"
26+
}
27+
}{{</code>}}<br>**acs_url**: Assertion Consumer Service URL (read-only)<br>**slo_url**: Single Logout URL (read-only)<br>**entity_id**: Service entity ID (read-only) |

‎content/operate/rs/references/rest-api/requests/cluster/sso.md‎

Lines changed: 333 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,333 @@
1+
---
2+
Title: Single sign-on requests
3+
alwaysopen: false
4+
categories:
5+
- docs
6+
- operate
7+
- rs
8+
description: Single sign-on (SSO) configuration requests
9+
headerRange: '[1-2]'
10+
linkTitle: sso
11+
toc: 'true'
12+
weight: $weight
13+
---
14+
15+
| Method | Path | Description |
16+
|--------|------|-------------|
17+
| [GET](#get-cluster-sso) | `/v1/cluster/sso` | Get SSO configuration |
18+
| [PUT](#put-cluster-sso) | `/v1/cluster/sso` | Set or update SSO configuration |
19+
| [DELETE](#delete-cluster-sso) | `/v1/cluster/sso` | Clear SSO configuration |
20+
| [GET](#get-cluster-sso-saml-metadata) | `/v1/cluster/sso/saml/metadata` | Get SAML service provider metadata |
21+
| [POST](#post-cluster-sso-saml-metadata) | `/v1/cluster/sso/saml/metadata` | Upload SAML identity provider metadata |
22+
23+
## Get SSO configuration {#get-cluster-sso}
24+
25+
GET /v1/cluster/sso
26+
27+
Get the single sign-on configuration as JSON.
28+
29+
#### Required permissions
30+
31+
| Permission name | Roles |
32+
|-----------------|-------|
33+
| [view_sso]({{< relref "/operate/rs/references/rest-api/permissions#view_sso" >}}) | admin<br />user_manager |
34+
35+
### Request {#get-request}
36+
37+
#### Example HTTP request
38+
39+
GET /v1/cluster/sso
40+
41+
#### Request headers
42+
43+
| Key | Value | Description |
44+
|-----|-------|-------------|
45+
| Host | cnm.cluster.fqdn | Domain name |
46+
| Accept | application/json | Accepted media type |
47+
48+
### Response {#get-response}
49+
50+
Returns an [SSO object]({{< relref "/operate/rs/references/rest-api/objects/sso" >}}).
51+
52+
#### Example JSON body
53+
54+
```json
55+
{
56+
"control_plane": true,
57+
"protocol": "saml2",
58+
"enforce_control_plane": false,
59+
"issuer": {
60+
"id": "urn:sso:example:idp",
61+
"login_url": "https://idp.example.com/sso/saml",
62+
"logout_url": "https://idp.example.com/sso/slo"
63+
},
64+
"service": {
65+
"saml2": {
66+
"entity_id": "https://cnm.cluster.fqdn/sp",
67+
"acs_url": "https://cnm.cluster.fqdn/v1/cluster/sso/saml/acs",
68+
"slo_url": "https://cnm.cluster.fqdn/v1/cluster/sso/saml/slo"
69+
}
70+
}
71+
}
72+
```
73+
74+
### Status codes {#get-status-codes}
75+
76+
| Code | Description |
77+
|------|-------------|
78+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success |
79+
80+
## Update SSO configuration {#put-cluster-sso}
81+
82+
PUT /v1/cluster/sso
83+
84+
Set or update the cluster single sign-on configuration.
85+
86+
#### Required permissions
87+
88+
| Permission name | Roles |
89+
|-----------------|-------|
90+
| [config_sso]({{< relref "/operate/rs/references/rest-api/permissions#config_sso" >}}) | admin<br />user_manager |
91+
92+
### Request {#put-request}
93+
94+
#### Example HTTP request
95+
96+
PUT /v1/cluster/sso
97+
98+
#### Example JSON body
99+
100+
```json
101+
{
102+
"control_plane": false,
103+
"protocol": "saml2",
104+
"enforce_control_plane": false,
105+
"issuer": {
106+
"id": "urn:sso:example:idp",
107+
"login_url": "https://idp.example.com/sso/saml",
108+
"logout_url": "https://idp.example.com/sso/slo"
109+
},
110+
"service": {
111+
"saml2": {
112+
"entity_id": "https://cnm.cluster.fqdn/sp",
113+
"acs_url": "https://cnm.cluster.fqdn/v1/cluster/sso/saml/acs",
114+
"slo_url": "https://cnm.cluster.fqdn/v1/cluster/sso/saml/slo"
115+
}
116+
}
117+
}
118+
```
119+
120+
#### Request headers
121+
122+
| Key | Value | Description |
123+
|-----|-------|-------------|
124+
| Host | cnm.cluster.fqdn | Domain name |
125+
| Accept | application/json | Accepted media type |
126+
127+
#### Request body
128+
129+
Include an [SSO object]({{< relref "/operate/rs/references/rest-api/objects/sso" >}}) with updated fields in the request body.
130+
131+
### Response {#put-response}
132+
133+
Returns a status code. If an error occurs, the response body can include an error code and message with more details.
134+
135+
### Error codes {#put-error-codes}
136+
137+
Possible `error_code` values:
138+
139+
| Code | Description |
140+
|------|-------------|
141+
| missing_param | A required parameter is missing while SSO is being enabled |
142+
| missing_certificate | SSO certificate is not found while SSO is being enabled |
143+
144+
### Status codes {#put-status-codes}
145+
146+
| Code | Description |
147+
|------|-------------|
148+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, SSO config has been set |
149+
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad or missing configuration parameters |
150+
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Missing required certificate |
151+
152+
## Delete SSO configuration {#delete-cluster-sso}
153+
154+
DELETE /v1/cluster/sso
155+
156+
Clear the single sign-on configuration.
157+
158+
#### Required permissions
159+
160+
| Permission name | Roles |
161+
|-----------------|-------|
162+
| [config_sso]({{< relref "/operate/rs/references/rest-api/permissions#config_sso" >}}) | admin<br />user_manager |
163+
164+
### Request {#delete-request}
165+
166+
#### Example HTTP request
167+
168+
DELETE /v1/cluster/sso
169+
170+
#### Request headers
171+
172+
| Key | Value | Description |
173+
|-----|-------|-------------|
174+
| Host | cnm.cluster.fqdn | Domain name |
175+
| Accept | application/json | Accepted media type |
176+
177+
### Response {#delete-response}
178+
179+
Returns a status code.
180+
181+
### Error codes {#delete-error-codes}
182+
183+
Possible `error_code` values:
184+
185+
| Code | Description |
186+
|------|-------------|
187+
| delete_certificate_error | An error occurred during SSO certificate deletion |
188+
189+
### Status codes {#delete-status-codes}
190+
191+
| Code | Description |
192+
|------|-------------|
193+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success |
194+
| [500 Internal Server Error](https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server-error) | Error during deletion |
195+
196+
## Get SAML service provider metadata {#get-cluster-sso-saml-metadata}
197+
198+
GET /v1/cluster/sso/saml/metadata
199+
200+
Generates and returns the SAML2 service provider metadata XML.
201+
202+
#### Required permissions
203+
204+
| Permission name | Roles |
205+
|-----------------|-------|
206+
| [view_sso]({{< relref "/operate/rs/references/rest-api/permissions#view_sso" >}}) | admin<br />user_manager |
207+
208+
### Request {#get-metadata-request}
209+
210+
#### Example HTTP request
211+
212+
GET /v1/cluster/sso/saml/metadata
213+
214+
#### Request headers
215+
216+
| Key | Value | Description |
217+
|-----|-------|-------------|
218+
| Host | cnm.cluster.fqdn | Domain name |
219+
| Accept | application/samlmetadata+xml | Accepted media type |
220+
221+
### Response {#get-metadata-response}
222+
223+
Returns SAML2 service provider metadata as XML.
224+
225+
#### Example response body
226+
227+
```xml
228+
<?xml version="1.0" encoding="UTF-8"?>
229+
<md:EntityDescriptor
230+
xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
231+
...
232+
</md:EntityDescriptor>
233+
```
234+
235+
### Error codes {#get-metadata-error-codes}
236+
237+
Possible `error_code` values:
238+
239+
| Code | Description |
240+
|------|-------------|
241+
| missing_certificate | Service certificate is missing |
242+
| saml_metadata_generation_error | An error occurred while generating the XML metadata |
243+
244+
### Status codes {#get-metadata-status-codes}
245+
246+
| Code | Description |
247+
|------|-------------|
248+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success |
249+
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Missing required service certificate |
250+
| [500 Internal Server Error](https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server-error) | Unexpected error when generating metadata |
251+
252+
## Upload SAML identity provider metadata {#post-cluster-sso-saml-metadata}
253+
254+
POST /v1/cluster/sso/saml/metadata
255+
256+
Uploads and validates the SAML2 identity provider metadata XML.
257+
258+
#### Required permissions
259+
260+
| Permission name | Roles |
261+
|-----------------|-------|
262+
| [config_sso]({{< relref "/operate/rs/references/rest-api/permissions#config_sso" >}}) | admin<br />user_manager |
263+
264+
### Request {#post-metadata-request}
265+
266+
#### Example HTTP request
267+
268+
POST /v1/cluster/sso/saml/metadata
269+
270+
#### Example JSON body
271+
272+
```json
273+
{
274+
"idp_metadata": "YWp3cjkwcHR1eWF3MHJ0eTkwYXc0eXQwOW4..."
275+
}
276+
```
277+
278+
#### Request headers
279+
280+
| Key | Value | Description |
281+
|-----|-------|-------------|
282+
| Host | cnm.cluster.fqdn | Domain name |
283+
| Accept | application/json | Accepted media type |
284+
285+
#### Request body
286+
287+
| Name | Type/Value | Description |
288+
|------|------------|-------------|
289+
| idp_metadata | string | Base64-encoded SAML2 identity provider metadata XML |
290+
291+
### Response {#post-metadata-response}
292+
293+
Returns an [SSO object]({{< relref "/operate/rs/references/rest-api/objects/sso" >}}) with the updated configuration.
294+
295+
#### Example JSON body
296+
297+
```json
298+
{
299+
"control_plane": true,
300+
"protocol": "saml2",
301+
"enforce_control_plane": false,
302+
"issuer": {
303+
"id": "urn:sso:example:idp",
304+
"login_url": "https://idp.example.com/sso/saml",
305+
"logout_url": "https://idp.example.com/sso/slo"
306+
},
307+
"service": {
308+
"saml2": {
309+
"entity_id": "https://cnm.cluster.fqdn/sp",
310+
"acs_url": "https://cnm.cluster.fqdn/v1/cluster/sso/saml/acs",
311+
"slo_url": "https://cnm.cluster.fqdn/v1/cluster/sso/saml/slo"
312+
}
313+
}
314+
}
315+
```
316+
317+
### Error codes {#post-metadata-error-codes}
318+
319+
Possible `error_code` values:
320+
321+
| Code | Description |
322+
|------|-------------|
323+
| saml_metadata_validation_error | IdP metadata failed configuration validation checks |
324+
| saml_metadata_parsing_error | IdP metadata is not a valid base64-encoded XML |
325+
| missing_certificate | SSO certificate is not found while SSO is being enabled |
326+
327+
### Status codes {#post-metadata-status-codes}
328+
329+
| Code | Description |
330+
|------|-------------|
331+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success |
332+
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad or missing parameters |
333+
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Missing required service certificate |

0 commit comments

Comments
 (0)