General

Issue Description Solution

Issue	Description	Solution
Tenant-Id is null in the API calls after login. There is an error in the console that "digest" could not be read in the calcHash method.	After login, the UI does not load any data because the tenant id in the URLs is null. Since BCI Web Core 13 the OIDC library for login relies on the browser’s Web Crypto API which is only available in secure contexts (HTTPS or localhost).	Enable HTTPS.
Slow / failing environment with Oracle database	Performance on environments with an Oracle database may be bad after inserting a lot of data.	Trigger update of statistics, Oracle’s default is just nightly.
Creation of indexes might fail when upgrading MACMA Keycloak	When deploying MACMA Keycloak to an existing environment migrations might be executed. In some occasions, when adding indexes to a table, the migration might fail, if the table has more than 300.000 entries. Since migration runs only ONCE on the first deployment of a new version of MACMA Keycloak, make sure to always check the steps mentioned in the solution.	Make sure to check the logs, if you find a message stating: Following index should be created This message appears ONLY once after the migration has been run, when deploying a new version of MACMA Keycloak. For all subsequent restarts of the service, the migration won’t be run again. If the message appears, run the mentioned SQL-statement manually on the database.
MACMA field length limitations	Not all MACMA fields lengths are documented properly in MACMA APIs. During usage of our API you might struggle with the field length limitations. This might be an issue, when creating resources via `/resourcemgmt-bulk/v1/tenants/{tenantId}/applications/{applicationId}/resources/create-or-update` and having a large name and type. assigning resources to roles via `/resourcemgmt-bulk/v1/tenants/{tenantId}/applications/{applicationId}/roles/create-or-update` and by using a previously defined resource with large name and type and having large role name. Creating users with too large email addresses (⇐76 characters)	Avoid too long names and type definitions for resources. too long names for roles The current implementation uses a combination of those fields to establish uniqueness. Hence, a maximum of 235 characters combined is allowed. Limit email addresses to 76 characters.
MACMA Keycloak does not handle unicode characters properly for some fields.	Unicode characters from languages like Norwegian, Turkish, Chinese, Japanese etc. might not be stored correctly. Currently, known fields are: Application.name	Avoid those special characters.
Encrypted connection not possible (PKIX failure) from MACMA Keycloak e.g. to LDAPS or TLS encrypted database	Though, certificates have been added to MACMA Keycloak image via e.g. volumes, the settings for the truststore are not properly passed to the Java application. This can result in PKIX failures, when the certificate from the callee is evaluated. This may affect all outgoing communications from MACMA Keycloak, which require encrypted communication.	This issue will be fixed in version 1.13.0. In order to fix truststore issue, this adds the following lines into your deployment. For Kubernetes, directly setting the values to proper truststore configuration: `MAX_RAM_PERCENTAGE: "90 -Djavax.net.ssl.trustStore=/etc/ssl/java/cacerts -Djavax.net.ssl.trustStorePass=changeit"` For Docker Compose, taking the values from other defined variables. Docker-Compose resolves them accordingly `MAX_RAM_PERCENTAGE: 90 -Djavax.net.ssl.trustStore=$$JAVA_CACERT_FILE -Djavax.net.ssl.trustStorePass=$$JAVA_CACERT_STORE_PASS`
Ansible script failure: failed to set token expiration. Session/EntityManager closed	First experienced with MACMA 1.13.0-preview-1.	Workaround: save token settings of the affected realm (see logs) once in Keycloak’s Admin UI (or maybe read and put whole realm via API). Typically, it’s the master realm.
Tenant creation may fail	Sporadically, tenant creation may fail when using MSSQL databases.	Retry tenant creation. Other endpoints are not affected, and we are waiting for a fix by Keycloak.
API-Request returns 401/403 with "CSRF-Token has been associated with the request"	If a path is not found, the request is routed to the UI / Webapp, thus CSRF tokens come into play.	Check if the API path in use is really correct.
Creation of multiple contracts in parallel may cause loss of data	When creating contracts in parallel it may happen, that the contracts are not reflected as desired in MACMA, which can lead to loss of data. In this case, the retrieved ACL would not reflect the intended contract(s). This especially can happen, when two contracts are written in parallel having the same consuming tenant and are affecting the same application(s).	To avoid this issue, create contracts between tenants one-by-one to avoid concurrent write operations.
Limited number of groups to be displayed	The maximum number of groups to be displayed within the groups view tree is limited to 100.000.	-
Role registration fails with error due to 409 conflicts.	Prior to MACMA 1.9.0, cleanup of permission storage for role resource access permissions after a resource has been deleted left some orphaned entries, causing issues when the resource is recreated later on.	Manually delete the mentioned "has-role" policies in Keycloak Admin UI in the application’s providing tenant at Client → <the-client> → Authorization → Policies and trigger a redeployment / role registration again.
Permissions of received application role are not shown.	When sharing an application role via contract, no permissions are shown for it in the receiving organisation.	ACL is not affected, everything is set up correctly, just the UI is not working. Will be fixed in 1.13.0.
Registration in Nexeed IAS Portal may fail with timeout.	We experienced that the registration in Nexeed IAS Portal may take longer than the default timeout of 5 seconds. With MACMA 1.13.0 the default timeout is increased to 10 seconds.	To change the default timeout for portal registration define a variable PORTAL_REGISTRATION_TIMEOUT with a value in milliseconds for macma_webapp.
Cookie Manager shows again and again.	On non-HTTPS systems, the cookie banner shows again and again on the login form.	Enable HTTPS, both for security reasons and to make the cookie banner remember the user’s selection. This is due to changes in the Cookie Manager’s configuration: 2.6.0 - 09.12.2020 Introduced `sameSite` and `secure` cookie attributes for "selection cookie". Properties can be configured via `cookieSameSite` and `cookieSecure` Defaults are `sameSite: 'Lax'` and `secure: true` !! This can lead to non-working Cookie Manager on insecure HTTP sites! Check "Configuration" docs for details !!
MACMA does not encrypt all data in transit and rest by default. For encryption of data in transit, we recommend to configure all communication paths to MACMA to be encrypted, for example, using Service Meshes.	When using encryption for data in transit, keep the following facts in mind: Impact of external TLS on users and other services Certificates must be trusted by other services to validate tokens and load ACLs (or ignore validation, which would make them vulnerable to Man in the Middle attacks). Certificates must be trusted by user’s browser for login/logout and MACMA UI (or user must accept certificate, which would make them vulnerable to Man in the Middle attacks). No mixed HTTP / HTTPS planned, hard cut. Impact of not using external TLS for Nexeed IAS proxy Keycloak’s behavior unclear due to dynamic issuer host and protocol resolution influenced by proxy forwarding headers. Only marginal security gains by our TLS encryption depending on network setup, user credentials are still transmitted in plain text to Nexeed IAS.	Requirement while running MACMA with the connected applications on one virtual or physical machine, data in transit and rest can be unencrypted running MACMA on a standalone machine is absolutely not recommended as data in transit will be unencrypted.
Secrets with stars (*) only are not allowed in tenant zero	-	-

