124 lines
7.0 KiB
Plaintext
124 lines
7.0 KiB
Plaintext
[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`
|