Authentication

Ilum supports three methods for authenticating a user: internal authentication using static configuration properties, Lightweight Directory Access Protocol (LDAP), and OAuth2 external provider implementing OpenID.

Internal authentication

By default, the application comes with internal authentication enabled. The default user is admin with the password admin, and the role assigned is ADMIN. As a security measure, you must change the default password.

Changing the default password

You can change the default password using a helm upgrade command. For instance:

helm upgrade \
    --set ilum-core.security.internal.users[0].username=admin \
	--set ilum-core.security.internal.users[0].password=newPassword \
	--set ilum-core.security.internal.users[0].roles[0]=ADMIN \
	--reuse-values ilum ilum/ilum

Creating additional user accounts

You can create additional users by using the helm upgrade command and specifying the username, password, and roles:

helm upgrade \
    --set ilum-core.security.internal.users[0].username=admin \
	--set ilum-core.security.internal.users[0].password=adminPassword \
	--set ilum-core.security.internal.users[0].roles[0]=ADMIN \
	--set ilum-core.security.internal.users[1].username=user \
	--set ilum-core.security.internal.users[1].password=userPassword \
	--set ilum-core.security.internal.users[1].roles[0]=USER \
	--reuse-values ilum ilum/ilum

LDAP authentication

LDAP is a protocol for managing and accessing distributed directory information services. It is particularly useful for verifying user credentials in a centralized manner.

To enable LDAP authentication, you need to provide the LDAP server URL, base DN, user DN pattern, etc. Here's an example helm command:

helm upgrade \
	--set ilum-core.security.type="ldap" \
	--set ilum-core.security.ldap.urls[0]="ldap://host:port" \
	--set ilum-core.security.ldap.base="dc=example,dc=ilum,dc=cloud" \
	--set ilum-core.security.ldap.username="cn=admin,dc=example,dc=ilum,dc=cloud" \
	--set ilum-core.security.ldap.password="psswd" \
	--set ilum-core.security.ldap.userSearch.base="ou=people" \
	--set ilum-core.security.ldap.userSearch.filter="uid={0}" \
	--set ilum-core.security.ldap.userSearch.passwordAttr="userPassword" \
	--set ilum-core.security.ldap.groupSearch.base="ou=group" \
	--set ilum-core.security.ldap.groupSearch.filter="member={0}" \
	--set ilum-core.security.ldap.groupSearch.roleAttr="ou" \
	--reuse-values ilum ilum/ilum

Configuring LDAP with SSL (LDAPS)

Securing your LDAP connections with SSL (LDAPS) involves configuring ilum-core to use:

• A trustStore for verifying the LDAP server’s certificate (built from the CA certificate), and
• A keyStore (pre-built) for presenting the client certificate (if mutual TLS is required).

You can control these settings via standard Helm values.

1. Prepare Your TLS Secret

Create a Kubernetes secret (for example, named tls-secret) that holds your required certificate files. In this setup you only need:

• ca.crt – The CA certificate that was used to sign the LDAP server’s certificate.
• keystore.p12 – A pre-built PKCS#12 keystore that contains the client certificate and private key.

Create the secret with a command similar to:

kubectl create secret generic tls-secret \
  --from-file=ca.crt=/path/to/ca.crt \
  --from-file=keystore.p12=/path/to/keystore.p12

---

2. Helm Values Configuration

In your values.yaml, add (or update) the following sections to configure LDAPS:

ilum-core:
   security:
      type: "ldap"
      ldap:
         urls:
            - "ldaps://openldap:636"
         base: "dc=ilum,dc=test"
         passwordEncoder: "adaptive"
         userSearch:
            base: "ou=people"
            filter: "uid={0}"
            passwordAttr: "userPassword"
         groupSearch:
            base: "ou=group"
            filter: "(member={0})"
            roleAttr: "cn"
      trustStore:
         enabled: true
         secretName: "tls-secret"
         caSecretFileName: "ca.crt"
         password: "CHANGEMEPLEASE"
      keyStore:
         enabled: true
         secretName: "tls-secret"
         secretFileName: "keystore.p12"
         password: "CHANGEMEPLEASE"

Key Points:

• ldap.protocol: Set to ldaps so your application connects securely over port 636.
• trustStore: When enabled, an init container will generate a Java trustStore using the CA certificate (from ca.crt).
• keyStore: When enabled, the chart instructs the JVM to use the pre-built keystore (from keystore.p12) as the client certificate store.

---

3. Troubleshooting

If you experience SSL handshake issues—such as errors indicating that the LDAP server certificate does not match the hostname—you may see messages like:

javax.net.ssl.SSLHandshakeException: No name matching openldap found

