Document how to use stack config policy to manage authentication

docs/orchestrating-elastic-stack-applications/securing-stack.asciidoc

@@ -14,7 +14,14 @@ You can secure your Elastic Stack by specifying the following settings:
 - <<{p}-rotate-credentials>>
 - <<{p}-saml-authentication>>
 
+You can use Elastic Stack configuration policy to configure the following authentication methods:
+
+- <<{p}-ldap-using-stack-config-policy>>
+- <<{p}-oidc-stack-config-policy>>
+- <<{p}-jwt-stack-config-policy>>
+
 include::security/custom-http-certificate.asciidoc[leveloffset=+1]
 include::security/users-and-roles.asciidoc[leveloffset=+1]
 include::security/rotate-credentials.asciidoc[leveloffset=+1]
 include::security/saml-authentication.asciidoc[leveloffset=+1]
+include::security/auth-configs-using-stack-config-policy.asciidoc[leveloffset=+1]

docs/orchestrating-elastic-stack-applications/security/auth-configs-using-stack-config-policy.asciidoc

@@ -0,0 +1,25 @@
+:page_id: auth-config-using-stack-config-policy
+ifdef::env-github[]
+****
+link:https://www.elastic.co/guide/en/cloud-on-k8s/master/k8s-{page_id}.html[View this document on the Elastic website]
+****
+endif::[]
+[id="{p}-{page_id}"]
+= Managing authentication for multiple stacks using Elastic Stack configuration policy
+
+NOTE: This requires a valid Enterprise license or Enterprise trial license. Check <<{p}-licensing,the license documentation>> for more details about managing licenses.
+
+
+ECK `2.11.0` extends the functionality of <<{p}-stack-config-policy,Elastic Stack configuration policies>> so that it becomes possible to configure Elasticsearch security realms for more than one Elastic stack at once. 
+The authentication will apply to all Elasticsearch clusters and Kibana instances managed by the Elastic Stack configuration policy.
+
+
+Examples for configuring some of the authentication methods can be found below:
+
+** <<{p}-ldap-using-stack-config-policy,LDAP authentication using Elastic Stack configuration policy>>
+** <<{p}-oidc-stack-config-policy,OpenID Connect authentication using Elastic Stack configuration policy>>
+** <<{p}-jwt-stack-config-policy,JWT authentication using Elastic Stack configuration policy>>
+
+include::managing-authentication-for-multiple-stacks/ldap-using-stack-config-policy.asciidoc[leveloffset=+1]
+include::managing-authentication-for-multiple-stacks/oidc-stack-config-policy.asciidoc[leveloffset=+1]
+include::managing-authentication-for-multiple-stacks/jwt-stack-config-policy.asciidoc[leveloffset=+1]

docs/orchestrating-elastic-stack-applications/security/managing-authentication-for-multiple-stacks/jwt-stack-config-policy.asciidoc

