Configuration snippets

To create a snippet using the Config Editor, use the following steps as a guide:

0. General approach using a base configuration
   Since IAM configurations can become quite complex, we recommended developing the snippet contents in a base configuration. By base configuration, we refer to the configuration (or a typical such configuration) into which the snippet is later imported.

1. Open the base configuration in the Config Editor
2. Remove unconnected plugins
   Make sure there are no unconnected plugins in the base configuration: If there are unconnected plugins, delete them from the base configuration. In the “Unconnected Plugins” view, there is a button (the bin icon) to do this.
3. Configure snippet plugins
   Configure all plugins that should later be part of the snippet.
4. • The added plugins are disconnected from the base config in the following step. It may therefore make sense to add a comment like “TODO: disconnect” for all added plugins so they are easier to find.
   • Use the validation feature of the Config Editor to make sure the resulting configuration is valid.
   • Test the resulting configuration if possible.
5. Disconnect snippet plugins
   Disconnect all plugins that should become part of the snippet. If you marked the plugins with “TODO: disconnect”, use the search function in the Config Editor to find all plugins.
6. Download configuration
   Download the configuration from the Config Editor. For the following steps, the downloaded file is called base-config-with-snippet-plugins.yaml. Open it in a text editor or IDE. Ideally, the editor is YAML-aware and allows you to collapse whole YAML trees.
7. The downloaded file contains all connected plugins from the base configuration plus all snippet plugins in the unconnected part of the configuration.
8. Locate snippet plugins
   Locate the beginning of the list of unconnected plugin trees in the YAML file.
   Since all unconnected plugin trees are located after the top-level IAM modules (Loginapp, Adminapp, Service Container, Transaction Approval, API Policy Service) it is easiest to collapse all YAML trees from the top until you hit the first item that is not a top-level IAM module. This should be a plugin intended for the snippet.
   After collapsing the top-level IAM modules, the configuration should look like this. In the example below, the collapsed trees are marked with an “[...]” at the end of the line. Also, an empty line has been added to the example before the first snippet plugin to make it more clear.
9.  

   Example

   schemaVersion: iam.airlock.com/v1
   type: IamConfig
   
   spec:
   - type: GlobalConfiguration[...] 
   - type: Loginapp[...]
   - type: TransactionApprovalApp[...]
   - type: Server[...]
      
   - type: TheFirstSnippetPluginInTheList
   ...
   - type: TheLastSnippetPluginInTheList 
    
10.  

    Info

    Parent plugins in list of unconnected plugins

    Note that the list of unconnected plugins may also contain “parent plugins” that do not belong to the snippet. This is the case if the inheritance feature is used and a parent plugins is exclusively referred to via the parent link (and not referenced in any other way).

    To find parent plugins, search for “parentRef:” in the non-snippet part of the configuration and check whether the referred-to parent is in the unconnected plugin list.
11. Copy snippet plugins into snippet template
    Select and copy all plugins from the first snippet plugin down to the last line of the configuration file. This is the list of all snippet plugins. The file is referred to as snippet.yaml in the following. Use one of the above snippet templates and paste the copied list of plugin trees into the template. The resulting file - sticking to the above example - then looks like the following example.
12.  

    Example

    schemaVersion: iam.airlock.com/v1
    type: IamSnippet
    metadata:
      iamVersion: '8.4'
    spec:
    - type: TheFirstSnippetPluginInTheList
    ...
    - type: TheLastSnippetPluginInTheList   
13. The snippet file now contains all plugins of the snippet including references within the plugin. However, there may be dangling references that have to be eliminated in the next steps.
14. Identify dangling references
    Dangling references are refs to plugins outside the snippet (in our case they refer to plugins from the base configuration). To find the dangling references, use the config validation CLI. It will output the list of ids of dangling references as in the following example:
15.  

    Example

    iam config validate -f snippet.yaml
    
     
    Error loading configuration: Unable to load the configuration from file: snippet.yaml: 
    Invalid plugin references found: idOfAPlugin-xyz, idOfAnotherPlugin-abc  

16. Alternatively, you can also upload the snippet.yaml to the Config Editor while watching the Config Editor's log file (adminapp-parsable.log). It will also contain the list of dangling references.

17. Eliminate dangling references
    Open the snippet.yaml in a text editor or IDE and search for the dangling references (idOfAPlugin-xyz, idOfAnotherPlugin-abc in the above example).

18. For each dangling reference, one of the following options exist:

    • Remove the dangling reference (delete the ref: xxx): this option is correct if the target of the reference is typically in the base configuration and must not be part of the snippet. For example, the database connection settings are typically not part of the snippet but part of the target configuration file in which the snippet is to be imported.
      After importing the snippet into the target configuration, such references must be established manually or using the CLI command iam config connect. In large snippets, it may be helpful to keep track of the references that need to be re-established when importing the snippet. One way to do this is by using the comment attribute:
    •  

      Example

      ...
       type: Airlock2FARepositoryConfig
      id: airlock2faRepository
      comment: TODO connect property "sqlDataSource" to database connection plugin 
      properties:
        storageEncryptionConfig:
          ...
    • Inline the referenced plugin (copy the plugin from the base configuration to the snippet): this option is correct if the referenced plugin should be part of the snippet. It may be ok to introduce a bit of redundancy to make the snippet more self-contained and therefore reduce the need for connecting plugins after importing the snippet.
19. Remove unnecessary IDs
    Remove unnecessary ids from the snippet: it may make sense to remove all unnecessary ids from the snippet. It makes the snippet more robust to ID collisions. This is especially important for snippets that are designed to be imported into a base configuration multiple times (e.g. a target application template). Although the CLI command iam config import-snippet is capable of resolving ID collisions it may make sense to remove ids that are neither required for internal nor external references to a plugin.
20. Test the snippet
    To test the resulting snippet either use the CLI command iam config import-snippet (possibly followed by iam config connect commands) or upload the snippet in the Config Editor while having the base configuration open. Choose the option “Import snippet into the current config” if asked by the Config Editor).
    Note that importing a snippet into a base configuration does not automatically connect the imported snippets.

Edit a snippet using the Config Editor

0. Open the base configuration in the Config Editor
1. Upload the snippet using the Upload button or drag and drop the snippet file onto the plugin tree on the left.
2. In the dialog, select the option Open snippet.

3. 

4. Click the Load button
5. The snippet is now displayed in the Config Editor. Note that because it is a snippet and another an entire configuration, some features (such as activation) are disabled in the Config Editor.
6. After editing the snippet, use the Download button to store the adapted snippet.

Import a snippet using the Config Editor

0. Open the base configuration in the Config Editor
1. Upload the snippet using the Upload button or drag and drop the snippet file onto the plugin tree on the left.
2. In the dialog, select the option Import snippet into the current configuration.

3. 

4. If loading the snippet fails because of ID collision, enter a suffix in the input field. The ID will be appended to all colliding snippet plugin IDs.
5. If loading the snippet fails because of colliding display names, check Rename display name on conflict.
6. Click the Load button
7. The plugins from the snippet are now part of the base configuration. Note that they are not connected automatically. You need to go through the configuration to connect plugins where needed.