Keycloak

SAML SSO Integration with Keycloak as an identity provider.

This document will guide you through the task of setting up an excellent, open source identity provider (KeyCloak) to work as an external authenticator and authorizer system for your ELK stack. The scenario is the usual:

  • A centralised, large Elasticsearch cluster

  • A Kibana installation

  • We want one, centralised multi tenant Elasticsearch + Kibana

But with some more enterprisy requirements:

  • Users need to be able to change their passwords independently

  • Users need to verify their emails

  • Group managers need to be able to add, remove, block (only) their users.

What is Keycloak

Keycloak is an advanced authentication server that lets user administer their credentials, and speaks many authentication protocols, Including SAML2.0 SSO.

Setup KeyCloak

This tutorial was created using KeyCloak 8.0.1.

  1. Download the standalone version of Keycloak from their official website

  2. Run Keycloak: run bin/standalone.sh or equivalent for your platform.

  3. Navigate to http://localhost:8080 and configure the admin user's credentials don't forget to fill the email address!

  4. Login as admin

  5. Follow the explanation below, or (if your KC version is the same or close enough to this) use the import function to load this configuration file

If you imported the JSON file, you should have a "ror" realm, and a SAML client called "ror" (keep this ID or change the "issuer" setting in kibana.yml) in the "master" realm. Please now select "ror" realm, navigate to "clients", click "ror" client and double check everything matches with your use case, as this guide assumes both Kibana, Elasticsearch and Keycloak are running on "localhost".

Configure Keycloak to work with ROR

First we want to create a new dedicated "ror" realm, so we don't interfere with any other use of this Keycloak installation.

keycloak_screenshot

Then, let's create a SAML client for this realm:

keycloak_screenshot

Then, configure the SAML client according to your Kibana URL, in this example, Kibana responds to "https://localhost:5601/k"

keycloak_screenshot

Now that the client is saved, let's observe the "configure" tab, here we will extract the two logout and login endpoints that we will use for configuring our SAML connector in "kibana.yml".

keycloak_screenshot

Install ReadonlyREST Enterprise for Kibana

Please refer to our documentation on how to obtain and install ReadonlyREST Enterprise for Kibana. Also remember that it relies on the Elasticsearch plugin to be configured as well.

Setup the SAML connector

Provided that you have ReadonlyREST Enterprise installed configured, you can add the following configuration:

kibana.yml

# More on how to enable SSL on the official documentation of Kibana
server.ssl.enabled: true
server.ssl.key: /home/xx/selfsigned_ssl_localhost/localhost.key
server.ssl.certificate: /home/xx/selfsigned_ssl_localhost/localhost.crt
xpack.security.enabled: false
server.basePath: /k # <-- optional, remember to change it in KC
elasticsearch:
hosts: ["https://localhost:9200"] # <-- our Elasticsearch responds to https
ssl.verificationMode: none
username: kibana
password: kibana
readonlyrest_kbn:
logLevel: debug
auth:
# this secret string has to be longer than 256 chars, use environmental variables to fill it in maybe.
signature_key: "9yzBfnLaTYLfGPzyKW9es76RKYhUVgmuv6ZtehaScj5msGpBpa5FWpwk295uJYaaffTFnQC5tsknh2AguVDaTrqCLfM5zCTqdE4UGNL73h28Bg4dPrvTAFQyygQqv4xfgnevBED6VZYdfjXAQLc8J8ywaHQQSmprZqYCWGE6sM3vzNUEWWB3kmGrEKa4sGbXhmXZCvL6NDnEJhXPDJAzu9BMQxn8CzVLqrx6BxDgPYF8gZCxtyxMckXwCaYXrxAGbjkYH69F4wYhuAdHSWgRAQCuWwYmWCA6g39j4VPge5pv962XYvxwJpvn23Y5KvNZ5S5c6crdG4f4gTCXnU36x92fKMQzsQV9K4phcuNvMWkpqVB6xMA5aPzUeHcGytD93dG8D52P5BxsgaJJE6QqDrk3Y2vyLw9ZEbJhPRJxbuBKVCBtVx26Ldd46dq5eyyzmNEyQGLrjQ4qd978VtG8TNT5rkn4ETJQEju5HfCBbjm3urGLFVqxhGVawecT4YM9Rry4EqXWkRJGTFQWQRnweUFbKNbVTC9NxcXEp6K5rSPEy9trb5UYLYhhMJ9fWSBMuenGRjNSJxeurMRCaxPpNppBLFnp8qW5ezfHgCBpEjkSNNzP4uXMZFAXmdUfJ8XQdPTWuYfdHYc5TZWnzrdq9wcfFQRDpDB2zX5Myu96krDt9vA7wNKfYwkSczA6qUQV66jA8nV4Cs38cDAKVBXnxz22ddAVrPv8ajpu7hgBtULMURjvLt94Nc5FDKw79CTTQxffWEj9BJCDCpQnTufmT8xenywwVJvtj49yv2MP2mGECrVDRmcGUAYBKR8G6ZnFAYDVC9UhY46FGWDcyVX3HKwgtHeb45Ww7dsW8JdMnZYctaEU585GZmqTJp2LcAWRcQPH25JewnPX8pjzVpJNcy7avfA2bcU86bfASvQBDUCrhjgRmK2ECR6vzPwTsYKRgFrDqb62FeMdrKgJ9vKs435T5ACN7MNtdRXHQ4fj5pNpUMDW26Wd7tt9bkBTqEGf"
saml_kc: # <--- Our SAML connector name, used in the path configured in KC
buttonName: "KeyCloak SAML SSO"
enabled: true
type: "saml"
issuer: "ror" # <-- called exactly like the SAML client in KC
entryPoint: "http://localhost:8080/auth/realms/ror/protocol/saml" # <-- from KC configuration tab!
kibanaExternalHost: 'localhost:5601'
protocol: "https" # <--- our Kibana responds to HTTPS
usernameParameter: "nameID"
groupsParameter: "Role"
logoutUrl: "http://localhost:8080/auth/realms/ror/protocol/saml" # <-- from KC configuration tab!