@@ -0,0 +1,121 @@
+:parent_page_id: auth-config-using-stack-config-policy
+:page_id: jwt-stack-config-policy
+ifdef::env-github[]
+****
+link:https://www.elastic.co/guide/en/cloud-on-k8s/master/k8s-{parent_page_id}.html#k8s-{page_id}[View this document on the Elastic website]
+****
+endif::[]
+[id="{p}-{page_id}"]
+
+= JWT using Elastic Stack configuration policy
+
+NOTE: This requires a valid Enterprise license or Enterprise trial license. Check <<{p}-licensing,the license documentation>> for more details about managing licenses.
+
+TIP: Make sure you check the complete link:https://www.elastic.co/guide/en/elasticsearch/reference/current/jwt-auth-realm.html[guide to setting up JWT with Elasticsearch].
+
+Configuring JWT with Elastic Stack configuration policy
+
+. Add your JWT realm to the `elasticsearch.yml` file using the `config` field under `elasticsearch` in the Elastic Stack configuration policy
+
++
+[source,yaml,subs="attributes,+macros"]
+----
+elasticsearch:
+    config:
+       xpack.security.authc.realms.jwt.jwt1:
+         order: -98
+         token_type: id_token
+         client_authentication.type: shared_secret
+         allowed_issuer: "https://es.k8s.elastic.co"
+         allowed_audiences: [ "elasticsearch" ]
+         allowed_subjects: ["elastic-user"]
+         allowed_signature_algorithms: [RS512]
+         pkc_jwkset_path: jwks/jwkset.json
+         claims.principal: sub
+----
+
+. Add `shared_secret` that will be used for client authentication to the Elasticsearch keystore. The following steps can be followed to do this.
+
+    .. Create a secret in the operator namespace containing the shared secret
++
+[source,sh]
+----
+kubectl create secret generic shared-secret --from-literal=xpack.security.authc.realms.jwt.jwt1.client_authentication.shared_secret=<sharedsecret>
+----
+    .. Add the secret name to the `secureSettings` field under `elasticsearch` in the Elastic Stack configuration policy
++
+[source,yaml,subs="attributes,+macros"]
+----
+  elasticsearch:
+    secureSettings:
+:   - secretName: shared-secret
+----
+
+. Add an additional volume to the Elasticsearch pods that contain the JSON Web Keys, it should be mounted to the path that is configured for the `xpack.security.authc.realms.jwt.jwt1.pkc_jwkset_path` config. The file path is resolved relative to the Elasticsearch configuration directory. The following steps can be followed to do this.
+
+    .. Create a secret in the operator namespace that has the jwk set
++
+[source,sh]
+----
+kubectl create secret generic jwks-secret --from-file=jwkset.json
+----
+    .. Add the secret name and mountpath to the `secretMounts` field under `elasticsearch` in the Elastic Stack configuration policy
++
+[source,yaml,subs="attributes,+macros"]
+----
+secretMounts:
+    - secretName: jwks-secret
+      mountPath: "/usr/share/elasticsearch/config/jwks"
+----
+
+. You can use the `securityRoleMappings` field under `elasticsearch` in the Elastic Stack configuration policy to define role mappings that determine which roles should be assigned to each user based on their username, groups, or other metadata.
++
+[source,yaml,subs="attributes,+macros"]
+----
+securityRoleMappings:
+      jwt1-user-role:
+        roles: [ "superuser" ]
+        rules:
+          all:
+            - field: { realm.name: "jwt1" }
+            - field: { username: "jwt-user" }
+        enabled: true
+----
+
+The following example demonstrates how an Elastic Stack configuration policy can be used to configure a JWT realm:
+[source,yaml,subs="attributes,+macros"]
+----
+apiVersion: stackconfigpolicy.k8s.elastic.co/v1alpha1
+kind: StackConfigPolicy
+metadata:
+  name: test-stack-config-policy
+spec:
+  resourceSelector:
+    matchLabels:
+      env: my-label
+  elasticsearch:
+    secureSettings:
+    - secretName: shared-secret
+    securityRoleMappings:
+      jwt1-user-role:
+        roles: [ "superuser" ]
+        rules:
+          all:
+            - field: { realm.name: "jwt1" }
+            - field: { username: "jwt-user" }
+        enabled: true
+    config:
+       xpack.security.authc.realms.jwt.jwt1:
+         order: -98
+         token_type: id_token
+         client_authentication.type: shared_secret
+         allowed_issuer: "https://es.k8s.elastic.co"
+         allowed_audiences: [ "elasticsearch" ]
+         allowed_subjects: ["elastic-user"]
+         allowed_signature_algorithms: [RS512]
+         pkc_jwkset_path: jwks/jwkset.json
+         claims.principal: sub
+    secretMounts:
+    - secretName: jwks-secret
+      mountPath: "/usr/share/elasticsearch/config/jwks"
+----

docs/orchestrating-elastic-stack-applications/security/managing-authentication-for-multiple-stacks/ldap-using-stack-config-policy.asciidoc

