Elastic Custom App SAML Starter

Purpose

This app starternstrates how to authenticate users of a custom application against Elasticsearch when using a SAML authentication realm. For example, an in-house application that performs queries against Elasticsearch on behalf of a user to retrieve data, where users would ordinarily log into Kibana via SAML.

It makes use of the POST /_security/saml/prepare and POST /_security/saml/authenticate APIs.

See SAML prepare authentication API and SAML authenticate API for more info.

Design

This app has been built using the Express web application framework, and includes the following pages/actions to starternstrate the approach:

Path	Name	Description
http://localhost:3000/	Home	Displays a "Log in" button when no session is detected. Displays profile data, an Elasticsearch API response and a "Log out" button when a session is detected.
http://localhost:3000/saml/login	SAML login	Uses the Elasticsearch POST /_security/saml/prepare API to prepare a SAML request and then redirects the browser to the redirect URL generated by the API.
http://localhost:3000/saml/callback	SAML callback	Accepts a SAML response, includes it in a call to the Elasticsearch POST /_security/saml/authenticate API and then creates a session using the response (which includes access and refresh tokens) before redirecting to /.
http://localhost:3000/logout	Logout	Destroys the existing session.

Running

1. Configure a new realm in Elasticsearch:

   For example, to use a Microsoft Entra ID Enterprise App with SAML enabled:

   xpack.security.authc.realms.saml:
       custom_app_saml:
           order: 2
           attributes.principal: nameid
           attributes.groups: "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"
           idp.metadata.path: "https://login.microsoftonline.com/3504e4b3-86da-4741-8f28-f6c113ff884d/federationmetadata/2007-06/federationmetadata.xml?appid=5d372d7f-c28d-49c5-9521-112ace78bca0"
           idp.entity_id: "https://sts.windows.net/3504e4b3-86da-4741-8f28-f6c113ff884d/"
           sp.entity_id: "http://localhost:3000/"
           sp.acs: "http://localhost:3000/saml/callback"
           sp.logout: "http://localhost:3000/logout"

   See Create a SAML realm for more information.

2. Configure a new or existing application in your SAML identity provider with the following details:

   Identifier (Entity ID)	Reply URL (Assertion Consumer Service URL)
   http://localhost:3000/	http://localhost:3000/saml/callback

3. Install a recent version of Node (this project was created with v20.11).

4. Run npm i to install dependencies.

5. Create a .env file with the following config:

   ELASTIC_ENDPOINT="" # e.g. Elasticsearch HTTPS endpoint, e.g. https://custom-app-saml-starter.es.eu-west-2.aws.cloud.es.io/
   ELASTIC_PASSWORD=""
   ELASTIC_SAML_REALM="" # Name of the SAML realm created above, e.g. custom_app_saml
   ELASTIC_USERNAME=""

6. Run npm start.

7. Browse to http://localhost:3000

Contributing

Thank you for considering contributing to the Elastic Custom App SAML Starter project! We welcome contributions! See CONTRIBUTING.md.