Tenant-Id is null in the API calls after login. There is an error in the console that "digest" could not be read in the calcHash method.

After login, the UI does not load any data because the tenant id in the URLs is null. Since BCI Web Core 13 the OIDC library for login relies on the browser’s Web Crypto API which is only available in secure contexts (HTTPS or localhost).

Enable HTTPS.

Slow / failing environment with Oracle database

Performance on environments with an Oracle database may be bad after inserting a lot of data.

Trigger update of statistics, Oracle’s default is just nightly.

Creation of indexes might fail when upgrading MACMA Keycloak

When deploying MACMA Keycloak to an existing environment migrations might be executed. In some occasions, when adding indexes to a table, the migration might fail, if the table has more than 300.000 entries.

Since migration runs only ONCE on the first deployment of a new version of MACMA Keycloak, make sure to always check the steps mentioned in the solution.

Make sure to check the logs, if you find a message stating:

Following index should be created

This message appears ONLY once after the migration has been run, when deploying a new version of MACMA Keycloak. For all subsequent restarts of the service, the migration won’t be run again.

If the message appears, run the mentioned SQL-statement manually on the database.

MACMA field length limitations

Not all MACMA fields lengths are documented properly in MACMA APIs. During usage of our API you might struggle with the field length limitations.

This might be an issue, when

creating resources via /resourcemgmt-bulk/v1/tenants/{tenantId}/applications/{applicationId}/resources/create-or-update and having a large name and type.
assigning resources to roles via /resourcemgmt-bulk/v1/tenants/{tenantId}/applications/{applicationId}/roles/create-or-update and by using a previously defined resource with large name and type and having large role name.
Creating users with too large email addresses (⇐76 characters)

Avoid

too long names and type definitions for resources.
too long names for roles

The current implementation uses a combination of those fields to establish uniqueness. Hence, a maximum of 235 characters combined is allowed.

Limit email addresses to 76 characters.

MACMA Keycloak does not handle unicode characters properly for some fields.

Unicode characters from languages like Norwegian, Turkish, Chinese, Japanese etc. might not be stored correctly. Currently, known fields are:

Application.name

Avoid those special characters.

Encrypted connection not possible (PKIX failure) from MACMA Keycloak e.g. to LDAPS or TLS encrypted database