In this case:

1. Certificate Hostname Mismatch:
   Ensure the LDAP server’s certificate includes the proper Common Name (CN) or Subject Alternative Names (SANs) that match the hostname (e.g., openldap).

2. Disable Endpoint Identification (Testing Only):
   As a temporary troubleshooting measure (not recommended for production), you can disable hostname verification by adding:

   -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true

   to ilum-core JVM options. For example, update your DEFAULT_JAVA_OPTS:

             - name: DEFAULT_JAVA_OPTS
               value: >
                 -Djavax.net.ssl.trustStore=/truststore/truststore.jks
                 -Djavax.net.ssl.trustStorePassword=CHANGEMEPLEASE
                 -Djavax.net.ssl.keyStore=/keystore/keystore.p12
                 -Djavax.net.ssl.keyStorePassword=CHANGEMEPLEASE
                 -Djavax.net.ssl.keyStoreType=PKCS12
                 -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true

   Warning: Disabling endpoint identification reduces the security of SSL and should only be used for troubleshooting.

OAuth2 authentication

OAuth2 external provider allows users to authenticate using identity service providers such as Microsoft Azure, Google Cloud, Amazon AWS, Okta, etc.

It's crucial to highlight that the OAuth2 authentication method in our application is designed to work exclusively with OpenID Connect. OpenID Connect is an identity layer built on top of the OAuth2 protocol, which allows clients to verify the identity of end-users based on the authentication performed by an authorization server.

To enable OAuth2 authentication, you need to provide the issuer URL of your OAuth2 provider and client ID. Here's an example helm command:

helm upgrade \
	--set ilum-core.security.type="oauth2" \
	--set global.security.oauth2.clientId=CLIENT_ID \
	--set global.security.oauth2.issuerUri=ISSUER_URI \
	--reuse-values ilum ilum/ilum

The setup of a proper redirect URLs on the Identity Service Provider's side is essential for the security and functionality of the authentication process. The redirect URL must be the publicly exposed URL of the Ilum application being integrated. This ensures that after authentication, users are correctly redirected back to the application.

Amazon AWS integration

The integration with Amazon AWS OAuth2 authorization can be effectively achieved using the Amazon Cognito service. For proper integration, it is important to set up the user pool federation endpoints accurately using service's REGION and USER_POOL_ID.

Example helm command:

helm upgrade \
	--set ilum-core.security.type="oauth2" \
	--set global.security.oauth2.clientId=CLIENT_ID \
	--set global.security.oauth2.issuerUri=https://cognito-idp.REGION.amazonaws.com/USER_POOL_ID \
	--reuse-values ilum ilum/ilum

Google Cloud integration

Google Cloud OAuth2 integration with Single Page Applications (SPAs) presents a deviation from the typical OAuth2 Authorization Code flow with Proof Key for Code Exchange (PKCE). While the standard PKCE does not require a client secret for SPAs, Google Cloud's implementation does. This requirement is contrary to common security practices for SPAs, where exposing a client secret in client-side code could lead to vulnerabilities.

Thus, the inclusion of a client secret in the configuration is mandatory, even though it ideally shouldn't be exposed in such applications. Given this situation, it's imperative to limit the use of the OAuth Client only to Ilum application where the secret has been exposed. This restriction is crucial for maintaining security. Using this client in a broader context or for multiple applications can significantly increase the risk of unauthorized access and potential security breaches.

Example helm command:

helm upgrade \
	--set ilum-core.security.type="oauth2" \
	--set global.security.oauth2.clientId=CLIENT_ID \
	--set global.security.oauth2.clientSecret=CLIENT_SECRET \
	--set global.security.oauth2.issuerUri=https://accounts.google.com \
	--reuse-values ilum ilum/ilum

Microsoft Azure integration

For integrating with Microsoft Azure using OpenID OAuth2, it's essential to specify the correct JWT token version in the application manifest. Set the accessTokenAcceptedVersion parameter in the app manifest to 2. This change ensures that Azure issues tokens in the desired format. For detailed steps on configuring this parameter in Azure Entra ID, refer to Microsoft's official guide on application manifest configuration.

Incorrectly setting the JWT token version can result in a mismatch between the JWT's iss claim and the issuer obtained from the OpenID Connect Discovery endpoint. This discrepancy will cause API endpoints to respond with HTTP 401 status.

Example helm command:

helm upgrade \
	--set ilum-core.security.type="oauth2" \
	--set global.security.oauth2.clientId=CLIENT_ID \
	--set global.security.oauth2.issuerUri=https://login.microsoftonline.com/TENANT_ID/v2.0 \
	--reuse-values ilum ilum/ilum