@@ -0,0 +1,171 @@
+:parent_page_id: auth-config-using-stack-config-policy
+:page_id: ldap-using-stack-config-policy
+ifdef::env-github[]
+****
+link:https://www.elastic.co/guide/en/cloud-on-k8s/master/k8s-{parent_page_id}.html#k8s-{page_id}[View this document on the Elastic website]
+****
+endif::[]
+[id="{p}-{page_id}"]
+= LDAP using Elastic stack configuration policy
+
+NOTE: This requires a valid Enterprise license or Enterprise trial license. Check <<{p}-licensing,the license documentation>> for more details about managing licenses.
+
+TIP: Make sure you check the complete link:https://www.elastic.co/guide/en/elasticsearch/reference/current/ldap-realm.html[guide to setting up LDAP with Elasticsearch].
+
+To configure LDAP using Elastic Stack configuration policy with user search:
+
+. Add a realm configuration to the `config` field under `elasticsearch` in the `xpack.security.authc.realms.ldap` namespace. At a minimum, you must specify the URL and order of the LDAP server and set `user_search.base_dn` to the container DN where the users are searched for. See link:https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#ref-ldap-settings[LDAP realm settings] for all of the options you can set for an LDAP realm.
+For example, the following snippet shows an LDAP realm configured with a user search:
+
++
+[source,yaml,subs="attributes,+macros"]
+----
+elasticsearch:
+  config:
+    xpack.security.authc.realms:
+      ldap:
+        ldap1:
+          order: 0
+          url: "ldap://openldap.default.svc.cluster.local:1389"
+          bind_dn: "cn=admin,dc=example,dc=org"
+          user_search:
+            base_dn: "dc=example,dc=org"
+            filter: "(cn={0})"
+          group_search:
+            base_dn: "dc=example,dc=org"
+          unmapped_groups_as_roles: false
+----
+
+. The password for the `bind_dn` user should be configured by adding the appropriate `secure_bind_password` setting to the Elasticsearch keystore. This can be done using the Elastic Stack configuration policy by following the below steps:
+
+  .. Create a secret that has the `secure_bind_password` in the same namespace as the operator
++
+[source,sh]
+----
+  kubectl create secret generic ldap-secret --from-literal=xpack.security.authc.realms.ldap.ldap1.secure_bind_password=<password>
+----
+
+    .. Add the secret name to the `secureSettings` field under `elasticsearch` in the Elastic Stack configuration policy
++
+[source,yaml,subs="attributes,+macros"]
+----
+  spec:
+    resourceSelector:
+      matchLabels:
+        env: my-label
+    elasticsearch:
+      secureSettings:
+      - secretName: ldap-secret
+----
+
+. Map LDAP groups to roles. In the below example, LDAP users group to `superuser` role. `dn: "cn=users,dc=example,dc=org"` is the LDAP distinguished name (DN) of the users group.
++
+[source,yaml,subs="attributes,+macros"]
+----
+securityRoleMappings:
+  ldap_role:
+    roles: [ "superuser" ]
+    rules:
+      all:
+        - field: { realm.name: "ldap1" }
+        - field: { dn: "cn=users,dc=example,dc=org" }
+    enabled: true
+----
+
+Simple full example Elastic Stack config policy to configure LDAP realm with user search
+
+[source,yaml,subs="attributes,+macros"]
+----
+apiVersion: stackconfigpolicy.k8s.elastic.co/v1alpha1
+kind: StackConfigPolicy
+metadata:
+  name: test-stack-config-policy
+spec:
+  resourceSelector:
+    matchLabels:
+      env: my-label
+  elasticsearch:
+    secureSettings:
+    - secretName: ldap-secret
+  securityRoleMappings:
+    ldap_role:
+      roles: [ "superuser" ]
+      rules:
+        all:
+          - field: { realm.name: "ldap1" }
+          - field: { dn: "cn=users,dc=example,dc=org" }
+      enabled: true
+  config:
+    xpack.security.authc.realms:
+      ldap:
+        ldap1:
+          order: 0
+          url: "ldap://openldap.default.svc.cluster.local:1389"
+          bind_dn: "cn=admin,dc=example,dc=org"
+          user_search:
+            base_dn: "dc=example,dc=org"
+            filter: "(cn={0})"
+          group_search:
+            base_dn: "dc=example,dc=org"
+          unmapped_groups_as_roles: false
+----
+
+To configure an LDAP realm with user DN templates:
+
+Add a realm configuration to `elasticsearch.yml` in the xpack.security.authc.realms.ldap namespace. At a minimum, you must specify the url and order of the LDAP server, and specify at least one template with the user_dn_templates option. See link:https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#ref-ldap-settings[LDAP realm settings]  for all of the options you can set for an ldap realm.
+
+For example, the following snippet shows an LDAP realm configured with user DN templates:
+
+[source,yaml,subs="attributes,+macros"]
+----
+xpack:
+  security:
+    authc:
+      realms:
+        ldap:
+          ldap1:
+            order: 0
+            url: "ldaps://ldap.example.com:636"
+            user_dn_templates:
+              - "cn={0}, ou=users, dc=example, dc=org"
+            group_search:
+              base_dn: "dc=example,dc=org"
+            unmapped_groups_as_roles: false
+----
+
+Example Elastic Stack config policy to configure LDAP realm with user DN templates:
+
+[source,yaml,subs="attributes,+macros"]
+----
+apiVersion: stackconfigpolicy.k8s.elastic.co/v1alpha1
+kind: StackConfigPolicy
+metadata:
+  name: test-stack-config-policy
+spec:
+  resourceSelector:
+    matchLabels:
+      env: my-label
+  elasticsearch:
+  securityRoleMappings:
+    ldap_role:
+      roles: [ "superuser" ]
+      rules:
+        all:
+          - field: { realm.name: "ldap1" }
+          - field: { dn: "*,ou=users,dc=example,dc=org" }
+      enabled: true
+  config:
+    xpack.security.authc.realms:
+      ldap:
+        ldap1:
+          order: 0
+          url: "ldaps://ldap.example.com:636"
+          user_dn_templates:
+            - "cn={0}, ou=users, dc=example, dc=org"
+          group_search:
+            base_dn: "dc=example,dc=org"
+          unmapped_groups_as_roles: false
+----
+
+The `bind_dn` setting is not used in template mode. All LDAP operations run as the authenticating user. So there is no need of setting up any additional secrets to be stored in keystore.
+