Skip to content

Commit 89d1d4a

Browse files
jkakavasjkakavas
committed
Rest spec and documentation (elastic#54664)
This change adds the spec for the new REST APIs that we introduce for the IDP and documentation for each of the APIs. The documentation pages are intentionally not included in the API reference so as to minimize unnecessary exposure. supersedes: elastic#53858
1 parent 13fbbbc commit 89d1d4a

File tree

10 files changed

+560
-0
lines changed

10 files changed

+560
-0
lines changed

‎x-pack/plugin/identity-provider/docs/en/rest-api/idp-saml-delete-sp.asciidoc‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
[role="xpack"]
2+
[[idp-saml-delete-sp]]
3+
=== Remove a SAML service provider
4+
++++
5+
<titleabbrev>Remove a SAML service provider</titleabbrev>
6+
++++
7+
Removes a SAML service provider definition from this identity provider.
8+
9+
[[idp-saml-delete-sp-request]]
10+
==== {api-request-title}
11+
12+
`DELETE /_idp/saml/sp/{sp_entity_id}`
13+
14+
[[idp-saml-delete-sp-prereqs]]
15+
==== {api-prereq-title}
16+
17+
* To use this API, you must have a role that grants the `cluster:admin/idp/saml/sp/delete` privilege.
18+
19+
[[idp-saml-delete-desc]]
20+
==== {api-description-title}
21+
22+
This API removes a service provider from the identity provider by deleting the underlying document that stores
23+
the service provider definition.
24+
25+
[[idp-saml-delete-sp-path-params]]
26+
==== {api-path-parms-title}
27+
28+
`sp_entity_id::
29+
(string) The SAML entity Id of the service provider to be removed. In case the entity Id is a URL, it should be urlencoded.
30+
31+
[[idp-saml-delete-sp-params]]
32+
==== {api-query-parms-title}
33+
34+
`refresh`::
35+
(Optional, string) One of `true`, `false`, or `wait_for`.
36+
These values have the same meaning as in the <<docs-refresh, Index API>>,
37+
but the default value for this API is `false`.
38+
39+
[[idp-saml-delete-example]]
40+
==== {api-examples-title}
41+
42+
The following example deletes a service provider definition from the identity provider
43+
44+
[source, console]
45+
--------------------------------------------------------------------
46+
DELETE /_idp/saml/sp/https%3A%2F%2Fsome.sp.org%2F
47+
--------------------------------------------------------------------
48+
// TEST[skip:Do not enable identity provider for the docs cluster, at least not yet]

‎x-pack/plugin/identity-provider/docs/en/rest-api/idp-saml-init.asciidoc‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
[role="xpack"]
2+
[[idp-saml-init]]
3+
=== Generate a SAML authentication response message
4+
++++
5+
<titleabbrev>Generate SAML response</titleabbrev>
6+
++++
7+
Generates a SAML Response message to be sent to a Service Provider
8+
9+
[[idp-saml-init-request]]
10+
==== {api-request-title}
11+
12+
`POST /_idp/saml/init`
13+
14+
[[idp-saml-init-prereqs]]
15+
==== {api-prereq-title}
16+
17+
* To use this API, you must have a role that grants the `cluster:admin/idp/saml/init` privilege.
18+
19+
[[idp-saml-init-desc]]
20+
==== {api-description-title}
21+
22+
This API generates a SAML Response message that should be sent to a Service Provider as part of an
23+
IDP initiated or SP initiated SAML Single Sign On. This API expects the caller to present
24+
credentials for the user that the SAML Response will be created for as "Secondary Authentication"
25+
using the `es-secondary-authorization` HTTP Request header.
26+
27+
The SAML response is returned as a String that contains an XML document. The caller of the API is responsible to instruct
28+
the end user's browser to make an HTTP Post request to the Service Provider with the SAML response
29+
Base64 encoded.
30+
31+
[[idp-saml-init-body]]
32+
==== {api-request-body-title}
33+
34+
The following parameters can be specified in the body of a POST request:
35+
36+
`entity_id`::
37+
(Required, string) The SAML entity Id of the service provider that will be the recipient of the SAML Response.
38+
39+
`acs`::
40+
(Required, string) The assertion consumer service URL of the service provider that will be the recipient of the SAML Response.
41+
42+
`authn_state`::
43+
(Optional, object) The JSON structure that <<idp-saml-validate>> returns. This should only be
44+
provided when calling this API as part of an SP initiated Single Sign On.
45+
46+
47+
[[idp-saml-init-example]]
48+
==== {api-examples-title}
49+
50+
The following example generates a SAML Response for an IDP initiated SAML Single Sign On to the Service Provider with entity Id
51+
`https://sp1.kibana.org` and an assertion consumer service URL that is `https://sp1.kibana.org/saml/acs`
52+
53+
[source, sh]
54+
--------------------------------------------------------------------
55+
curl -u idp_admin:idp_admin_pwd <1> \
56+
-H 'Content-Type: application/json' \
57+
-H 'es-secondary-authorization: ApiKey dVhmUDBuQUJERWhZWEZaQVg5S0k6WUJubmZwNEtRZ1d4cGRxdXBzZmFDUQ==' <2> \
58+
localhost:9200/_idp/saml/init -d '{"entity_id":"https://sp1.kibana.org","acs":"https://sp1.kibana.org/saml/acs"}'
59+
--------------------------------------------------------------------
60+
// NOTCONSOLE
61+
<1> The credentials of the user that has the necessary privileges to call this API
62+
<2> The credentials of the end user for which the SAML Response will be generated. These can be in the form of a Basic authentication
63+
header, an {es} access token, or an API key.
64+
65+
66+
The following example generates a SAML Response for an SP initiated SAML Single Sign On to the Service Provider with entity Id
67+
`https://sp1.kibana.org` that would have originally sent an authentication request and which has been validated with the
68+
use of <<idp-saml-validate>>
69+
70+
[source, sh]
71+
--------------------------------------------------------------------
72+
curl -u idp_admin:idp_admin_pwd <1> -H 'Content-Type: application/json' \
73+
-H 'es-secondary-authorization: ApiKey dVhmUDBuQUJERWhZWEZaQVg5S0k6WUJubmZwNEtRZ1d4cGRxdXBzZmFDUQ==' <2>\
74+
localhost:9200/_idp/saml/init -d '{"entity_id":"https://sp1.kibana.org","acs":"https://sp1.kibana.org/saml/acs",
75+
"authn_state":{"authn_request_id":"_3243243243fdwfsd34r2f32f23","nameid_format":"urn:oasis:names:tc:SAML:2.0:nameid-format:transient"}<3>}'
76+
--------------------------------------------------------------------
77+
// NOTCONSOLE
78+
<1> The credentials of the user that has the necessary privileges to call this API
79+
<2> The credentials of the end user for which the SAML Response will be generated. These can be in the form of a Basic authentication
80+
header, an elasticsearch access token, or an API key.
81+
<3> The `authn_state` JSON structure as it was returned by <<idp-saml-validate>>
82+
83+
84+
A successful call returns the SAML Response as an XML String, the URL to post this SAML Response to, and information about the Service
85+
Provider that should receive this SAML Response.
86+
87+
[source, console-result]
88+
--------------------------------------------------------------------
89+
{
90+
"post_url" : "https://sp1.kibana.org/saml/acs",
91+
"saml_response" : "<?xml version="1.0" encoding="UTF-8"?><saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:xsd="http://www.w3.org/2001/XMLSchema" Destination="https://sp.some.org/api/security/v1/saml" ID="_845fbfc9f3254162ce1e161c91b07d85311d65cd" IssueInstant="2020-03-19T15:45:00.158Z" ...removed for brevity ... </saml2p:Response>",
92+
"saml_status" : "urn:oasis:names:tc:SAML:2.0:status:Success",
93+
"error" : null,
94+
"service_provider" : {
95+
"entity_id" : "https://sp1.kibana.org"
96+
}
97+
}
98+
--------------------------------------------------------------------
99+
// TESTRESPONSE[skip:Do not enable identity provider for the docs cluster, at least not yet]
100+
101+
A failed call, in the case of an SP initiated SSO returns a SAML Response as an XML String with its status set to the appropriate error
102+
code indicating that the authentication request failed and the reason for that failure. A `saml_status` of
103+
`urn:oasis:names:tc:SAML:2.0:status:Requester` indicates that the error is on the side of the SP or the user, while a `saml_status` of
104+
`urn:oasis:names:tc:SAML:2.0:status:Responder` indicates that something went wrong in the IDP side. The `error` field contains a short
105+
human friendly interpretation of the error that is outside the SAML standard and is meant to be communicated to the user, especially
106+
if the user is not redirected back the SP with the `saml_response`
107+
108+
[source, console-result]
109+
--------------------------------------------------------------------
110+
{
111+
"post_url" : "https://sp1.kibana.org/saml/acs",
112+
"saml_response" : "?xml version="1.0" encoding="UTF-8"?><saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:xsd="http://www.w3.org/2001/XMLSchema" Destination="https://sp1.kibana.org/api/saml/acs" ID="_845fbfc9f3254162ce1e161c91b07d85311d65cd" IssueInstant="2020-03-19T15:45:00.158Z" Version="2.0"><saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">https://idp.cloud.elastic.co</saml2:Issuer><ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">...removed for brevity...</ds:Signature><saml2p:Status><saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Requester"><samlp:StatusCode xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" Value="urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy"/></saml2p:StatusCode></saml2p:Status></saml2p:Response>",
113+
"saml_status" : "urn:oasis:names:tc:SAML:2.0:status:Requester",
114+
"error" : "User [user1] is not permitted to access service [https://sp1.kibana.org]",
115+
"service_provider" : {
116+
"entity_id" : "https://sp1.kibana.org"
117+
}
118+
}
119+
--------------------------------------------------------------------
120+
// TESTRESPONSE[skip:Do not enable identity provider for the docs cluster, at least not yet]
121+
122+
A failed call, in the case of an IDP initiated SSO returns an error with the appropriate HTTP Status code. i.e. if the value of the
123+
`es-secondary-authorization` is wrong, the IDP will respond with `403`

