SSO / Azure AD setup

Elastic Stack Elasticsearch
2

The Configuring SAML single-sign-on (SSO) documentation provides some general guidance and terminology to use SAML SSO with the Elastic Stack. The SAML based Single Sign-On with Elasticsearch and Azure Active Directory blog post may also be useful; it's related to configuring SAML SSO with Elastic stack deployed to Azure using the Azure Resource Manager (ARM) template, but most of the information is more general in nature. I think most of the information is still relevant, except that Azure now automatically sets up the role claim so you no longer have to.

For Azure specifically, there are two parts:

  1. Configuring SAML SSO in Azure
  2. Configuring Elastic stack to work with Azure SAML SSO

1. Configuring SAML SSO in Azure

SAML SSO is configured in Azure by creating an Enterprise application in Azure Active Directory.

1(a). Create Enterprise application

An Enterprise application can be created in the Azure Portal by first navigating to Azure Active Directory

image
image1920×1109 186 KB

Choosing Enterprise applications from the AAD blade

image
image1920×1109 118 KB

And then creating a new application using the + New application button. This will bring up a new blade where a new Enterprise application can be added

image
image1920×1109 227 KB

Configure a non-gallery application and give it a name, such as Elasticsearch.

1(b). Configure Enterprise application

To configure the enterprise application for SAML SSO, navigate to it in the AAD blade under Enterprise Applications , and select the Single sign-on navigation item

image
image1920×1109 164 KB

From here, you will have access to the App Federation Metadata Url which contains the metadata needed to configure Elasticsearch.

1(c). Configure Identifier, Reply URL and Logout Url

In the Basic SAML Configuration section within the Single sign-on subsection of the Enterprise application, configure the following

  • Identifier (Entity ID): <Kibana Url and port>
  • Reply URL (Assertion Consumer Service URL): <Kibana Url and port>/api/security/v1/saml
  • Logout Url: <Kibana Url and port>/logout

where

  • <Kibana Url and port> is the URL including the port of the instance of Kibana configured to work with the instance of Elasticsearch.

1(d). Enterprise application manifest and appRoles

We now need to configure the roles that are available in the Enterprise application. These roles will come through in claims on a successful SAML authentication response, and be used to map to Elasticsearch roles.

Within the AAD blade, go to App registrationsand click on the Enterprise application in the list. Go to the Manifest subsection and add JSON objects to the appRoles array for the roles that you wish to be available for the Enterprise application.

For example, you might add a Superuser appRole

{
  "appId": "<guid>",
  "appRoles": [
    {
      "allowedMemberTypes": [
        "User"
      ],
      "displayName": "Superuser",
      "id": "18d14569-c3bd-439b-9a66-3a2aee01d14d",
      "isEnabled": true,
      "description": "Superuser with administrator access",
      "value": "superuser"
    },
    ... other roles
  ],

which appRoles you decide to have is up to you.

1(e). Configure users and groups

We now need to configure which users in Azure AAD have access to the Enterprise application i.e. can use SAML SSO to log in to the Elastic Stack, and what roles they have.

Go to the AAD blade, click on Enterprise applications, click on the Enterprise application in question, then go to the Users and groups subsection. Here you will be able to add users and groups that are configured in AAD to the Enterprise application, giving them roles that you defined in step 1(d).

2. Configuring Elastic stack to work with Azure SAML SSO

Elasticsearch needs to be configured for SAML SSO, using Azure AD as the Identity Provider (IdP). SAML features of the Elastic Stack require at least a Platinum subscription.

2(a). Enable TLS for Elasticsearch HTTP layer

TLS on the HTTP layer is required in order to configure SAML. At a minimum, something like the following is added to elasticsearch configuration (elasticsearch.yml)

xpack.security.http.ssl.enabled: true
xpack.security.http.ssl.keystore.path: "http.p12"

and if you secured the PKCS#12 archive keystore with a password, add that password to a secure setting in Elasticsearch keystore

bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password

2(b). Enable token service

This is automatically enabled when TLS is configured on the HTTP layer.

2(c). Create the SAML realm

A SAML realm needs to be configured for using Azure AD as an IdP. For Elasticsearch 7.x, this looks like

xpack.security.authc.realms.saml.saml_aad:
  order: 2
  idp.metadata.path: "<Azure App Federation Metadata Url>"
  idp.entity_id: "<Azure AD Identifier>"
  sp.entity_id:  "<Kibana Url and port>"
  sp.acs: "<Kibana Url and port>/api/security/v1/saml"
  sp.logout: "<Kibana Url and port>/logout"
  attributes.principal: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
  attributes.groups: "http://schemas.microsoft.com/ws/2008/06/identity/claims/role"
  attributes.name: "http://schemas.microsoft.com/identity/claims/displayname"
  attributes.mail: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"

where

  • <Azure App Federation Metadata Url> is the App Federation Metadata Url copied from the Enterprise application set up in Azure portal. This looks something like https://login.microsoftonline.com/<GUID>/federationmetadata/2007-06/federationmetadata.xml?appid=<GUID>

  • <Azure AD Identifier> is the Azure AD Identifier copied from the Enterprise application set up in Azure portal. This is the same as the entityID element value found within the metadata XML returned from the App Federation Metadata Url, and looks something like https://sts.windows.net/<some GUID>/

  • <Kibana Url and port> is the URL including the port of the instance of Kibana configured to work with the instance of Elasticsearch.

The values assigned to the attributes are claims (referred to as User Attributes and Claims in the Enterprise Application in Azure portal) provided by Azure AD.

2(d). Configure native realm

You probably want to configure the native realm in addition to the SAML realm, to allow you to set up role mappings in Elasticsearch using a built-in user. Role mappings will map claims in a successful SAML authentication response to roles in Elasticsearch. Native realm configuration in Elasticsearch 7.x looks like

xpack.security.authc.realms.native.native1:
  order: 0

2(e). Configure Kibana

Kibana needs to be configured for authentication with the SAML realm. Add the following to Kibana configuration (kibana.yml)

xpack.security.authProviders: [ saml, basic ]
server.xsrf.whitelist: [ /api/security/v1/saml ]
xpack.security.public.protocol: "<Kibana URL protocol>"
xpack.security.public.hostname: "<Kibana URL hostname>"
xpack.security.public.port: "<Kibana URL public port>"

where

  • <Kibana URL protocol> is the protocol used to reach Kibana instance. This is going to be "https"
  • <Kibana URL hostname> is the hostname used to reach Kibana.
  • <Kibana URL public port> is the public port used to reach Kibana. For example, if using https and the default port for HTTPS, this will be 443

2(f). Configure role mappings

Final piece is to configure the roles that users that authenticate through SAML SSO should have in Elasticsearch. This is done by creating role mappings in Elasticsearch that will map claims about a user in the SAML authentication response to roles within Elasticsearch. As an example, we can map users that are assigned the superuser role in the Enterprise application to have the superuser role in Elasticsearch.

In Kibana Dev tools (you'll be able to log in to Kibana using the elastic built-in superuser account using the <Kibana URL>/login endpoint directly, since the native realm is enabled):

PUT /_security/role_mapping/saml-superuser
{
  "roles": [ "superuser" ],
  "enabled": true,
  "rules": {
    "all": [
      { "field": { "realm.name": "saml_aad" } },
      { "field": { "groups": "superuser" } }
    ]
  }
}

I think these are all the steps needed to get you up and running :smiley:

2 Likes