As a partner, you can upload a ZIP-File containing a medusa configuration XML or YAML directly to Airlock SaaS. There are however certain requirements for such a configuration. These requirements are features that should be supported or certain environment variables that must be used in order to get the IAM working properly. On this page, we describe the different parts of the configuration that must be provided in a certain way.
Important notes
Notice
This functionality requires special permissions which must be requested from Airlock.
Notice
If you migrate from an on-premise Airlock IAM installation, please start with this guide.
Notice
Details about the supported files and structure of the ZIP-File can be found in this guide.
Notice
Details about which policies have to be applied for the Microgateway can be found in this guide.
Notice
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 SaaS. It allows a SaaS administrator to access the tenant IAM Adminapp using an SSO ticket.
The relevant configuration is included in our template medusa-configuration.xml files and must not be changed (or must be copied, if one starts from scratch). This includes JwtTicketEncoderSettings and related settings. The template configuration files can be found in our airlock-iam-configs module in the airlock-saas code repository (check stash mirror).
The encryption key ([FILE]/secrets/sso-encryption-key) is provided by Vault and other related sensitive values are written into sensitive.values , also provided via Vault.
SSO Signing key: sensitive-values/sensitive-values/infrastructure/keys/sso-signing-public-key.pem
SSO 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.
Support SSO & SLO from Airlock Console
To enable single logout as a SaaS admin, the admin app of a tenant requires a session lifetime and session idle time being less than the one of the management platform. This is due to the following limitations:
There is no back-channel logout feature available at this stage
To retrieve all Tenant Admin App Urls, the SaaS admin must have a valid management platform session
Configuration Requirements
Adminapp > Advanced Settings > Session Idle Timeout: 1h (or lower)
Adminapp > Advanced Settings > Session Lifetime: 10h (or lower)
Adjust CORS-Settings
Create the following CORS Settingsand set config variable as MEDUSA_CONFIGURATION_CORS_ALLOWED_HOSTS
and disable Strict CORS Validation
The following environment variables must be used:
MEDUSA_CONFIGURATION_CORS_ALLOWED_HOSTS
<plugin class="com.airlock.iam.common.application.configuration.CorsSettings" uuid="########-####-####-####-############">
<propertyList name="allowedHosts" var="MEDUSA_CONFIGURATION_CORS_ALLOWED_HOSTS"/>
</plugin>
Adjust the login and logout URLs
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_URL
MEDUSA_CONFIGURATION_DYNAMIC_LOGIN_URL_PATTERN
MEDUSA_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.
Use default (auth) Instance Directory
Airlock SaaS uses the default auth instance directory name. If your configuration relies on it, for instance if you use paths that include the instance directory, make sure to use auth.
Add service container with clean-up tasks
Notice
It is recommended to configure a service container with clean-up tasks to prevent accumulation of temporary data.
The service container is a separate module and contain various clean-up tasks. Most commonly, 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 are to be configured, but this depends on the configured authentication flows in the Loginapp. We advise to consult the IAM documentation as well as the info boxes next to each clean up task type for further information on what may be beneficial for your configuration.
Required shared secret
Such that the clean-up tasks in the service container can run, you must configure a Service Container Shared Secret of at least 32 characters and reference it both in the Service Container as well as in the Adminapp. That secret should be configured in the Vault and referenced by `[FILE]/...`
Enable User Activity Log Access
Create User Trail Data Source
Enable Trace-ID Logging
IAM needs to know the correlation-ID's header name. This is done by configuring the Correlation ID Settings .
Open your configuration in the config editor, select the "MAIN SETTINGS":
Click the "Create a new plugin" icon and enter a name for the "Correlation ID Settings":
Click "Create & Edit":
Enter traceparent as the value for "Header Name" and ^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$ as the value for "Validation Pattern".
You're done.
How to test your config
Create the tenant if not exists, upload the ZIP-File, then activate. Access the User Management and create a to the backend application known user there with the necessary roles.
How to add secrets
To provide secret values to IAM, Airlock SaaS uses a Hashicorp Vault. The vault is a secure and central storage that persists infrastructure and platform secrets for us. At runtime, the secrets are fetched by the vault-agent and written to separate files.
Each file contains the secret in plaintext. IAM is then able to consume these secrets by importing them. Therefore, when working with a local IAM, it's necessary to create the relevant secret files at the right location otherwise the configuration is invalid.
Predefined Secrets
The following table documents all secrets and their respective location:
Sendgrid API Key |
The API key of the E-Mail gateway provider |
|
|
Twilio API Key |
The API key of the SMS gateway provider |
|
|
IAM License |
The license of IAM. The location is set via the env variable IAM_LICENSE |
|
|
The sensitive values file |
|
|
|
Database credentials |
The credentials used to access the IAM's database |
|
|
|
SSO related key material |
The symmetric SSO encryption key, the asymmetric SSO signing public key. keystorePassword: (leer lassen) Key password: (gibt es nicht) |
|
|
Custom Secrets
Additional secrets in the Vault can be created and edited by admins as defined here.
Critical Secrets
There are secrets, such as the Tenant IAM database connection, that are provided by Airlock SaaS and that cannot be changed by admins. If you created your configuration using any template by Airlock SaaS, you may need to add some secrets. More precisely, in our templates, there are secret values that must not be used in production. Make sure to update these values, by adding secrets, before using such a configuration:
Loginapp > SecurityConfig > encryptionKey
Loginapp > SecurityConfig > hmacKey
LoginFromNewDeviceStepConfig > key
JwTicketDirectAesEncryptionSettings > encryptionKey
JwTicketHmacSettings > hmacKey
How to add key pairs
Key pairs can be created here.
How Airlock SaaS runs your tenant IAM
Airlock IAM mode
Airlock IAM runs in strict mode
Database (PostgreSQL)
Airlock SaaS provides a PostgreSQL database instance that is used by the tenant IAMs. The relevant database credentials are provided via vault and added to IAM through files. These files must be referenced in medusa-configuration.xml and must hold 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
Out of the box, the medusa_user table is created with a standard set of columns. Nevertheless, it is possible to add custom columns to the medusa_user by requesting it from the SaaS Support team as shown in the following chapter.
State Repository (Redis)
Airlock SaaS provides a Redis database instance that is used as state repository for tenant IAMs.
Productive tenant IAMs must use the Redis state repository. Non-productive 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 assign the appropriate state repository per environment. For example:
<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>Verification
Ensure that Adminapp and Loginapp both use the correct state repository. In the config editor, the state repository is configured in Adminapp > Advanced Settings and Loginapp > Advanced Settings, respectively. In medusa-configuration.xml the plugins can be found in the corresponding modules as stateRepository plugins.
Adding custom context data to the medusa_user
You can request the Airlock SaaS Support team to add custom columns to the medusa_user. In order to do so, the following details need to be communicated in that request:
column name
type
additional details like defaults
Notice
Before the column can be added, the tenant IAM must already be deployed via the Airlock Console. This means you must first perform an initial deployment with a valid IAM Medusa configuration (.zip) that does not use the new columns. After this initial deployment, the Airlock SaaS Support team can add the column. You can then update the Medusa configuration and deploy it in a second deployment via the Airlock Console.
Pitfalls
Problem |
Solution |
Description |
|---|---|---|
Users not editable despite roles |
Check Adminapp User Settings |
Happens typically if you switch from "No Access Control" to any form of access control |
WAF Connection SSL Error |
Check Response Actions. Translate Host Header must be enabled |
Without Translation, the SSL connection will be dropped by the SaaS backend and it will not be visible in the istio-proxy logs. |
WAF Connection SSL Error (mTLS) |
Use |
Without the correct Types and Version, Airlock WAF will display a generic SSL error that is hard to debug. |