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: #53858
This commit is contained in:
Ioannis Kakavas
GitHub
parent
5856344691
commit
b27f23a80d
|
|
@ -0,0 +1,48 @@
|
||||||
|
[role="xpack"]
|
||||||
|
[[idp-saml-delete-sp]]
|
||||||
|
=== Remove a SAML service provider
|
||||||
|
++++
|
||||||
|
<titleabbrev>Remove a SAML service provider</titleabbrev>
|
||||||
|
++++
|
||||||
|
Removes a SAML service provider definition from this identity provider.
|
||||||
|
|
||||||
|
[[idp-saml-delete-sp-request]]
|
||||||
|
==== {api-request-title}
|
||||||
|
|
||||||
|
`DELETE /_idp/saml/sp/{sp_entity_id}`
|
||||||
|
|
||||||
|
[[idp-saml-delete-sp-prereqs]]
|
||||||
|
==== {api-prereq-title}
|
||||||
|
|
||||||
|
* To use this API, you must have a role that grants the `cluster:admin/idp/saml/sp/delete` privilege.
|
||||||
|
|
||||||
|
[[idp-saml-delete-desc]]
|
||||||
|
==== {api-description-title}
|
||||||
|
|
||||||
|
This API removes a service provider from the identity provider by deleting the underlying document that stores
|
||||||
|
the service provider definition.
|
||||||
|
|
||||||
|
[[idp-saml-delete-sp-path-params]]
|
||||||
|
==== {api-path-parms-title}
|
||||||
|
|
||||||
|
`sp_entity_id::
|
||||||
|
(string) The SAML entity Id of the service provider to be removed. In case the entity Id is a URL, it should be urlencoded.
|
||||||
|
|
||||||
|
[[idp-saml-delete-sp-params]]
|
||||||
|
==== {api-query-parms-title}
|
||||||
|
|
||||||
|
`refresh`::
|
||||||
|
(Optional, string) One of `true`, `false`, or `wait_for`.
|
||||||
|
These values have the same meaning as in the <<docs-refresh, Index API>>,
|
||||||
|
but the default value for this API is `false`.
|
||||||
|
|
||||||
|
[[idp-saml-delete-example]]
|
||||||
|
==== {api-examples-title}
|
||||||
|
|
||||||
|
The following example deletes a service provider definition from the identity provider
|
||||||
|
|
||||||
|
[source, console]
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
DELETE /_idp/saml/sp/https%3A%2F%2Fsome.sp.org%2F
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
// TEST[skip:Do not enable identity provider for the docs cluster, at least not yet]
|
||||||
|
|
@ -0,0 +1,123 @@
|
||||||
|
[role="xpack"]
|
||||||
|
[[idp-saml-init]]
|
||||||
|
=== Generate a SAML authentication response message
|
||||||
|
++++
|
||||||
|
<titleabbrev>Generate SAML response</titleabbrev>
|
||||||
|
++++
|
||||||
|
Generates a SAML Response message to be sent to a Service Provider
|
||||||
|
|
||||||
|
[[idp-saml-init-request]]
|
||||||
|
==== {api-request-title}
|
||||||
|
|
||||||
|
`POST /_idp/saml/init`
|
||||||
|
|
||||||
|
[[idp-saml-init-prereqs]]
|
||||||
|
==== {api-prereq-title}
|
||||||
|
|
||||||
|
* To use this API, you must have a role that grants the `cluster:admin/idp/saml/init` privilege.
|
||||||
|
|
||||||
|
[[idp-saml-init-desc]]
|
||||||
|
==== {api-description-title}
|
||||||
|
|
||||||
|
This API generates a SAML Response message that should be sent to a Service Provider as part of an
|
||||||
|
IDP initiated or SP initiated SAML Single Sign On. This API expects the caller to present
|
||||||
|
credentials for the user that the SAML Response will be created for as "Secondary Authentication"
|
||||||
|
using the `es-secondary-authorization` HTTP Request header.
|
||||||
|
|
||||||
|
The SAML response is returned as a String that contains an XML document. The caller of the API is responsible to instruct
|
||||||
|
the end user's browser to make an HTTP Post request to the Service Provider with the SAML response
|
||||||
|
Base64 encoded.
|
||||||
|
|
||||||
|
[[idp-saml-init-body]]
|
||||||
|
==== {api-request-body-title}
|
||||||
|
|
||||||
|
The following parameters can be specified in the body of a POST request:
|
||||||
|
|
||||||
|
`entity_id`::
|
||||||
|
(Required, string) The SAML entity Id of the service provider that will be the recipient of the SAML Response.
|
||||||
|
|
||||||
|
`acs`::
|
||||||
|
(Required, string) The assertion consumer service URL of the service provider that will be the recipient of the SAML Response.
|
||||||
|
|
||||||
|
`authn_state`::
|
||||||
|
(Optional, object) The JSON structure that <<idp-saml-validate>> returns. This should only be
|
||||||
|
provided when calling this API as part of an SP initiated Single Sign On.
|
||||||
|
|
||||||
|
|
||||||
|
[[idp-saml-init-example]]
|
||||||
|
==== {api-examples-title}
|
||||||
|
|
||||||
|
The following example generates a SAML Response for an IDP initiated SAML Single Sign On to the Service Provider with entity Id
|
||||||
|
`https://sp1.kibana.org` and an assertion consumer service URL that is `https://sp1.kibana.org/saml/acs`
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
curl -u idp_admin:idp_admin_pwd <1> \
|
||||||
|
-H 'Content-Type: application/json' \
|
||||||
|
-H 'es-secondary-authorization: ApiKey dVhmUDBuQUJERWhZWEZaQVg5S0k6WUJubmZwNEtRZ1d4cGRxdXBzZmFDUQ==' <2> \
|
||||||
|
localhost:9200/_idp/saml/init -d '{"entity_id":"https://sp1.kibana.org","acs":"https://sp1.kibana.org/saml/acs"}'
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
// NOTCONSOLE
|
||||||
|
<1> The credentials of the user that has the necessary privileges to call this API
|
||||||
|
<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
|
||||||
|
header, an {es} access token, or an API key.
|
||||||
|
|
||||||
|
|
||||||
|
The following example generates a SAML Response for an SP initiated SAML Single Sign On to the Service Provider with entity Id
|
||||||
|
`https://sp1.kibana.org` that would have originally sent an authentication request and which has been validated with the
|
||||||
|
use of <<idp-saml-validate>>
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
curl -u idp_admin:idp_admin_pwd <1> -H 'Content-Type: application/json' \
|
||||||
|
-H 'es-secondary-authorization: ApiKey dVhmUDBuQUJERWhZWEZaQVg5S0k6WUJubmZwNEtRZ1d4cGRxdXBzZmFDUQ==' <2>\
|
||||||
|
localhost:9200/_idp/saml/init -d '{"entity_id":"https://sp1.kibana.org","acs":"https://sp1.kibana.org/saml/acs",
|
||||||
|
"authn_state":{"authn_request_id":"_3243243243fdwfsd34r2f32f23","nameid_format":"urn:oasis:names:tc:SAML:2.0:nameid-format:transient"}<3>}'
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
// NOTCONSOLE
|
||||||
|
<1> The credentials of the user that has the necessary privileges to call this API
|
||||||
|
<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
|
||||||
|
header, an elasticsearch access token, or an API key.
|
||||||
|
<3> The `authn_state` JSON structure as it was returned by <<idp-saml-validate>>
|
||||||
|
|
||||||
|
|
||||||
|
A successful call returns the SAML Response as an XML String, the URL to post this SAML Response to, and information about the Service
|
||||||
|
Provider that should receive this SAML Response.
|
||||||
|
|
||||||
|
[source, console-result]
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
{
|
||||||
|
"post_url" : "https://sp1.kibana.org/saml/acs",
|
||||||
|
"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>",
|
||||||
|
"saml_status" : "urn:oasis:names:tc:SAML:2.0:status:Success",
|
||||||
|
"error" : null,
|
||||||
|
"service_provider" : {
|
||||||
|
"entity_id" : "https://sp1.kibana.org"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
// TESTRESPONSE[skip:Do not enable identity provider for the docs cluster, at least not yet]
|
||||||
|
|
||||||
|
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
|
||||||
|
code indicating that the authentication request failed and the reason for that failure. A `saml_status` of
|
||||||
|
`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
|
||||||
|
`urn:oasis:names:tc:SAML:2.0:status:Responder` indicates that something went wrong in the IDP side. The `error` field contains a short
|
||||||
|
human friendly interpretation of the error that is outside the SAML standard and is meant to be communicated to the user, especially
|
||||||
|
if the user is not redirected back the SP with the `saml_response`
|
||||||
|
|
||||||
|
[source, console-result]
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
{
|
||||||
|
"post_url" : "https://sp1.kibana.org/saml/acs",
|
||||||
|
"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>",
|
||||||
|
"saml_status" : "urn:oasis:names:tc:SAML:2.0:status:Requester",
|
||||||
|
"error" : "User [user1] is not permitted to access service [https://sp1.kibana.org]",
|
||||||
|
"service_provider" : {
|
||||||
|
"entity_id" : "https://sp1.kibana.org"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
// TESTRESPONSE[skip:Do not enable identity provider for the docs cluster, at least not yet]
|
||||||
|
|
||||||
|
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
|
||||||
|
`es-secondary-authorization` is wrong, the IDP will respond with `403`
|
||||||
|
|
@ -0,0 +1,56 @@
|
||||||
|
[role="xpack"]
|
||||||
|
[[idp-saml-metadata]]
|
||||||
|
=== Generate SAML metadata for the IDP
|
||||||
|
++++
|
||||||
|
<titleabbrev>Generate SAML metadata for the IDP</titleabbrev>
|
||||||
|
++++
|
||||||
|
Generates a SAML metadata document for the Identity Provider, describing its configuration and capabilities.
|
||||||
|
|
||||||
|
[[idp-saml-metadata-request]]
|
||||||
|
==== {api-request-title}
|
||||||
|
|
||||||
|
`GET /_idp/saml/metadata/{sp_entity_id}`
|
||||||
|
|
||||||
|
[[idp-saml-metadata-prereqs]]
|
||||||
|
==== {api-prereq-title}
|
||||||
|
|
||||||
|
* To use this API, you must have a role that grants the `cluster:admin/idp/saml/metadata` privilege.
|
||||||
|
|
||||||
|
[[idp-saml-metadata-desc]]
|
||||||
|
==== {api-description-title}
|
||||||
|
|
||||||
|
This API generates a SAML metadata XML Document that can be consumed by a service provider in order
|
||||||
|
to be configured to work with this identity provider
|
||||||
|
|
||||||
|
[[idp-saml-metadata-path-params]]
|
||||||
|
==== {api-path-parms-title}
|
||||||
|
|
||||||
|
`sp_entity_id::
|
||||||
|
(string) The SAML entity Id of the service provider that will consume this SAML metadata document.
|
||||||
|
|
||||||
|
`acs`::
|
||||||
|
(Optional, string) The SAML Assertion Consumer Service URL of the service provider that will consume this SAML.
|
||||||
|
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.
|
||||||
|
metadata document.
|
||||||
|
|
||||||
|
[[idp-saml-metadata-example]]
|
||||||
|
==== {api-examples-title}
|
||||||
|
|
||||||
|
The following example generates a SAML metadata document to be consumed by the service provider with
|
||||||
|
entity Id `https://some.sp.org/`.
|
||||||
|
|
||||||
|
[source, console]
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
GET /_idp/saml/metadata/https%3A%2F%2Fsome.sp.org%2F?acs=https%3A%2F%2Fsome.sp.org%2Fsaml%2Facs
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
// TEST[skip:Do not enable identity provider for the docs cluster, at least not yet]
|
||||||
|
|
||||||
|
a successful call returns the SAML metadata as an XML String
|
||||||
|
|
||||||
|
[source, console-result]
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
{
|
||||||
|
"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>"
|
||||||
|
}
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
// TESTRESPONSE[skip:Do not enable identity provider for the docs cluster, at least not yet]
|
||||||
|
|
@ -0,0 +1,102 @@
|
||||||
|
[role="xpack"]
|
||||||
|
[[idp-saml-register-sp]]
|
||||||
|
=== Register or update a SAML service provider
|
||||||
|
++++
|
||||||
|
<titleabbrev>Register or update a SAML service provider</titleabbrev>
|
||||||
|
++++
|
||||||
|
Registers a SAML service provider for use with this Identity Provider or updates the configuration of an existing one.
|
||||||
|
|
||||||
|
[[idp-saml-register-sp-request]]
|
||||||
|
==== {api-request-title}
|
||||||
|
|
||||||
|
`POST /_idp/saml/sp/{sp_entity_id}` +
|
||||||
|
`PUT /_idp/saml/sp/{sp_entity_id}`
|
||||||
|
|
||||||
|
[[idp-saml-register-sp-prereqs]]
|
||||||
|
==== {api-prereq-title}
|
||||||
|
|
||||||
|
* To use this API, you must have a role that grants the `cluster:admin/idp/saml/sp` privilege.
|
||||||
|
|
||||||
|
[[idp-saml-register-desc]]
|
||||||
|
==== {api-description-title}
|
||||||
|
|
||||||
|
This API registers a Service Provider with the Identity Provider and sets the necessary configuration options for that SP.
|
||||||
|
|
||||||
|
|
||||||
|
[[idp-saml-register-sp-path-params]]
|
||||||
|
==== {api-path-parms-title}
|
||||||
|
|
||||||
|
`sp_entity_id`::
|
||||||
|
(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.
|
||||||
|
|
||||||
|
[[idp-saml-register-sp-params]]
|
||||||
|
==== {api-query-parms-title}
|
||||||
|
|
||||||
|
`refresh`::
|
||||||
|
(Optional, string) One of `true`, `false`, or `wait_for`.
|
||||||
|
These values have the same meaning as in the <<docs-refresh, Index API>>,
|
||||||
|
but the default value for this API is `false`.
|
||||||
|
|
||||||
|
[[idp-saml-register-sp-body]]
|
||||||
|
==== {api-request-body-title}
|
||||||
|
|
||||||
|
The following parameters can be specified in the body of a POST or PUT request:
|
||||||
|
|
||||||
|
`name`::
|
||||||
|
(Required, string) A name to identify this service provider. Used only for informational purposes
|
||||||
|
|
||||||
|
`entity_id`::
|
||||||
|
(Optional, string) The SAML entity Id of the service provider. If not set, it will be populated with the value from the URL parameter.
|
||||||
|
If set, it must match the value that is passed in the URL parameter.
|
||||||
|
|
||||||
|
`acs`::
|
||||||
|
(Required, string) The assertion consumer service URL of the service provider.
|
||||||
|
|
||||||
|
`enabled`::
|
||||||
|
(Optional, boolean) Defines whether this service provider is enabled or not. Defaults to `true`.
|
||||||
|
|
||||||
|
`name_id_format`::
|
||||||
|
(Optional, string) The SAML NameID Format that this service provider wants the NameIDs of the authenticating users to have in the SAML
|
||||||
|
Responses it receives. Defaults to an empty string, in which case the IDP default value will be used. Currently, only
|
||||||
|
`urn:oasis:names:tc:SAML:2.0:nameid-format:transient` is supported.
|
||||||
|
|
||||||
|
`sign_messages`::
|
||||||
|
(Optional, array) The types of messages that this service provider will sign. Permitted values are `authn`, `logout`. Defaults to no
|
||||||
|
values.
|
||||||
|
|
||||||
|
`authn_expiry_ms`::
|
||||||
|
(Optional, long) The duration (in milliseconds) of the validity of the SAML assertion as it is encoded in the `<Conditions>` element.
|
||||||
|
Defaults to the IDP default value which is 30000 ( 5 min ).
|
||||||
|
|
||||||
|
`privileges`::
|
||||||
|
(Required, object)
|
||||||
|
|
||||||
|
`attributes`::
|
||||||
|
(Required, object) The names of the SAML Attributes that the IDP should use in the SAML response for the values of the following
|
||||||
|
elasticsearch user properties : `principal`, `name`, `email` and the deduced roles based on the privileges configured.
|
||||||
|
The SAML Attribute name for `principal` is required.
|
||||||
|
|
||||||
|
[[idp-saml-register-example]]
|
||||||
|
==== {api-examples-title}
|
||||||
|
|
||||||
|
The following example registers a service provider for use with the identity provider
|
||||||
|
|
||||||
|
[source, console]
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
POST /_idp/saml/sp/https%3A%2F%2Fsome.sp.org%2F
|
||||||
|
{
|
||||||
|
"name" : "My Service Provider",
|
||||||
|
"entity_id" : "https://some.sp.org/",
|
||||||
|
"acs" : "https://some.sp.org/saml/acs",
|
||||||
|
"privilegs" : {
|
||||||
|
"resource" : "https://some.sp.org/",
|
||||||
|
"roles" : {
|
||||||
|
"administrator": "sso:administrator"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"attributes" : {
|
||||||
|
"principal" : "urn:oid:0.9.2342.19200300.100.1.1"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
// TEST[skip:Do not enable identity provider for the docs cluster, at least not yet]
|
||||||
|
|
@ -0,0 +1,82 @@
|
||||||
|
[role="xpack"]
|
||||||
|
[[idp-saml-validate]]
|
||||||
|
=== Validate a SAML authentication request
|
||||||
|
++++
|
||||||
|
<titleabbrev>Validate a SAML authentication request</titleabbrev>
|
||||||
|
++++
|
||||||
|
|
||||||
|
Validates a SAML authentication request that was received from a Service Provider.
|
||||||
|
|
||||||
|
[[idp-saml-validate-request]]
|
||||||
|
==== {api-request-title}
|
||||||
|
|
||||||
|
`POST /_idp/saml/validate`
|
||||||
|
|
||||||
|
[[idp-saml-validate-prereqs]]
|
||||||
|
==== {api-prereq-title}
|
||||||
|
|
||||||
|
* To use this API, you must have a role that grants the `cluster:admin/idp/saml/validate` privilege.
|
||||||
|
|
||||||
|
[[idp-saml-validate-desc]]
|
||||||
|
==== {api-description-title}
|
||||||
|
|
||||||
|
This API validates a SAML authentication request. It does so by
|
||||||
|
* Verifying that the SAML message is syntactically correct
|
||||||
|
* Validating the signature if the authentication request should be signed and a signature is provided
|
||||||
|
* Verifying that the IDP is the intended recipient of this
|
||||||
|
* Verifying that the SP is known to the IDP and trusted and that the ACS URL it asks us to send the response is known and trusted
|
||||||
|
* Verifying that the IDP can satisfy the requirements that the SP imposes ( i.e. NameID Policy )
|
||||||
|
|
||||||
|
[[idp-saml-validate-request-body]]
|
||||||
|
==== {api-request-body-title}
|
||||||
|
|
||||||
|
The following parameters can be specified in the body of a POST request:
|
||||||
|
|
||||||
|
`authn_request_query`::
|
||||||
|
(Required, string) The SAML Authentication request in the form of the query
|
||||||
|
string of the request that was sent by the Service Provider.
|
||||||
|
|
||||||
|
|
||||||
|
[[idp-saml-validate-example]]
|
||||||
|
==== {api-examples-title}
|
||||||
|
|
||||||
|
The following example submits an unsigned SAML authentication request for validation.
|
||||||
|
|
||||||
|
[source, console]
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
POST /_idp/saml/validate
|
||||||
|
{
|
||||||
|
"authn_request_query":"SAMLRequest=fZFbb4MwDIX%2FSpR3IEA7aFSoqlWVKnXT1Mse9jKZENpokLA4VNu%2FH71NnTT11efYx%2F48nnw1NTlIi8rojIY%2Bo0RqYUqldxndbuZeSif5GKGpo5ZPO7fXK%2FnZSXSkb9TIz0pGO6u5AVTINTQSuRN8PX1a8shnvLXGGWFqSqaI0ro%2B6tFo7Bpp19IelJDb1TKje%2Bda5EGAbeh%2FqAI0%2BMbugmNCAAIpmfWxSoM7rXp1i9p0pS9r6DXhC3P2K60cJYtZRt8hhCKsCmDDQTpiMEgfQpZUMknTMh4BKxLRyyyuejtiJxcaHWiX0YhFzGOxF442YchZwqOhHw%2FYGyWvV1z9cfQCh5%2Ba7S2V%2B1DgioLm%2Fx8%2BDm4H%2F%2F7guZ%2B0mL2YWolvMje2AXc%2F6FhRpVedrNxZ0KikdjTILwl%2F%2F5r%2FAA%3D%3D&RelayState=SAwdVW" <1>
|
||||||
|
}
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
// TEST[skip:Do not enable identity provider for the docs cluster, at least not yet]
|
||||||
|
<1> The query string, urlencoded, with no further modifications from what was sent by the user's browser.
|
||||||
|
|
||||||
|
A successful call returns a JSON structure that contains information about the Service Provider that initiated the Signle Sign On, and
|
||||||
|
a nested JSON structured called `authn_state` that should not be interpreted by the caller but passed as-is in subsequent calls to the
|
||||||
|
init API.
|
||||||
|
|
||||||
|
|
||||||
|
[source, console-result]
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
{
|
||||||
|
"service_provider" : {
|
||||||
|
"entity_id" : "https://sp1.kibana.org" <1>
|
||||||
|
"acs" : "https://sp1.kibana.org/saml/acs" <2>
|
||||||
|
},
|
||||||
|
"force_authn" : false, <3>
|
||||||
|
"authn_state" : {
|
||||||
|
"authn_request_id" : "_3243243243fdwfsd34r2f32f23",
|
||||||
|
"nameid_format" : "urn:oasis:names:tc:SAML:2.0:nameid-format:transient"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
// TESTRESPONSE[skip:Do not enable identity provider for the docs cluster, at least not yet]
|
||||||
|
<1> The SAML entity ID of the Service Provider that generated the authentication request
|
||||||
|
<2> The SAML assertion consumer service URL of the Service Provider that generated the authentication request
|
||||||
|
<2> Indicates whether or not the Service Provider requests that the end user is forced to re-authenticate even if they have
|
||||||
|
an existing session with the Identity Provider.
|
||||||
|
|
||||||
|
IMPORTANT: It is assumed that the `authn_state` object is not passed to the end user and is not stored anywhere where it could be
|
||||||
|
edited by the end user ( i.e. in a Browser cookie ). If there is a need for this, then the caller of the API must take precautions and
|
||||||
|
ensure that the `authn_state` object is integrity protected ( i.e. signed or encrypted ).
|
||||||
|
|
@ -0,0 +1,35 @@
|
||||||
|
{
|
||||||
|
"idp.saml_delete_sp": {
|
||||||
|
"documentation": {
|
||||||
|
"url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/idp-saml-delete-sp.html"
|
||||||
|
},
|
||||||
|
"stability": "stable",
|
||||||
|
"url": {
|
||||||
|
"paths": [
|
||||||
|
{
|
||||||
|
"path": "/_idp/saml/sp/{sp_entity_id}",
|
||||||
|
"methods": [
|
||||||
|
"DELETE"
|
||||||
|
],
|
||||||
|
"parts": {
|
||||||
|
"sp_entity_id": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "The SAML entity ID of the Service Provider to delete"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"params": {
|
||||||
|
"refresh": {
|
||||||
|
"type": "enum",
|
||||||
|
"options": [
|
||||||
|
"true",
|
||||||
|
"false",
|
||||||
|
"wait_for"
|
||||||
|
],
|
||||||
|
"description": "If `true` (the default) then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes."
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,30 @@
|
||||||
|
{
|
||||||
|
"idp.saml_get_metadata": {
|
||||||
|
"documentation": {
|
||||||
|
"url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/idp-saml-metadata.html"
|
||||||
|
},
|
||||||
|
"stability": "stable",
|
||||||
|
"url": {
|
||||||
|
"paths": [
|
||||||
|
{
|
||||||
|
"path": "/_idp/saml/metadata/{sp_entity_id}",
|
||||||
|
"methods": [
|
||||||
|
"GET"
|
||||||
|
],
|
||||||
|
"parts": {
|
||||||
|
"sp_entity_id": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "The SAML entity ID of the Service Provider that will consume the metadata"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"params": {
|
||||||
|
"acs": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "The assertion consumer service URL of the Service Provider that will consume the metadata"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,22 @@
|
||||||
|
{
|
||||||
|
"idp.saml_init": {
|
||||||
|
"documentation": {
|
||||||
|
"url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/idp-saml-init.html"
|
||||||
|
},
|
||||||
|
"stability": "stable",
|
||||||
|
"url": {
|
||||||
|
"paths": [
|
||||||
|
{
|
||||||
|
"path": "/_idp/saml/init",
|
||||||
|
"methods": [
|
||||||
|
"POST"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"body": {
|
||||||
|
"description": "The SAML entity ID of the Service Provider",
|
||||||
|
"required": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,40 @@
|
||||||
|
{
|
||||||
|
"idp.saml_register_sp": {
|
||||||
|
"documentation": {
|
||||||
|
"url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/idp-saml-register-sp.html"
|
||||||
|
},
|
||||||
|
"stability": "stable",
|
||||||
|
"url": {
|
||||||
|
"paths": [
|
||||||
|
{
|
||||||
|
"path": "/_idp/saml/sp/{sp_entity_id}",
|
||||||
|
"methods": [
|
||||||
|
"POST",
|
||||||
|
"PUT"
|
||||||
|
],
|
||||||
|
"parts": {
|
||||||
|
"sp_entity_id": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "The SAML entity ID of the Service Provider to register"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"params": {
|
||||||
|
"refresh": {
|
||||||
|
"type": "enum",
|
||||||
|
"options": [
|
||||||
|
"true",
|
||||||
|
"false",
|
||||||
|
"wait_for"
|
||||||
|
],
|
||||||
|
"description": "If `true` (the default) then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes."
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"body": {
|
||||||
|
"description": "The Service Provider to register",
|
||||||
|
"required": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,22 @@
|
||||||
|
{
|
||||||
|
"idp.saml_validate": {
|
||||||
|
"documentation": {
|
||||||
|
"url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/idp-saml-validate.html"
|
||||||
|
},
|
||||||
|
"stability": "stable",
|
||||||
|
"url": {
|
||||||
|
"paths": [
|
||||||
|
{
|
||||||
|
"path": "/_idp/saml/validate",
|
||||||
|
"methods": [
|
||||||
|
"POST"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"body": {
|
||||||
|
"description": "The SAML authentication request to validate",
|
||||||
|
"required": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
Loading…
Reference in New Issue