Though, certificates have been added to MACMA Keycloak image via e.g. volumes, the settings for the truststore are not properly passed to the Java application. This can result in PKIX failures, when the certificate from the callee is evaluated.

This may affect all outgoing communications from MACMA Keycloak, which require encrypted communication.

This issue will be fixed in version 1.13.0. In order to fix truststore issue, this adds the following lines into your deployment.

For Kubernetes, directly setting the values to proper truststore configuration:

MAX_RAM_PERCENTAGE: "90 -Djavax.net.ssl.trustStore=/etc/ssl/java/cacerts -Djavax.net.ssl.trustStorePass=changeit"

For Docker Compose, taking the values from other defined variables. Docker-Compose resolves them accordingly MAX_RAM_PERCENTAGE: 90 -Djavax.net.ssl.trustStore=$$JAVA_CACERT_FILE -Djavax.net.ssl.trustStorePass=$$JAVA_CACERT_STORE_PASS

Ansible script failure: failed to set token expiration.
Session/EntityManager closed

First experienced with MACMA 1.13.0-preview-1.

Workaround: save token settings of the affected realm (see logs) once in Keycloak’s Admin UI (or maybe read and put whole realm via API). Typically, it’s the master realm.

Tenant creation may fail

Sporadically, tenant creation may fail when using MSSQL databases.

Retry tenant creation. Other endpoints are not affected, and we are waiting for a fix by Keycloak.

API-Request returns 401/403 with "CSRF-Token has been associated with the request"

If a path is not found, the request is routed to the UI / Webapp, thus CSRF tokens come into play.

Check if the API path in use is really correct.

Creation of multiple contracts in parallel may cause loss of data

When creating contracts in parallel it may happen, that the contracts are not reflected as desired in MACMA, which can lead to loss of data. In this case, the retrieved ACL would not reflect the intended contract(s).
This especially can happen, when two contracts are written in parallel having

the same consuming tenant and
are affecting the same application(s).

To avoid this issue, create contracts between tenants one-by-one to avoid concurrent write operations.

Limited number of groups to be displayed

The maximum number of groups to be displayed within the groups view tree is limited to 100.000.

Role registration fails with error due to 409 conflicts.

Prior to MACMA 1.9.0, cleanup of permission storage for role resource access permissions after a resource has been deleted left some orphaned entries, causing issues when the resource is recreated later on.

Manually delete the mentioned "has-role" policies in Keycloak Admin UI in the application’s providing tenant at Client → <the-client> → Authorization → Policies and trigger a redeployment / role registration again.

Permissions of received application role are not shown.

When sharing an application role via contract, no permissions are shown for it in the receiving organisation.

ACL is not affected, everything is set up correctly, just the UI is not working. Will be fixed in 1.13.0.

Registration in Nexeed IAS Portal may fail with timeout.

We experienced that the registration in Nexeed IAS Portal may take longer than the default timeout of 5 seconds.
With MACMA 1.13.0 the default timeout is increased to 10 seconds.

To change the default timeout for portal registration define a variable PORTAL_REGISTRATION_TIMEOUT with a value in milliseconds for macma_webapp.

Cookie Manager shows again and again.

On non-HTTPS systems, the cookie banner shows again and again on the login form.

Enable HTTPS, both for security reasons and to make the cookie banner remember the user’s selection.
This is due to changes in the Cookie Manager’s configuration:
2.6.0 - 09.12.2020

Introduced sameSite and secure cookie attributes for "selection cookie". Properties can be configured via cookieSameSite and cookieSecure Defaults are sameSite: 'Lax' and secure: true
!! This can lead to non-working Cookie Manager on insecure HTTP sites! Check "Configuration" docs for details !!

MACMA does not encrypt all data in transit and rest by default. For encryption of data in transit, we recommend to configure all communication paths to MACMA to be encrypted, for example, using Service Meshes.

When using encryption for data in transit, keep the following facts in mind:
Impact of external TLS on users and other services

Certificates must be trusted by other services to validate tokens and load ACLs (or ignore validation, which would make them vulnerable to Man in the Middle attacks).
Certificates must be trusted by user’s browser for login/logout and MACMA UI (or user must accept certificate, which would make them vulnerable to Man in the Middle attacks).
No mixed HTTP / HTTPS planned, hard cut.

Impact of not using external TLS for Nexeed IAS proxy

Keycloak’s behavior unclear due to dynamic issuer host and protocol resolution influenced by proxy forwarding headers.
Only marginal security gains by our TLS encryption depending on network setup, user credentials are still transmitted in plain text to Nexeed IAS.

Requirement

while running MACMA with the connected applications on one virtual or physical machine, data in transit and rest can be unencrypted
running MACMA on a standalone machine is absolutely not recommended as data in transit will be unencrypted.

Secrets with stars (*) only are not allowed in tenant zero