As a partner, you can upload a ZIP file containing an iam-config.yaml file directly to Airlock as a Service. Such configurations must meet specific requirements — e.g., regarding supported features and required environment variables — to ensure that the tenant IAM operates correctly.
Notice
This functionality requires special permissions, which must be requested from Airlock.
If you are migrating from an on-premises Airlock IAM installation, start with this guide.
For details about the supported files and required ZIP file structure, see this guide.
For details about the Microgateway policies that must be configured, see this guide.
Egress traffic from IAM is restricted. For details and configuration instructions, see this guide.
Required tenant IAM configuration for SSO and SLO integration with the Airlock Console
Warning
The following configuration is required for user management in Airlock as a Service. It enables SaaS administrators to access the tenant IAM Adminapp through an SSO ticket and perform administrative actions.
SSO ticket authentication
The required configuration is included in the template iam-config.yaml files and must not be modified. If you do not use a template as the basis for your configuration, copy these settings unchanged. This includes JwtTicketEncoderSettings and all related settings.
The encryption key ([FILE]/secrets/sso-encryption-key) and other sensitive values stored in sensitive.values are provided through 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
Use the settings from the configuration template for the module shown below. Do not add custom values or custom files:
Session timeouts
To support single logout (SLO) for SaaS administrators, the tenant IAM Adminapp must use shorter session lifetimes and idle timeouts than the Airlock Console. Otherwise, users may remain authenticated in the Adminapp after their management platform session has ended.
This requirement exists because of the following limitations:
Back-channel logout is not available.
Access to the tenant IAM Adminapp requires an active management platform session.
Required configuration
Adminapp >> Advanced Settings >> Session Idle Timeout: 30m (or lower)
Adminapp >> Advanced Settings >> Session Lifetime: 4h (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>
AL_TM_#### roles in tenant IAM
Notice
If certain access shall be prohibited despite a SaaS Admin owning a matching role, leave the corresponding Role-based Access Control field blank.
However, note that "List Users" must match `AL_TM_USERS_LIST` as otherwise the Tenant IAM Adminapp cannot be accessed through SSO by a SaaS Admin.
Usernames should not contain personally identifiable information
Notice
The username is recorded in various logs, including HTTP access logs, proxy logs, and audit logs. Therefore, the username should not contain personally identifiable information (PII).
Recommendation
Use a Universally Unique Identifier (UUID) as the username and store user-friendly identifiers, such as email addresses or account names, in separate attributes.
During self-registration, a UUID can be generated using the Universally Unique Identifier (UUID) Generator:Within the Adminapp, configure the User Identity Generator to Universally Unique Identifier (UUID) Generator:
Also ensure that no role is assigned to Edit username in the Role-Based Access Control configuration.
To support authentication with identifiers other than the UUID stored in the username field, Airlock IAM supports aliases based on any Context Data Column of your choice:Also ensure that Mandatory Transformation is checked.
To display the context data field in the user list, add it to Columns in User List in the Users Configuration plugin:You may also want to adjust the Username Search Field to
email and Default Sort Column to email.
Since this context data field is required when creating a user — both during self-registration and in the Adminapp — configure it as non-optional:
Microgateway Settings
Use the default Microgateway 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:
Trace-ID logging is enabled.
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 iam-config.yaml. 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 iam-config.yaml 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 iam-config.yaml, 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 iam-config.yaml 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. |