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