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

[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`