‎x-pack/plugin/identity-provider/docs/en/rest-api/idp-saml-metadata.asciidoc‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
[role="xpack"]
2+
[[idp-saml-metadata]]
3+
=== Generate SAML metadata for the IDP
4+
++++
5+
<titleabbrev>Generate SAML metadata for the IDP</titleabbrev>
6+
++++
7+
Generates a SAML metadata document for the Identity Provider, describing its configuration and capabilities.
8+
9+
[[idp-saml-metadata-request]]
10+
==== {api-request-title}
11+
12+
`GET /_idp/saml/metadata/{sp_entity_id}`
13+
14+
[[idp-saml-metadata-prereqs]]
15+
==== {api-prereq-title}
16+
17+
* To use this API, you must have a role that grants the `cluster:admin/idp/saml/metadata` privilege.
18+
19+
[[idp-saml-metadata-desc]]
20+
==== {api-description-title}
21+
22+
This API generates a SAML metadata XML Document that can be consumed by a service provider in order
23+
to be configured to work with this identity provider
24+
25+
[[idp-saml-metadata-path-params]]
26+
==== {api-path-parms-title}
27+
28+
`sp_entity_id::
29+
(string) The SAML entity Id of the service provider that will consume this SAML metadata document.
30+
31+
`acs`::
32+
(Optional, string) The SAML Assertion Consumer Service URL of the service provider that will consume this SAML.
33+
If this is not set, then this API will ignore any wildcard services and will fail if `sp_entity_id` is not a directly registered Service Provider.
34+
metadata document.
35+
36+
[[idp-saml-metadata-example]]
37+
==== {api-examples-title}
38+
39+
The following example generates a SAML metadata document to be consumed by the service provider with
40+
entity Id `https://some.sp.org/`.
41+
42+
[source, console]
43+
--------------------------------------------------------------------
44+
GET /_idp/saml/metadata/https%3A%2F%2Fsome.sp.org%2F?acs=https%3A%2F%2Fsome.sp.org%2Fsaml%2Facs
45+
--------------------------------------------------------------------
46+
// TEST[skip:Do not enable identity provider for the docs cluster, at least not yet]
47+
48+
a successful call returns the SAML metadata as an XML String
49+
50+
[source, console-result]
51+
--------------------------------------------------------------------
52+
{
53+
"metadata" : "<?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://idp.org"><md:IDPSSODescriptor WantAuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"><md:KeyDescriptor use="signing"><ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:X509Data><ds:X509Certificate>MIIDYzCCAkugAwIBAgIVAITQVqXYYUT0w04Z2gWAZ6pv7gwbMA0GCSqGSIb3DQEBCwUAMDQxMjAwBgNVBAMTKUVsYXN0aWMgQ2VydGlmaWNhdGUgVG9vbCBBdXRvZ2VuZXJhdGVkIENBMCAXDTIwMDEyODA2MzczNloYDzIxNjgxMDE5MDYzNzM2WjBRMRMwEQYKCZImiZPyLGQBGRYDb3JnMR0wGwYKCZImiZPyLGQBGRYNZWxhc3RpY3NlYXJjaDEMMAoGA1UECxMDaWRwMQ0wCwYDVQQDEwR0ZXN0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAujk+mVzI+qmf4gSJZdVVDdhFTi06kikb7FxG5JPu+gmU9Ke0LVEpP7Jp3gmhwsa18JUuvaepL1jnKmbbepKkEsvqUj4FuI/gImvFwb7X+xUwzNTYZAEvnZ4n16k0sBPuDuDibF0MGniVeLG3bD2VF3crFQrphFr+GZSXbVk5zIcSf6D6nSDcKmCNpVAK3jX9iV0nkr8cPtHOgprv1Y7mZgk5jwli9to0QD7r7OG5Db34R06JTMGTji+RULPISH1bc8FHdurRASkGmsei5GlJqPSuKdViuaKPmDrvKR8OK6gMzUd3pikJgD8veLxEuZ640FHPndPlvwJrSLwhitRgPQIDAQABo00wSzAdBgNVHQ4EFgQUD87H31WVQNfCc85/H2qhpzs3XfowHwYDVR0jBBgwFoAUVenAN+T06rqNDxjMcvgimnTw+FgwCQYDVR0TBAIwADANBgkqhkiG9w0BAQsFAAOCAQEAIvHYxT30cvoHWUE2saDVJ4qs/e0G3WusDyem3e4HkqwLEah06RDSgVCaOfW3ey5Q6CIQW3HHGUYqO0nU8JVCWdAk3+bUYJJOeLnwD+SbDxxKBhxLdx+BjWata85lfJTR9+dXs0RXAAN8dSiIaj9NSgnwiJqQQZf7i66S7XB58TDTdZlV3d26STLy5h7Uy6vyCka8Xu8HFQ4hH2qf2L6EhBbzVTB6tuyPQOQwrlLE65nhUNkfBbjZlre45UMc9GuxzHkbvd3HEQaroMHZxnu+/n/JDlgsrCYUEXnZnOXvgUPupPynoRdDN1F6r95TLyU9pYjDf/6zNPE854VF6y1TqQ==</ds:X509Certificate></ds:X509Data></ds:KeyInfo></md:KeyDescriptor><md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://idp.org/slo/post"/><md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat><md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat><md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp.org/sso/redirect"/></md:IDPSSODescriptor></md:EntityDescriptor>"
54+
}
55+
--------------------------------------------------------------------
56+
// TESTRESPONSE[skip:Do not enable identity provider for the docs cluster, at least not yet]

