Skip to main content

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="cn={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="cn" \
    --reuse-values ilum ilum/ilum

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