Document SAML APIs

[jkakavas]

This change adds documentation for the SAML APIs in Elasticsearch
and adds simple instructions on how these APIs can be used to
authenticate a user with SAML by a custom web application other
than Kibana.

Resolves: #40352

[elasticmachine]

Pinging @elastic/es-security

[elasticmachine]

Pinging @elastic/es-docs

[jkakavas]

@elasticmachine update branch

[jkakavas]

@elasticmachine test this please

[jkakavas]

java.lang.AssertionError: Failure at [painless/10_basic:109]: watch_record.state didn't match expected value:
            watch_record.state: expected String [executed] but was String [not_executed_already_queued]

@elasticmachine run elasticsearch-ci/2

[jkakavas]

@elasticmachine test this please

[tvernum]

I think we've iterated on this enough times, and it's time to get it out for public consumption.

[jkakavas]

@lcawl is this ok to merge from your perspective too ?

[lcawl]

If we don't specify an anchor here, our build makes one up, which is not reliable. I suggest:

Suggested change

	=== SAML without {kib}
	[[saml-no-kibana]]
	=== SAML without {kib}

[lcawl]

Likewise, we should have an anchor here too. Otherwise, it is currently defaulting to "_saml_realm". For example:

Suggested change

	==== SAML realm
	[[saml-no-kibana-realm]]
	==== SAML realm

[lcawl]

Likewise, this is defaulting to "_service_account_user_for_accessing_the_apis" for an anchor. I suggest explicitly setting it to something like this:

Suggested change

	==== Service Account user for accessing the APIs
	[[saml-no-kibana-user]]
	==== Service Account user for accessing the APIs

[lcawl]

This section's URL defaults to "_handling_the_idp_initiated_authentication_flow", so I suggest setting it to something like this:

Suggested change

	[[saml-idp-init]]

[lcawl]

This section URL defaults to "_handling_the_logout_flow", I suggest something like this:

Suggested change

	==== Handling the logout flow
	[[saml-logout]]
	==== Handling the logout flow

[lcawl]

When this PR is rebased against master, you'll see that this content is all now in the elasticsearch repo for use in the Elasticsearch Reference, so the URLs should change as follows:

Suggested change

	If you are using {kib}, see the {stack-ov}/saml-guide.html[SAML guide].
	If you are using {kib}, see the <<saml-guide>>.

[lcawl]

Suggested change

	access token as described in {ref}/security-api-get-token.html[get token API].
	access token as described in <<security-api-get-token,get token API>>.

[lcawl]

Suggested change

	See the {ref}/security-api-saml-prepare-authentication.html[SAML prepare authentication API] for more details.
	See the <<security-api-saml-prepare-authentication,SAML prepare authentication API>> for more details.

[lcawl]

Suggested change

	See {ref}/security-api-saml-authenticate.html[SAML authenticate API] for more details.
	See <<security-api-saml-authenticate,SAML authenticate API>> for more details.

[lcawl]

Suggested change

	access token as described in {ref}/security-api-get-token.html[get token API].
	access token as described in <<security-api-get-token,get token API>>.

[lcawl]

Suggested change

	{ref}/security-api-saml-logout.html[SAML logout API] and passing the access token and refresh token as parameters. For example:
	<<security-api-saml-logout,SAML logout API>> and passing the access token and refresh token as parameters. For example:

[lcawl]

Suggested change

	using the {ref}/security-api-saml-invalidate.html[SAML invalidate API]
	using the <<security-api-saml-invalidate,SAML invalidate API>>