As a partner, you can upload a ZIP file that contains a medusa-configuration.xml file or medusa-configuration.yaml file directly to Airlock as a Service. Such configurations must meet specific requirements — e.g., supported features and required environment variables — to ensure that the tenant IAM works correctly. This page explains which configuration elements must be provided in a specific way.
Notice
This functionality requires special permissions which must be requested from Airlock.
If you migrate from an on-premise Airlock IAM installation, please start with this guide.
Details about the supported files and structure of the ZIP-File can be found in this guide.
Details about which policies have to be applied for the Microgateway can be found in this guide.
Egress traffic from IAM is limited. Details and how to configure can be found in this guide.
Required configuration on Tenant IAM
Risk
The following configuration is required for end-user management in Airlock as a Service. It enables a SaaS administrator to access the tenant IAM Adminapp using an SSO ticket.
The required configuration is included in the template medusa-configuration.xml files and must not be modified. If you do not use the template as a base, copy this configuration unchanged. This includes JwtTicketEncoderSettings and related settings.
The encryption key ([FILE]/secrets/sso-encryption-key) and other sensitive values (written to sensitive.values) are sourced from Vault.
SSO signing key:
sensitive-values/sensitive-values/infrastructure/keys/sso-signing-public-key.pemSSO encryption key:
sensitive-values/sensitive-values/infrastructure/keys/sso-encryption-key
In summary, use the settings from the configuration template for the module shown below, and do not add any custom values or files.
Supporting SSO and SLO from the Airlock Console
To support single logout (SLO) for SaaS administrators, the tenant IAM Adminapp must use a shorter session lifetime and shorter session idle timeout than the management platform. This is required due to the following limitations:
Back-channel logout is not available.
Retrieving the tenant IAM Adminapp URLs requires an active management platform session.
Configuration Requirements
Adminapp >> Advanced Settings >> Session Idle Timeout: 1h (or lower)
Adminapp >> Advanced Settings >> Session Lifetime: 10h (or lower)
Adjusting CORS-Settings
Create the following CORS Settings:
Set config variable as
MEDUSA_CONFIGURATION_CORS_ALLOWED_HOSTS.Disable Strict CORS Validation:
Notice
The environment-variable–backed placeholder MEDUSA_CONFIGURATION_CORS_ALLOWED_HOSTS must be used:
<plugin class="com.airlock.iam.common.application.configuration.CorsSettings" uuid="########-####-####-####-############">
<propertyList name="allowedHosts" var="MEDUSA_CONFIGURATION_CORS_ALLOWED_HOSTS"/>
</plugin>Adjusting the login and logout URLs
Notice
The following environment variables must be used:
MEDUSA_CONFIGURATION_AFTER_LOGOUT_URL(the config variable can be configured when entering a non-empty, non-default fallback value)MEDUSA_CONFIGURATION_CUSTOM_LOGIN_URLMEDUSA_CONFIGURATION_DYNAMIC_LOGIN_URL_PATTERNMEDUSA_CONFIGURATION_DYNAMIC_LOGOUT_URL_PATTERN
<plugin class="com.airlock.iam.admin.app.application.configuration.Adminapp" uuid="########-####-####-####-############">
...
<property name="afterLogoutUrl" var="MEDUSA_CONFIGURATION_AFTER_LOGOUT_URL"/>
<property name="customLoginUrl" var="MEDUSA_CONFIGURATION_CUSTOM_LOGIN_URL"/>
<property name="allowedLoginUrlPattern" var="MEDUSA_CONFIGURATION_DYNAMIC_LOGIN_URL_PATTERN"/>
<property name="allowedAfterLogoutUrlPattern" var="MEDUSA_CONFIGURATION_DYNAMIC_LOGOUT_URL_PATTERN"/>
</plugin>Microgateway Settings
Use the default Gateway Settings in both the Loginapp as well as the Adminapp.
Using the default auth instance directory
Airlock as a Service uses auth as the instance directory name. If your configuration references the instance directory (e.g., in file paths), use auth.
Adding a service container for cleanup tasks
Notice
To prevent temporary data from accumulating, configure cleanup tasks in the service container.
The service container is a separate module that contains various cleanup tasks. In most cases, configure the Accepted SSO Tickets Clean-up Task, User Tail Log Clean-up Task, OAuth 2.0 Clean-up Task and Remember-Me Token Clean-up Task, depending on the authentication flows configured in the Loginapp. For details, see the Airlock IAM documentation and the information boxes next to each cleanup task type.
Required shared secret
To run cleanup tasks in the service container, configure a Service Container Shared Secret with at least 32 characters and reference it in both the Service Container and the Adminapp. Store the secret in Vault and reference it using [FILE]/...:
Enabling user activity log access
Create a User Trail Data Source plugin:
Enabling trace ID logging
IAM must know the header name used for the correlation ID. Configure this in Correlation ID Settings.
Open your configuration in the IAM Config Editor and select MAIN SETTINGS:
Click
and enter a name for the Correlation ID Settings:
Click Create & Edit.
Enter
traceparentfor Header Name and^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$for Validation Pattern:
Testing your configuration
Create the tenant (if it does not already exist), upload the ZIP file, and activate the configuration.
Open User Management.
Create a user that is known to the back-end application, including the required roles.
Adding secrets
To provide secret values to IAM, Airlock as a Service uses Hashicorp Vault. Vault is the central, secure store for infrastructure and platform secrets. At runtime, a Vault agent retrieves the secrets and writes them to separate files, with each file containing the secret in plaintext. IAM then consumes the secrets by importing these files. Therefore, when working with a local IAM, create the required secret files in the correct locations; otherwise, the configuration is invalid.
Predefined secrets
The following table lists all predefined secrets and their locations:
Secret |
Description |
Location |
Used by |
|---|---|---|---|
SendGrid API Key |
API key for the email gateway provider |
|
|
Twilio credentials |
Credentials for the SMS gateway provider |
|
|
IAM license |
IAM license file (path is configured via environment variable |
|
|
Sensitive values configuration |
Sensitive values properties file (configured via environment variable |
|
|
Database credentials |
Credentials used to access the IAM database |
|
|
|
SSO key material |
Symmetric SSO encryption key and asymmetric SSO signing public key Keystore password: leave empty Key password: not used |
|
|
Custom Secrets
Administrators can create and manage additional Vault secrets as described here.
Critical Secrets
Some secrets (e.g., the tenant IAM database connection) are provided by Airlock as a Service and cannot be changed by administrators. If you create your configuration from an Airlock as a Service template, you may need to add additional secrets. In particular, templates can contain placeholder secret values that must not be used in production. Replace these placeholders by adding the required secrets before using the configuration in production:
Loginapp >> SecurityConfig >> encryptionKey
Loginapp >> SecurityConfig >> hmacKey
LoginFromNewDeviceStepConfig >> key
JwTicketDirectAesEncryptionSettings >> encryptionKey
JwTicketHmacSettings >> hmacKey
Adding key pairs
To create a key pair, follow the instructions in Adding a signed certificate to a key pair.
How Airlock as a Service runs your tenant IAM
Airlock IAM mode
Airlock IAM runs in strict mode.
Database (PostgreSQL)
Airlock as a Service provides a PostgreSQL database instance for tenant IAMs. The database credentials are stored in Vault and provided to IAM as files. Reference these files in medusa-configuration.xml. The files must contain the following values:
<plugin class="com.airlock.iam.core.misc.impl.persistency.db.HikariCpDataSource" id="PostgreSQL Database Connection" uuid="f0d2a309-8eb4-4574-a622-503d6e5f47be">
<property name="driverClass">org.postgresql.Driver</property>
<property name="password">[FILE]sensitive-values/infrastructure/secrets/postgresql-password</property>
<property name="url">[FILE]sensitive-values/infrastructure/secrets/postgresql-url</property>
<property name="user">[FILE]sensitive-values/infrastructure/secrets/postgresql-username</property>
</plugin>Context Data
By default, the medusa_user table is created with a standard set of columns. You can add custom columns to medusa_user by requesting them from Airlock as a Service Support, as described in the next section.
State Repository (Redis)
Airlock as a Service provides a Redis instance that tenant IAMs use as a state repository.
Notice
Production tenant IAMs must use the Redis state repository. Non-production tenant IAMs can use either the Redis state repository or an in-memory state repository.
The required credentials and configuration are provided automatically. Reference them in medusa-configuration.xml as follows:
<plugin class="com.airlock.iam.common.application.configuration.state.Aes128GcmStateEncryptionConfig" uuid="cc2f91eb-297d-4f91-a2e6-c4b01362e315">
<property name="secretKey">[FILE]sensitive-values/infrastructure/secrets/session-store-encryption-key</property>
</plugin>
<plugin class="com.airlock.iam.common.application.configuration.state.ExpertModeRedisStateRepositoryConfig" uuid="f0dc7ad1-1f84-4895-83fe-89a79b1b39fa">
<pluginProperty name="encryption">
<plugin uuidref="cc2f91eb-297d-4f91-a2e6-c4b01362e315"/>
</pluginProperty>
<property name="namespace" var="MEDUSA_CONFIGURATION_SESSION_STORE_NAMESPACE">default</property>
<property name="yamlConfig">[FILE]sensitive-values/infrastructure/secrets/session-store-config</property>
</plugin>Use the envId feature to select the appropriate state repository for each environment, e.g.:
<pluginProperty name="stateRepository" envid="prod">
<plugin uuidref="f0dc7ad1-1f84-4895-83fe-89a79b1b39fa"/>
</pluginProperty>
<pluginProperty name="stateRepository" envid="nonprod">
<plugin uuidref="e94d0e07-0f8d-4fb1-928d-fb385bea5667"/>
</pluginProperty>Notice
To verify the configuration, ensure that both the Adminapp and Loginapp use the correct state repository. In the IAM Config Editor, configure the state repository under Adminapp >> Advanced Settings and Loginapp >> Advanced Settings, respectively. In medusa-configuration.xml, the corresponding plugins are included in the Adminapp and Loginapp modules as stateRepository plugins.
Adding custom context data to medusa_user
You can ask Airlock as a Service Support to add custom columns to medusa_user. Include the following details in your request:
column name
data type
additional details (e.g., default values)
Notice
Before Support can add a column, the tenant IAM must already be deployed via the Airlock Console. First, deploy a valid IAM Medusa configuration ZIP without the new column(s). After this initial deployment, Support can add the column(s). You can then update the medusa-configuration.xml and deploy it in a second deployment via the Airlock Console.
Troubleshooting
Problem |
Solution |
Description |
|---|---|---|
Users are not editable despite correct roles. |
Check the Adminapp user settings. |
This typically happens after switching from No access control to any access-control mode. |
The connection to Airlock Gateway fails with an SSL error. |
Check Response Actions. Ensure Translate Host Header is enabled. |
Without host-header translation, the SaaS back end drops the SSL connection. The drop is not visible in the |
The connection to Airlock Gateway fails with an SSL error (mTLS). |
When generating certificates, set the correct X.509 Extended Key Usage and select the correct certificate type (SSL Client / SSL Server). |
If the certificate type/EKU is incorrect, Airlock Gateway shows a generic SSL error that is hard to debug. |