# System Configuration

Appmixer offers a variety of system configuration options for advanced use cases, allowing you to finely tune the behavior of its underlying workflow and integration engine. To access and set these configuration options, navigate through the [Appmixer Backoffice](https://docs.appmixer.com/appmixer-backoffice) interface to the "System -> System Configuration" page.

Please be aware that certain configuration changes may not take immediate effect without restarting the Appmixer engine. For customers with a Self-Managed Appmixer installation, restarting the engine can be done at your convenience to apply the new settings. For those with a hosted Appmixer tenant, it's advisable to reach out to our support team at <support@appmixer.com>. Our team can provide guidance on how to effectively set these configuration options and assist with any necessary engine restarts to ensure your configurations are applied as intended.

<figure><img src="https://content.gitbook.com/content/gA9J5A1N66u2GrNSZK7X/blobs/YxZEbnzXxxijfuPwxNbx/image.png" alt=""><figcaption></figcaption></figure>

### Configuration options

Below is a list of available configuration options, accompanied by a brief explanation for each and their default values. These defaults are used by Appmixer in instances where no specific value is provided:

<table><thead><tr><th width="227.37507552383653">Key</th><th width="306.7207646830474">Detail</th><th width="116.67578125">Default value</th><th data-type="checkbox">Needs restart</th></tr></thead><tbody><tr><td>API_USER_CREATE_SCOPE</td><td>By default, the POST /user API is open to enable the sign-in feature for everyone. This option can restrict the access to this endpoint. It takes a list of scopes (comma-separated). If the value is not null, then a JWT token has to be used to call this API. Typically, the value is set to <code>admin</code>.</td><td>null</td><td>false</td></tr><tr><td>APP_NAME</td><td>This will for example appear in the head title of a sign-in popup for Api Key services.</td><td>Appmixer</td><td>false</td></tr><tr><td>AUTH_HUB_AUTOMATIC</td><td>If the <em>auth-hub</em> system plugin is on and this value is <em>true,</em> all OAuth requests for unconfigured services will go through the Authentication Hub. It means that if you install Slack, for example, and do not configure the <em>clientId</em> and <em>clientSecret</em> the engine will use the Appmixer Authentication Hub for Slack authorization.</td><td>true</td><td>false</td></tr><tr><td>DEFAULT_USER_VENDOR</td><td>Vendor assigned to newly created users.</td><td><em>No value</em></td><td>false</td></tr><tr><td>AUTH_POPUP_DISPLAY_ERR</td><td>Whether to display <a href="../../building-connectors/authentication#validate-function-object-or-string">validation errors</a> from the authentication modules.</td><td>true</td><td>false</td></tr><tr><td>AUTH_POPUP_TIMEOUT_ERR</td><td>How many seconds before automatically closing the <em>Connecting Account Failed</em> popup window.</td><td>5</td><td>false</td></tr><tr><td>BROKER_MESSAGE_ACK_TIMEOUT</td><td>Timeout for message processing.</td><td>1500000</td><td>false</td></tr><tr><td>COMPONENT_FACTORY_TIMEOUT</td><td>An attempt to create a component will fail after this timeout.</td><td>300000</td><td>false</td></tr><tr><td>COMPONENT_RECEIVE_TIMEOUT</td><td>A message will be retried if the receive() function does not return within this timeout.</td><td>1380000</td><td>false</td></tr><tr><td>LIMIT_FLOW_UPDATE_BYTES</td><td>The max size in bytes of a flow descriptor to be able to be saved.</td><td>2097152</td><td>false</td></tr><tr><td>LIMIT_CC_ARCHIVE_MAX_BYTES</td><td>Maximum size in bytes for custom components.</td><td>10485760</td><td>false</td></tr><tr><td>LIMIT_WEBHOOK_BYTES</td><td>Maximum payload size in bytes for webhook components.</td><td>1048576</td><td>false</td></tr><tr><td>WEBHOOK_REQUEST_TIMEOUT</td><td>Timeout in milliseconds for webhook component requests.</td><td>10000</td><td>false</td></tr><tr><td>LIMIT_COMPONENT_STATIC_CALL_MAX_BYTES</td><td>Maximum size in bytes of the payload for component static calls.</td><td>104857600</td><td>false</td></tr><tr><td>PUBLIC_FILES_PREFIX</td><td><a href="broken-reference">Public files</a> (needed usually for domain verification) can be served from different paths. Path prefixes have to be separated by <code>:</code></td><td><p></p><pre><code>/:/.well-known
</code></pre></td><td>true</td></tr><tr><td>RETRY_BACKOFF</td><td>In case of an error, a message for a Component is rescheduled for another attempt. A back-off strategy is used. This value defines the number of attempts and the number of minutes between them.</td><td><p></p><pre><code>1,5,60,300,720
</code></pre></td><td>true</td></tr><tr><td>DISPATCHER_PREFETCH_COUNT</td><td>The maximum number of Rabbit messages being dispatched at the same time.</td><td>500</td><td>true</td></tr><tr><td>INPUT_QUEUE_PREFETCH_COUNT</td><td>The maximum number of outgoing Rabbit messages waiting for aknowledgement at the time in the Input Queue. Subsequent incoming messages will not be sent until pending messages are aknowledged.</td><td>300</td><td>true</td></tr><tr><td>WEBHOOK_PREFETCH_COUNT</td><td>This is for webhooks from Appmixer to registered URLs. This is the amount of webhook messages that will be processing at a time.</td><td>50</td><td>true</td></tr><tr><td>WEBHOOK_RETRY_COUNT</td><td>Number of times that Appmixer will retry sending a webhook. Applies for all webhooks.</td><td>20</td><td>false</td></tr><tr><td>WEBHOOK_RETRY_INTERVAL</td><td>Initial interval in milliseconds for retries. Subsequent retries will take longer (multiplied by an internal factor).</td><td>30000</td><td>false</td></tr><tr><td>WEBHOOK_RETRY_MAX</td><td>Maximum interval in milliseconds between retries.</td><td>1800000</td><td>false</td></tr><tr><td>WEBHOOK_USER_CREATED</td><td>URL that will be called when new user is created (sign-up).</td><td><em>No value</em></td><td>false</td></tr><tr><td>WEBHOOK_FLOW_COMPONENT_ERROR</td><td>URL that will be called when a running flow encounters an error.</td><td><em>No value</em></td><td>false</td></tr><tr><td>WEBHOOK_FLOW_COMPONENT_ERROR_INCLUDE_QUOTA</td><td>Include quota errors among the errors sent to the registered webhook URL.</td><td>false</td><td>false</td></tr><tr><td>WEBHOOK_FLOW_COMPONENT_ERROR_INCLUDE_RETRY</td><td>Include <em>retry</em> attempts among the errors sent to the registered webhook URL. If <em>false</em>, the error will be sent, when all 30 attempts to process a message fail. If <em>true</em>, every failed attempt will be sent.</td><td>false</td><td>false</td></tr><tr><td>WEBHOOK_FLOW_STOPPED</td><td>URL that will be called when a flow is stopped due to an incompatible module upgrade. </td><td><em>No value</em></td><td>false</td></tr><tr><td>STRICT_COOKIES</td><td>If set to true, the engine will reject any incoming HTTP requests that have cookies that don't comply with the <a href="https://www.rfc-editor.org/rfc/rfc6265">HTTP cookies RFC specification</a>.</td><td>false</td><td>true</td></tr><tr><td>GARBAGE_COLLECTOR_CONTINUITY_SCOPES_TTL</td><td>The maximum time in days before continuity scopes are garbage collected. A continuity scope is a state of a flow including data from the flow runtime needed to continue the flow from a certain component onwards. For example, the Plivo.SendSMSAndWaitForReply sends an SMS and waits for an event (webhook) from Plivo that contains an SMS with a reply. The continuity scope contains all the data needed to continue the flow at a later time (when the webhook from Plivo is received which can take hours to days.</td><td>100</td><td>false</td></tr><tr><td>GC_FILES_ENABLED</td><td>If the Garbage collector for files is enabled.</td><td>true</td><td>true</td></tr><tr><td>GC_FILES_RULES</td><td>Rules for the Gargabge collector.</td><td>See below.</td><td>false</td></tr><tr><td>IDP_CONFIG</td><td>Identity provider configuration. Please see <a href="#configuring-single-sign-on">Configuring Single-Sing-On</a> for more informations.</td><td><em>No value</em></td><td>false</td></tr><tr><td>IDP_ROLES_PATH</td><td>Identity provider configuration. Please see <a href="#configuring-single-sign-on">Configuring Single-Sing-On</a> for more informations.</td><td><em>No value</em></td><td>false</td></tr><tr><td>IDP_DEFAULT_REDIRECT</td><td>Identity provider configuration. Please see <a href="#configuring-single-sign-on">Configuring Single-Sing-On</a> for more informations.</td><td><em>No value</em></td><td>false</td></tr></tbody></table>

GC\_FILES\_RULES

```
 [
    {
        "scope": "user",

        /**
         * The GC will never delete files created in the past TTL (in hours). By default,
         * set to 720 hours. The reason is to prevent the GC from removing files that could be needed by the
         * flows.
         */
        "ttl": 720,   // 30 days

        /**
         * The user will be blocked from saving any files if the limit is reached.
         */
        "hardLimit": 2000000000   // 2 GB
    }
]

You can have different rules for different user scopes:
[
    { "scope": "user:, "ttl": 720, "hardLimit": 2000000000 },
    { "scope": "admin", "ttl":1440, "hardLimit": 90000000000 }
]
```

## Configuring Single Sign-On

Configuring Single Sign-On (SSO) for Appmixer allows your users to authenticate using their existing identity provider. Appmixer supports **OpenID Connect (OIDC)** and **SAML** standards for seamless integration.

**Required Configuration Parameters**

To set up SSO, you'll need to gather the following information from your Identity Provider (IdP):

* **`idp_type`**: This specifies the authentication method. It can be either `oidc` or `saml`.
* **`authorization_url`**: This is the URL where users will be redirected to log in via your IdP.
* **`client_id`**: An identifier for your client application.

**Appmixer-Specific Parameters**

The following parameters are typically not part of a standard IdP configuration and will likely need to be added manually:

* **`domains`**: A list of domains for which you want to enable SSO. Any user with an email address from a domain listed here will be redirected to your IdP's authentication page. For example: `["yourcompany.com", "example.org"]`
* **`role_mapping`**: This object maps roles from your IdP to Appmixer's roles. Appmixer currently supports `admin` and `user` roles. For example, if your IdP uses "administrator" for admins and "member" for users, your mapping might look like: `{"admin": "administrator", "user": "member"}`

**Parameters Based on Authentication Type**

You'll also need additional parameters depending on whether you're using SAML or OIDC:

**SAML**

* **`,certificate`**: The certificate used to sign SAML requests.
* **`reauth_method` :** What method to use to re-authenticate a user when their session expires. Can be either `popup` or `iframe` . While a hidden iframe is the neat way of handling this situation, this method is not allowed by some identity providers, so popup is used instead to ensure wider compatibility. If you are not sure about your provider's policy, you should use `popup` .

**OIDC**

* **`issuer`**: A unique string that identifies your identity provider.
* **`client_secret`**: A secret identifier for your client application.
* **`token_url`**: The URL where Appmixer can obtain a new OIDC token.
* **`metadata_url`**: A publicly accessible URL provided by your IdP that contains essential information for the authentication process.

**Important Considerations**\
\
Most of these parameters will be provided when you download the configuration from your Identity Provider. You'll primarily need to manually add the **`domains`** and **`role_mapping`** fields.

It's crucial that your **`metadata_url`** is publicly accessible. This is generally true for cloud-based identity providers like AWS IAM and Google ID. However, if you're self-hosting your IdP, you might need to adjust your network configuration to ensure its public accessibility. Appmixer does not currently support configuring a proxy to access an IdP; this must be handled via your hosting machine's network settings. If you encounter issues, please contact our support center.\
\
**Configuration Examples**\
\
Once you've gathered all the necessary information, your configuration JSON should resemble one of the following examples:

{% tabs %}
{% tab title="OIDC" %}

```json
{
    "idp_type": "oidc",
    "client_id": "a361cbac-a420-42ca-8f07-fc3520d5c36b",
    "client_secret": "0841fb03-55b8-4b0d-aeb0-330374348c09",
    "issuer": "my-idp",
    "domains": ["client.io"],
    "token_url": "https://idp.example.com/auth/realms/apm/protocol/openid-connect/token",
    "authorization_url": "https://idp.example.com/auth/realms/apm/protocol/openid-connect/auth",
    "metadata_url": "https://idp.example.com/auth/realms/apm/.well-known/openid-configuration",
    "role_mapping": {
        "admin": "adm",
        "user": "usr"
    }
}
```

{% endtab %}

{% tab title="SAML" %}

```json
{
    "idp_type": "saml",
    "client_id": "my-client-id"
    "authorization_url": "https://idp.example.com/auth/realms/apm/protocol/saml",
    "certificate": "MIIClTCCAX0CBgGV0[...]6smvQM7VU=",
    "domains": ["localhost", "client.io"],
    "role_mapping": {
        "admin": "adm",
        "user": "usr"
    }
    "default_redirect": "https://myapp.appmixer.ai/login"
}
```

{% endtab %}
{% endtabs %}

**Applying Your Configuration**

Paste your finalized configuration JSON as a new Appmixer **System Configuration** with the key `IDP_CONFIG`.

<figure><img src="https://content.gitbook.com/content/gA9J5A1N66u2GrNSZK7X/blobs/QTT0ltQPxB4kT1nDHMWE/CleanShot%202025-05-29%20at%2012.48.09.png" alt=""><figcaption></figcaption></figure>

**Additional Parameters**

**`handle_roles`**: Identity Providers (IdPs) may manage either Authentication and Authorization or just Authentication. By default, Appmixer delegates only authentication to the IdP. To allow the IdP to manage authorization as well (importing roles from the IdP), set this variable to `true` . By doing this, the roles in Appmixer will be ignored for all users who sign in through IdP, meaning some users might not be able to sign in if the proper role isn't granted to them. Please check auto\_grant\_user\_role, below.

**`auto_grant_user_role`**: Works in combination with handle\_roles. If this is set to `true` then all users that are allowed to log in will be granted the minimum permissions needed to operate Appmixer. If this is `false` such users will be denied access until they get the appropriate permissions.

**`enforce_sso`**: By default, we do not disable the legacy email access. If you'd rather have users log in exclusively using Single Sign-On, you can do so by setting this variable to `true` .

**`disable_legacy_signup` :** This property is similar to enforce\_sso, but only applies to new users. If set to `true` the option to sign up will be removed, and new users will only be able to access through Single Sign-On, while existing users will retain the ability to sign in with email and password. This is a weaker check than enforce\_sso, so if both are active, this check will be ignored.

**`roles_path`**: (Only required if **`handle_roles`** is `true`) This is the path within your IdP's authentication response where a user's roles can be found. The value varies between Identity Providers. Refer to the table below for common IdPs:

<table><thead><tr><th width="257.2265625">Identity Provider</th><th>Roles Path</th></tr></thead><tbody><tr><td>Keycloak</td><td>realm_access.roles</td></tr><tr><td>Google ID</td><td><del><em>&#x3C;not supported></em></del></td></tr><tr><td>Google Workspace</td><td>depends on configuration</td></tr><tr><td>Amazon IAM</td><td>-</td></tr></tbody></table>

SAML

**`default_redirect`**: This should be the URL of your login page. It's used as a fallback if an authentication error prevents Appmixer from retrieving a valid redirect URL from the identity provider.

**`expects_signed_assertions`** : Whether each single assertion will be signed separately. Defaults to `false` .

### Providers Configuration

#### Google Workspace

This section explains how to set up Single Sign-On using Google Workspace.

1. First, log in to your [Google Admin control panel](https://admin.google.com/)
2. In the menu on the left, select `Apps -> Web and Mobile Apps`\
   ![](https://content.gitbook.com/content/gA9J5A1N66u2GrNSZK7X/blobs/2Y3I337t8ZUJZlCHCVVZ/CleanShot%202025-09-22%20at%2009.53.45@2x.png)
3. Now, in the new tab, select `Add App -> Add Custom SAML app`\
   \
   &#x20;.\
   ![](https://content.gitbook.com/content/gA9J5A1N66u2GrNSZK7X/blobs/5VLvKVgAgtzp7HfvNhxG/CleanShot%202025-09-22%20at%2009.54.45@2x.png)
4. Choose a name for your app and note all the details provided by Google; we will need them later.
5. On step 3 of the procedure, when prompted to provide the service provider details, please follow the screenshot, replacing `<your-tenant-url>` with the actual URL of your application.\
   ![](https://content.gitbook.com/content/gA9J5A1N66u2GrNSZK7X/blobs/CXE9jxPiXn44UL8WZqNV/CleanShot%202025-09-22%20at%2010.00.58@2x.png)
6. Leave everything blank on the last step `Attribute Mapping` for now.
7. Now that our SAML application is ready, we need to enable it for the users in our tenant. You can do it as you would for any other application (like Gmail, Drive, and so on).
8. Finally, let's set up the roles needed to log in to Appmixer.&#x20;
9. Go to `Directory -> Users -> More options -> Manage custom attributes` \
   ![](https://content.gitbook.com/content/gA9J5A1N66u2GrNSZK7X/blobs/Xk1Yu1tEwmFHi5vnBdio/CleanShot%202025-08-12%20at%2012.43.32@2x.png)
10. &#x20;On the next page, select `Add Custom Attribute` on the top right.\
    ![](https://content.gitbook.com/content/gA9J5A1N66u2GrNSZK7X/blobs/5um8ZbqR1K5IcRCfbAgm/CleanShot%202025-08-12%20at%2012.45.00@2x.png)
11. Configure the attribute as shown in the screenshot. You can use any value you want for `Category` and `Description`. You can also change the name of your field.\
    ![](https://content.gitbook.com/content/gA9J5A1N66u2GrNSZK7X/blobs/BMG2YdsUqRCLfKn0jAsD/CleanShot%202025-08-12%20at%2012.35.14@2x.png)
12. Choose a user you want to assign roles to and expand the `Users Informations` tab.\
    ![](https://content.gitbook.com/content/gA9J5A1N66u2GrNSZK7X/blobs/LOQNEWKecGnoPdAiuzOS/CleanShot%202025-08-12%20at%2012.48.11@2x.png)
13. You will find the newly created attribute. If you scroll down, you can write any string here; they will have to match the content of the **`role_mapping`** in your configuration on Appmixer (Step 15).\
    ![](https://content.gitbook.com/content/gA9J5A1N66u2GrNSZK7X/blobs/b3JHlHcErEhF6dM0JCnv/CleanShot%202025-08-12%20at%2012.50.11@2x.png)
14. Now go back to the app we created earlier and edit the attribute mapping to expose the newly created attribute. If you decided to use `Roles` like in the example, you can follow the screenshot in this case too; otherwise, please replace the role in the left drop-down of the screenshot with the one you created before. Keep the value of `App attributes` to `Role` .\
    ![](https://content.gitbook.com/content/gA9J5A1N66u2GrNSZK7X/blobs/RSwSSanKSMs6Z33RTCDu/CleanShot%202025-08-12%20at%2012.38.14@2x.png)
15. When creating the configuration JSON for Appmixer, please use the following format:<br>

    ```json
    {
        "idp_type": "saml",
        "client_id": <ENTITY ID*>
        "authorization_url": <SSO URL>,
        "issuer": "my-idp",
        "certificate": <CERTIFICATE (METADATA)>,
        "domains": [<YOUR EMAIL DOMAIN>],
        "role_mapping": {
            "admin": <AS CONFIGURED ON STEP 13>,
            "user": <AS CONFIGURED ON STEP 13>
        }
        "default_redirect": <YOUR APP LOGIN PAGE>,
        "expects_signed_assertions": false,
        "handle_roles": true,
        "reauth_method": "popup"
    }
    ```

    \ <mark style="color:$warning;">(\*)</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">**\<ENTITY ID>**</mark> <mark style="color:$warning;"></mark><mark style="color:$warning;">is the one provided on point 5 of this guide, not the one shown in the App's metadata. They are called in the same way, and this can cause confusion, but they are completely different values.</mark> <br>
16. Please feel free to choose any value for `enforce_sso` and `disable_legacy_signup` and `auto_grant_user_role` based on your company policies.
17. Minify the JSON and add it to the Appmixer configuration under the name `IDP_CONFIG` .