Skip to content

Commit 8ea92f1

Browse files
jkakavashowardhuanghua
jkakavas
authored and
howardhuanghua
committed
Document SAML APIs (elastic#45105)
* Document SAML APIs 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: elastic#40352 * typo * fix links * fix more links * [DOCS] Fixes broken link * Add metadata file with shorter names for docs, fix typos and mute tests * [DOCS] Reformats the SAML APIs to match API template * Apply suggestions from code review Co-Authored-By: Lisa Cawley <[email protected]> * Address feedback and add small section on IdP-initiated SSO handling * address feedback * moar feedback * Clarifications and addressing feedback * properly resolve conflicts * address feedback * fix doc links * minor fixes * Fix reference
1 parent 4737eaf commit 8ea92f1

File tree

9 files changed

+657
-3
lines changed

9 files changed

+657
-3
lines changed

‎x-pack/docs/build.gradle

+8
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ project.copyRestSpec.from(xpackResources) {
2929

3030
testClusters.integTest {
3131
extraConfigFile 'op-jwks.json', xpackProject('test:idp-fixture').file("oidc/op-jwks.json")
32+
extraConfigFile 'idp-docs-metadata.xml', xpackProject('test:idp-fixture').file("idp/shibboleth-idp/metadata/idp-docs-metadata.xml")
3233
extraConfigFile 'testClient.crt', xpackProject('plugin:security').file("src/test/resources/org/elasticsearch/xpack/security/action/pki_delegation/testClient.crt")
3334
setting 'xpack.security.enabled', 'true'
3435
setting 'xpack.security.authc.api_key.enabled', 'true'
@@ -52,6 +53,13 @@ testClusters.integTest {
5253
setting 'xpack.security.authc.realms.pki.pki1.order', '3'
5354
setting 'xpack.security.authc.realms.pki.pki1.certificate_authorities', '[ "testClient.crt" ]'
5455
setting 'xpack.security.authc.realms.pki.pki1.delegation.enabled', 'true'
56+
setting 'xpack.security.authc.realms.saml.saml1.order', '4'
57+
setting 'xpack.security.authc.realms.saml.saml1.idp.entity_id', 'https://my-idp.org'
58+
setting 'xpack.security.authc.realms.saml.saml1.idp.metadata.path', 'idp-docs-metadata.xml'
59+
setting 'xpack.security.authc.realms.saml.saml1.sp.entity_id', 'https://kibana.org'
60+
setting 'xpack.security.authc.realms.saml.saml1.sp.acs', 'https://kibana.org/api/security/v1/saml'
61+
setting 'xpack.security.authc.realms.saml.saml1.attributes.principal', 'uid'
62+
setting 'xpack.security.authc.realms.saml.saml1.attributes.name', 'urn:oid:2.5.4.3'
5563
user username: 'test_admin'
5664
}
5765

‎x-pack/docs/en/rest-api/security.asciidoc

+17-1
Original file line numberDiff line numberDiff line change
@@ -83,12 +83,24 @@ native realm:
8383
=== OpenID Connect
8484

8585
You can use the following APIs to authenticate users against an OpenID Connect
86-
authentication realm
86+
authentication realm when using a custom web application other than Kibana
8787

8888
* <<security-api-oidc-prepare-authentication, Prepare an authentication request>>
8989
* <<security-api-oidc-authenticate, Submit an authentication response>>
9090
* <<security-api-oidc-logout, Logout an authenticated user>>
9191

92+
[float]
93+
[[security-saml-apis]]
94+
=== SAML
95+
96+
You can use the following APIs to authenticate users against a SAML authentication
97+
realm when using a custom web application other than Kibana
98+
99+
* <<security-api-saml-prepare-authentication, Prepare an authentication request>>
100+
* <<security-api-saml-authenticate, Submit an authentication response>>
101+
* <<security-api-saml-logout, Logout an authenticated user>>
102+
* <<security-api-saml-invalidate, Submit a logout request from the IdP>>
103+
92104

93105
include::security/authenticate.asciidoc[]
94106
include::security/change-password.asciidoc[]
@@ -119,4 +131,8 @@ include::security/invalidate-tokens.asciidoc[]
119131
include::security/oidc-prepare-authentication-api.asciidoc[]
120132
include::security/oidc-authenticate-api.asciidoc[]
121133
include::security/oidc-logout-api.asciidoc[]
134+
include::security/saml-prepare-authentication-api.asciidoc[]
135+
include::security/saml-authenticate-api.asciidoc[]
136+
include::security/saml-logout-api.asciidoc[]
137+
include::security/saml-invalidate-api.asciidoc[]
122138
include::security/ssl.asciidoc[]

‎x-pack/docs/en/rest-api/security/saml-authenticate-api.asciidoc

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
[role="xpack"]
2+
[[security-api-saml-authenticate]]
3+
=== SAML authenticate API
4+
5+
Submits a SAML `Response` message to {es} for consumption.
6+
7+
NOTE: This API is intended for use by custom web applications other than {kib}.
8+
If you are using {kib}, see the <<saml-guide>>.
9+
10+
[[security-api-saml-authenticate-request]]
11+
==== {api-request-title}
12+
13+
`POST /_security/saml/authenticate`
14+
15+
[[security-api-saml-authenticate-desc]]
16+
==== {api-description-title}
17+
18+
The SAML message that is submitted can be:
19+
20+
* a response to a SAML authentication request that was previously created using the
21+
<<security-api-saml-prepare-authentication, SAML prepare authentication API>>.
22+
* an unsolicited SAML message in the case of an IdP-initiated single sign-on (SSO) flow.
23+
24+
In either cases, the SAML message needs to be a base64 encoded XML document with a root
25+
element of `<Response>`
26+
27+
After successful validation, {es} responds with an
28+
{es} internal access token and refresh token that can be subsequently used for authentication.
29+
This API endpoint essentially exchanges SAML responses that
30+
indicate successful authentication in the IdP for {es} access and refresh tokens,
31+
which can be used for authentication against {es}.
32+
33+
{es} exposes all the necessary SAML related functionality via the SAML APIs.
34+
These APIs are used internally by {kib} in order to provide SAML based
35+
authentication, but can also be used by other, custom web applications or other
36+
clients. See also
37+
<<security-api-saml-prepare-authentication,SAML prepare authentication API>>,
38+
<<security-api-saml-invalidate,SAML invalidate API>> and
39+
<<security-api-saml-logout,SAML logout API>>.
40+
41+
42+
[[security-api-saml-authenticate-request-body]]
43+
==== {api-request-body-title}
44+
45+
`content`::
46+
(Required, string) The SAML response as it was sent by the user's browser, usually a
47+
Base64 encoded XML document.
48+
49+
`ids`::
50+
(Required, array) A json array with all the valid SAML Request Ids that the caller of
51+
the API has for the current user.
52+
53+
[[security-api-saml-authenticate-response-body]]
54+
==== {api-response-body-title}
55+
56+
`access_token`::
57+
(string) The access token that was generated by {es}.
58+
`username`::
59+
(string) The authenticated user's name.
60+
`expires_in`::
61+
(integer) The amount of time (in seconds) left until the token expires.
62+
`refresh_token`::
63+
(string) The refresh token that was generated by {es}.
64+
65+
[[security-api-saml-authenticate-example]]
66+
==== {api-examples-title}
67+
68+
The following example exchanges a SAML Response indicating a successful
69+
authentication at the SAML IdP for an {es} access token and refresh token to be
70+
used in subsequent requests:
71+
72+
[source,console]
73+
--------------------------------------------------
74+
POST /_security/saml/authenticate
75+
{
76+
"content" : "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....",
77+
"ids" : ["4fee3b046395c4e751011e97f8900b5273d56685"]
78+
}
79+
--------------------------------------------------
80+
// TEST[skip:handled in IT]
81+
82+
The API returns the following response:
83+
84+
[source,js]
85+
--------------------------------------------------
86+
{
87+
"access_token" : "46ToAxZVaXVVZTVKOVF5YU04ZFJVUDVSZlV3",
88+
"username" : "Bearer",
89+
"expires_in" : 1200,
90+
"refresh_token": "mJdXLtmvTUSpoLwMvdBt_w"
91+
}
92+
--------------------------------------------------
93+
// NOTCONSOLE

‎x-pack/docs/en/rest-api/security/saml-invalidate-api.asciidoc

+91
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
[role="xpack"]
2+
[[security-api-saml-invalidate]]
3+
=== SAML invalidate API
4+
5+
Submits a SAML LogoutRequest message to {es} for consumption.
6+
7+
NOTE: This API is intended for use by custom web applications other than {kib}.
8+
If you are using {kib}, see the <<saml-guide>>.
9+
10+
[[security-api-saml-invalidate-request]]
11+
==== {api-request-title}
12+
13+
`POST /_security/saml/invalidate`
14+
15+
[[security-api-saml-invalidate-desc]]
16+
==== {api-description-title}
17+
18+
The logout request comes from the SAML IdP during an IdP initiated Single Logout.
19+
The custom web application can use this API to have {es} process the `LogoutRequest`.
20+
After successful validation of the request, {es} invalidates the access token
21+
and refresh token that corresponds to that specific SAML principal and provides
22+
a URL that contains a SAML LogoutResponse message, so that the user can be
23+
redirected back to their IdP.
24+
25+
{es} exposes all the necessary SAML related functionality via the SAML APIs.
26+
These APIs are used internally by {kib} in order to provide SAML based
27+
authentication, but can also be used by other custom web applications or other
28+
clients. See also <<security-api-saml-authenticate,SAML authenticate API>>,
29+
<<security-api-saml-prepare-authentication,SAML prepare authentication API>>,
30+
and <<security-api-saml-logout,SAML logout API>>.
31+
32+
[[security-api-saml-invalidate-request-body]]
33+
==== {api-request-body-title}
34+
35+
`acs`::
36+
(Optional, string) The Assertion Consumer Service URL that matches the one of the SAML
37+
realm in {es} that should be used. You must specify either this parameter or the `realm` parameter.
38+
39+
`queryString`::
40+
(Required, string) The query part of the URL that the user was redirected to by the SAML
41+
IdP to initiate the Single Logout. This query should include a single
42+
parameter named `SAMLRequest` that contains a SAML logout request that is
43+
deflated and Base64 encoded. If the SAML IdP has signed the logout request,
44+
the URL should include two extra parameters named `SigAlg` and `Signature`
45+
that contain the algorithm used for the signature and the signature value itself.
46+
In order for {es} to be able to verify the IdP's signature, the value of the queryString field must be an exact match to the string provided by the browser.
47+
The client application must not attempt to parse or process the string in any way.
48+
49+
`realm`::
50+
(Optional, string) The name of the SAML realm in {es} the configuration. You must specify
51+
either this parameter or the `acs` parameter.
52+
53+
[[security-api-saml-invalidate-response-body]]
54+
==== {api-response-body-title}
55+
56+
`invalidated`::
57+
(integer) The number of tokens that were invalidated as part of this logout.
58+
59+
`realm`::
60+
(string) The realm name of the SAML realm in {es} that authenticated the user.
61+
62+
`redirect`::
63+
(string) A SAML logout response as a parameter so that the user can be
64+
redirected back to the SAML IdP.
65+
66+
67+
[[security-api-saml-invalidate-example]]
68+
==== {api-examples-title}
69+
70+
The following example invalidates all the tokens for realm `saml1` pertaining to
71+
the user that is identified in the SAML Logout Request:
72+
73+
[source,console]
74+
--------------------------------------------------
75+
POST /_security/saml/invalidate
76+
{
77+
"queryString" : "SAMLRequest=nZFda4MwFIb%2FiuS%2BmviRpqFaClKQdbvo2g12M2KMraCJ9cRR9utnW4Wyi13sMie873MeznJ1aWrnS3VQGR0j4mLkKC1NUeljjA77zYyhVbIE0dR%2By7fmaHq7U%2BdegXWGpAZ%2B%2F4pR32luBFTAtWgUcCv56%2Fp5y30X87Yz1khTIycdgpUW9kY7WdsC9zxoXTvMvWuVV98YyMnSGH2SYE5pwALBIr9QKiwDGpW0oGVUznGeMyJZKFkQ4jBf5HnhUymjIhzCAL3KNFihbYx8TBYzzGaY7EnIyZwHzCWMfiDnbRIftkSjJr%2BFu0e9v%2B0EgOquRiiZjKpiVFp6j50T4WXoyNJ%2FEWC9fdqc1t%2F1%2B2F3aUpjzhPiXpqMz1%2FHSn4A&SigAlg=http%3A%2F%2Fwww.w3.org%2F2001%2F04%2Fxmldsig-more%23rsa-sha256&Signature=MsAYz2NFdovMG2mXf6TSpu5vlQQyEJAg%2B4KCwBqJTmrb3yGXKUtIgvjqf88eCAK32v3eN8vupjPC8LglYmke1ZnjK0%2FKxzkvSjTVA7mMQe2AQdKbkyC038zzRq%2FYHcjFDE%2Bz0qISwSHZY2NyLePmwU7SexEXnIz37jKC6NMEhus%3D",
78+
"realm" : "saml1"
79+
}
80+
--------------------------------------------------
81+
// TEST[skip:handled in IT]
82+
83+
[source,js]
84+
--------------------------------------------------
85+
{
86+
"redirect" : "https://my-idp.org/logout/SAMLResponse=....",
87+
"invalidated" : 2,
88+
"realm" : "saml1"
89+
}
90+
--------------------------------------------------
91+
// NOTCONSOLE

‎x-pack/docs/en/rest-api/security/saml-logout-api.asciidoc

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
[role="xpack"]
2+
[[security-api-saml-logout]]
3+
=== SAML logout API
4+
5+
Submits a request to invalidate an access token and refresh token.
6+
7+
NOTE: This API is intended for use by custom web applications other than {kib}.
8+
If you are using {kib}, see the <<saml-guide>>.
9+
10+
[[security-api-saml-logout-request]]
11+
==== {api-request-title}
12+
13+
`POST /_security/saml/logout`
14+
15+
[[security-api-saml-logout-desc]]
16+
==== {api-description-title}
17+
18+
This API invalidates the tokens that were generated for a user by the
19+
<<security-api-saml-authenticate,SAML authenticate API>>.
20+
21+
If the SAML realm in {es} is configured accordingly and the SAML IdP supports
22+
this, the {es} response contains a URL to redirect the user to the IdP
23+
that contains a SAML logout request (starting an SP-initiated SAML Single Logout).
24+
25+
{es} exposes all the necessary SAML related functionality via the SAML APIs.
26+
These APIs are used internally by {kib} in order to provide SAML based
27+
authentication, but can also be used by other custom web applications or other
28+
clients. See also <<security-api-saml-authenticate,SAML authenticate API>>,
29+
<<security-api-saml-prepare-authentication,SAML prepare authentication API>>,
30+
and <<security-api-saml-invalidate,SAML invalidate API>>.
31+
32+
[[security-api-saml-logout-request-body]]
33+
==== {api-request-body-title}
34+
35+
`token`::
36+
(Required, string) The access token that was returned as a response to calling the
37+
<<security-api-saml-authenticate,SAML authenticate API>>. Alternatively, the most
38+
recent token that was received after refreshing the original one by using a
39+
`refresh_token`.
40+
41+
`refresh_token`::
42+
(Optional, string) The refresh token that was returned as a response to calling the
43+
<<security-api-saml-authenticate,SAML authenticate API>>. Alternatively, the
44+
most recent refresh token that was received after refreshing the original access token.
45+
46+
[[security-api-saml-logout-response-body]]
47+
==== {api-response-body-title}
48+
49+
`redirect`::
50+
(string) A URL that contains a SAML logout request as a parameter. The user
51+
can use this URL to be redirected back to the SAML IdP and to initiate Single
52+
Logout.
53+
54+
[[security-api-saml-logout-example]]
55+
==== {api-examples-title}
56+
57+
The following example invalidates the pair of tokens that were generated by
58+
calling the <<security-api-saml-authenticate,SAML authenticate API>>
59+
with a successful SAML response:
60+
61+
[source,console]
62+
--------------------------------------------------
63+
POST /_security/saml/logout
64+
{
65+
"token" : "46ToAxZVaXVVZTVKOVF5YU04ZFJVUDVSZlV3",
66+
"refresh_token" : "mJdXLtmvTUSpoLwMvdBt_w"
67+
}
68+
--------------------------------------------------
69+
// TEST[skip:can't test this without a valid SAML Response]
70+
71+
The API returns the following response:
72+
73+
[source,js]
74+
--------------------------------------------------
75+
{
76+
"redirect" : "https://my-idp.org/logout/SAMLRequest=...."
77+
}
78+
--------------------------------------------------
79+
// NOTCONSOLE

0 commit comments

Comments
 (0)