Don't forget setting up SAML requires some changes to security settings in readonlyrest.yml (on the elasticsearch side). Security settings can also be changed via the ReadonlyREST Kibana app.

Setup Elasticsearch with ReadonlyREST

Our Elasticsearch needs to be available on https (more detailed info in our documentation), so we modify the elasticsearch.yml

append to elasticsearch.yml

xpack.security.enabled: false
http.type: ssl_netty4 # <-- needed for ROR SSL

Write in readonlyrest.yml

readonlyrest:
ssl:
enable: true
keystore_file: "keystore.jks"
keystore_pass: readonlyrest
key_pass: readonlyrest
prompt_for_basic_auth: false
audit_collector: true
access_control_rules:
- name: "::KIBANA-SRV::"
auth_key: kibana:kibana
verbosity: error
- name: "ReadonlyREST Enterprise instance #1"
kibana_index: ".kibana_sso"
ror_kbn_auth:
name: "kbn1"
ror_kbn:
- name: kbn1
signature_key: "9yzBfnLaTYLfGPzyKW9es76RKYhUVgmuv6ZtehaScj5msGpBpa5FWpwk295uJYaaffTFnQC5tsknh2AguVDaTrqCLfM5zCTqdE4UGNL73h28Bg4dPrvTAFQyygQqv4xfgnevBED6VZYdfjXAQLc8J8ywaHQQSmprZqYCWGE6sM3vzNUEWWB3kmGrEKa4sGbXhmXZCvL6NDnEJhXPDJAzu9BMQxn8CzVLqrx6BxDgPYF8gZCxtyxMckXwCaYXrxAGbjkYH69F4wYhuAdHSWgRAQCuWwYmWCA6g39j4VPge5pv962XYvxwJpvn23Y5KvNZ5S5c6crdG4f4gTCXnU36x92fKMQzsQV9K4phcuNvMWkpqVB6xMA5aPzUeHcGytD93dG8D52P5BxsgaJJE6QqDrk3Y2vyLw9ZEbJhPRJxbuBKVCBtVx26Ldd46dq5eyyzmNEyQGLrjQ4qd978VtG8TNT5rkn4ETJQEju5HfCBbjm3urGLFVqxhGVawecT4YM9Rry4EqXWkRJGTFQWQRnweUFbKNbVTC9NxcXEp6K5rSPEy9trb5UYLYhhMJ9fWSBMuenGRjNSJxeurMRCaxPpNppBLFnp8qW5ezfHgCBpEjkSNNzP4uXMZFAXmdUfJ8XQdPTWuYfdHYc5TZWnzrdq9wcfFQRDpDB2zX5Myu96krDt9vA7wNKfYwkSczA6qUQV66jA8nV4Cs38cDAKVBXnxz22ddAVrPv8ajpu7hgBtULMURjvLt94Nc5FDKw79CTTQxffWEj9BJCDCpQnTufmT8xenywwVJvtj49yv2MP2mGECrVDRmcGUAYBKR8G6ZnFAYDVC9UhY46FGWDcyVX3HKwgtHeb45Ww7dsW8JdMnZYctaEU585GZmqTJp2LcAWRcQPH25JewnPX8pjzVpJNcy7avfA2bcU86bfASvQBDUCrhjgRmK2ECR6vzPwTsYKRgFrDqb62FeMdrKgJ9vKs435T5ACN7MNtdRXHQ4fj5pNpUMDW26Wd7tt9bkBTqEGf"