‎x-pack/plugin/identity-provider/docs/en/rest-api/idp-saml-register-sp.asciidoc‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
[role="xpack"]
2+
[[idp-saml-register-sp]]
3+
=== Register or update a SAML service provider
4+
++++
5+
<titleabbrev>Register or update a SAML service provider</titleabbrev>
6+
++++
7+
Registers a SAML service provider for use with this Identity Provider or updates the configuration of an existing one.
8+
9+
[[idp-saml-register-sp-request]]
10+
==== {api-request-title}
11+
12+
`POST /_idp/saml/sp/{sp_entity_id}` +
13+
`PUT /_idp/saml/sp/{sp_entity_id}`
14+
15+
[[idp-saml-register-sp-prereqs]]
16+
==== {api-prereq-title}
17+
18+
* To use this API, you must have a role that grants the `cluster:admin/idp/saml/sp` privilege.
19+
20+
[[idp-saml-register-desc]]
21+
==== {api-description-title}
22+
23+
This API registers a Service Provider with the Identity Provider and sets the necessary configuration options for that SP.
24+
25+
26+
[[idp-saml-register-sp-path-params]]
27+
==== {api-path-parms-title}
28+
29+
`sp_entity_id`::
30+
(string) The SAML entity Id of the service provider to be registered or updated. In case the entity Id is a URL, it should be urlencoded.
31+
32+
[[idp-saml-register-sp-params]]
33+
==== {api-query-parms-title}
34+
35+
`refresh`::
36+
(Optional, string) One of `true`, `false`, or `wait_for`.
37+
These values have the same meaning as in the <<docs-refresh, Index API>>,
38+
but the default value for this API is `false`.
39+
40+
[[idp-saml-register-sp-body]]
41+
==== {api-request-body-title}
42+
43+
The following parameters can be specified in the body of a POST or PUT request:
44+
45+
`name`::
46+
(Required, string) A name to identify this service provider. Used only for informational purposes
47+
48+
`entity_id`::
49+
(Optional, string) The SAML entity Id of the service provider. If not set, it will be populated with the value from the URL parameter.
50+
If set, it must match the value that is passed in the URL parameter.
51+
52+
`acs`::
53+
(Required, string) The assertion consumer service URL of the service provider.
54+
55+
`enabled`::
56+
(Optional, boolean) Defines whether this service provider is enabled or not. Defaults to `true`.
57+
58+
`name_id_format`::
59+
(Optional, string) The SAML NameID Format that this service provider wants the NameIDs of the authenticating users to have in the SAML
60+
Responses it receives. Defaults to an empty string, in which case the IDP default value will be used. Currently, only
61+
`urn:oasis:names:tc:SAML:2.0:nameid-format:transient` is supported.
62+
63+
`sign_messages`::
64+
(Optional, array) The types of messages that this service provider will sign. Permitted values are `authn`, `logout`. Defaults to no
65+
values.
66+
67+
`authn_expiry_ms`::
68+
(Optional, long) The duration (in milliseconds) of the validity of the SAML assertion as it is encoded in the `<Conditions>` element.
69+
Defaults to the IDP default value which is 30000 ( 5 min ).
70+
71+
`privileges`::
72+
(Required, object)
73+
74+
`attributes`::
75+
(Required, object) The names of the SAML Attributes that the IDP should use in the SAML response for the values of the following
76+
elasticsearch user properties : `principal`, `name`, `email` and the deduced roles based on the privileges configured.
77+
The SAML Attribute name for `principal` is required.
78+
79+
[[idp-saml-register-example]]
80+
==== {api-examples-title}
81+
82+
The following example registers a service provider for use with the identity provider
83+
84+
[source, console]
85+
--------------------------------------------------------------------
86+
POST /_idp/saml/sp/https%3A%2F%2Fsome.sp.org%2F
87+
{
88+
"name" : "My Service Provider",
89+
"entity_id" : "https://some.sp.org/",
90+
"acs" : "https://some.sp.org/saml/acs",
91+
"privilegs" : {
92+
"resource" : "https://some.sp.org/",
93+
"roles" : {
94+
"administrator": "sso:administrator"
95+
}
96+
},
97+
"attributes" : {
98+
"principal" : "urn:oid:0.9.2342.19200300.100.1.1"
99+
}
100+
}
101+
--------------------------------------------------------------------
102+
// TEST[skip:Do not enable identity provider for the docs cluster, at least not yet]

0 commit comments

Comments
 (0)