[7.x] Return realm name in SAML Authenticate API (#52188) (#52465)

This is useful in cases where the caller of the API needs to know
the name of the realm that consumed the SAML Response and
authenticated the user and this is not self evident (i.e. because
there are many saml realms defined in ES).
Currently, the way to learn the realm name would be to make a
subsequent request to the `_authenticate` API.

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

@@ -50,6 +50,10 @@ clients. See also
   (Required, array) A json array with all the valid SAML Request Ids that the caller of
   the API has for the current user.
 
+`realm`::
+  (Optional, string) The name of the realm that should authenticate the SAML response.
+  Useful in cases where many SAML realms are defined.
+
 [[security-api-saml-authenticate-response-body]]
 ==== {api-response-body-title}
 
@@ -61,6 +65,8 @@ clients. See also
   (integer) The amount of time (in seconds) left until the token expires.
 `refresh_token`::
   (string) The refresh token that was generated by {es}.
+`realm`::
+  (string) The name of the realm that the user was authenticated by.
 
 [[security-api-saml-authenticate-example]]
 ==== {api-examples-title}
@@ -87,7 +93,8 @@ The API returns the following response:
   "access_token" : "46ToAxZVaXVVZTVKOVF5YU04ZFJVUDVSZlV3",
   "username" : "Bearer",
   "expires_in" : 1200,
-  "refresh_token": "mJdXLtmvTUSpoLwMvdBt_w"
+  "refresh_token": "mJdXLtmvTUSpoLwMvdBt_w",
+  "realm": "saml1"
 }
 --------------------------------------------------
 // NOTCONSOLE

x-pack/plugin/core/src/main/java/org/elasticsearch/xpack/core/security/action/saml/SamlAuthenticateResponse.java

@@ -5,6 +5,7 @@
  */
 package org.elasticsearch.xpack.core.security.action.saml;
 
+import org.elasticsearch.Version;
 import org.elasticsearch.action.ActionResponse;
 import org.elasticsearch.common.io.stream.StreamInput;
 import org.elasticsearch.common.io.stream.StreamOutput;
@@ -21,18 +22,23 @@ public final class SamlAuthenticateResponse extends ActionResponse {
     private String principal;
     private String tokenString;
     private String refreshToken;
+    private String realm;
     private TimeValue expiresIn;
 
     public SamlAuthenticateResponse(StreamInput in) throws IOException {
         super(in);
         principal = in.readString();
+        if (in.getVersion().onOrAfter(Version.V_7_7_0)) {
+            realm = in.readString();
+        }
         tokenString = in.readString();
         refreshToken = in.readString();
         expiresIn = in.readTimeValue();
     }
 
-    public SamlAuthenticateResponse(String principal, String tokenString, String refreshToken, TimeValue expiresIn) {
+    public SamlAuthenticateResponse(String principal, String realm, String tokenString, String refreshToken, TimeValue expiresIn) {
         this.principal = principal;
+        this.realm = realm;
         this.tokenString = tokenString;
         this.refreshToken = refreshToken;
         this.expiresIn = expiresIn;
@@ -42,6 +48,10 @@ public final class SamlAuthenticateResponse extends ActionResponse {
         return principal;
     }
 
+    public String getRealm() {
+        return realm;
+    }
+
     public String getTokenString() {
         return tokenString;
     }
@@ -57,6 +67,9 @@ public final class SamlAuthenticateResponse extends ActionResponse {
     @Override
     public void writeTo(StreamOutput out) throws IOException {
         out.writeString(principal);
+        if (out.getVersion().onOrAfter(Version.V_7_7_0)) {
+            out.writeString(realm);
+        }
         out.writeString(tokenString);
         out.writeString(refreshToken);
         out.writeTimeValue(expiresIn);

x-pack/plugin/security/src/main/java/org/elasticsearch/xpack/security/action/saml/TransportSamlAuthenticateAction.java

@@ -68,7 +68,8 @@ public final class TransportSamlAuthenticateAction extends HandledTransportActio
                         tokenMeta, true, ActionListener.wrap(tuple -> {
                             final TimeValue expiresIn = tokenService.getExpirationDelay();
                             listener.onResponse(
-                                    new SamlAuthenticateResponse(authentication.getUser().principal(), tuple.v1(), tuple.v2(), expiresIn));
+                                new SamlAuthenticateResponse(authentication.getUser().principal(),
+                                    authentication.getAuthenticatedBy().getName(), tuple.v1(), tuple.v2(), expiresIn));
                         }, listener::onFailure));
             }, e -> {
                 logger.debug(() -> new ParameterizedMessage("SamlToken [{}] could not be authenticated", saml), e);

x-pack/plugin/security/src/main/java/org/elasticsearch/xpack/security/rest/action/saml/RestSamlAuthenticateAction.java

@@ -98,6 +98,7 @@ public class RestSamlAuthenticateAction extends SamlBaseRestHandler {
                     public RestResponse buildResponse(SamlAuthenticateResponse response, XContentBuilder builder) throws Exception {
                         builder.startObject()
                                 .field("username", response.getPrincipal())
+                                .field("realm", response.getRealm())
                                 .field("access_token", response.getTokenString())
                                 .field("refresh_token", response.getRefreshToken())
                                 .field("expires_in", response.getExpiresIn().seconds())