User Management Extension in the IAM Adminapp

With user management extensions (UMEs), the user and token management UI in the IAM Adminapp can be extended JavaScript (JS) code. It allows adding a custom tab to the user detail page that can be filled with custom content and, e.g., interact with a custom REST API.

This article explains how to configure and develop UMEs in the IAM Adminapp.

Introduction

The following screenshot shows a very simple “Hello World” user management extension (UME) on the user detail page of user jdoe.

User management extensions (UMEs) are displayed as separate tabs on the user detail screen and can be used to implement custom management features on users and users' tokens.

UMEs are designed to do the following:

  • Provide a custom UI for user-centric data.
  • Call existing IAM REST APIs.
  • Call REST APIs from a Generic Token Controller (e.g., for custom authentication tokens)
  • Call custom REST endpoints from custom REST extensions or external systems.
 
Info

Generic Token Controllers are an alternative but less flexible way of implementing custom user management features.

Creating and configuring a UME

 
Info

For detailed step-by-step instructions, please refer to the Hello World Example.

Creating and configuring a UME involves the following steps:

  1. Create the actual UME JavaScript code (see below and linked examples) and register it using a unique UME ID.
  2. Save the UME JavaScript code in a file named user-management-extensions.js and store it in the IAM instance's Adminapp layout folder.
    The Adminapp layout folder is defined in the instance.properties file by property iam.adminapp.layout.dirs and defaults to instances/<instance-name>/adminapp-layout/.
  3. Add the required translations for text elements to instances/<instance-name>/adminapp-texts/string_xx.properties.
  4. List the UME ID in the IAM configuration: Adminapp >> Users >> User Management Extensions.
  5. Adapt access control settings in Adminapp >> Access Control >> Display User Management Extensions so entitled admin users can see the UME.

Writing the UME JavaScript

UMEs are written in JavaScript and reside in the file adminapp-layout/user-management-extensions.js (relative to the folder of the affected IAM instance). The file may contain several UMEs.

A UME consists of two parts:

  • The UME's class definition.
  • A method-call registering the UME class in the Adminapp.
 
Example

The following code shows the structure of a UME and explains the meaning of the UME's lifecycle methods to be implemented. Note that you don't need to implement all methods.

/* User management extensions must extend the UserManagementExtension class. */
class MyUME extends UserManagementExtension {

    shouldShow() {
        // defines whether the UME should be displayed or not
        // may return a boolean or a Promise resolving to a boolean
        // if not defined, the UME is always displayed
    }

    onInit() {
        // Called when the user is displayed and shouldShow() returns true
        // Can be used, e.g., to preload data.
        // The caller does not wait for the result. If preloading data, make sure the data is present before accessing it
        // (e.g. using Promises).
    }

    onUserLoaded() {
        // Is called when the user is loaded initially or reloaded.
    }

    render(node) {
        // Called to render the contents of the UME
        // Called once and if the language of the Adminapp is changed.
        // The node passed to the function is the root node of the UME.
        // A UME may only interact with the node and its children. 
    }

    onSelect() {
        // Called every time the admin switches to the UME tab.
    } 
} 

iam.api.userManagementExtension.register("myUME", new MyUME());

The following methods from the IAM API are available in UMEs:

  • iam.api.userManagementExtension.register(ID, UME Class): used to register a UME in the Adminapp (see example above).
  • iam.api.userManagementExtension.userId(): returns the ID of the selected user.
  • iam.api.userManagementExtension.adminId(): return the ID of the logged-in administrator.
  • iam.api.userManagementExtension.adminRoles(): returns the array of roles of the logged-in administrator.
  • iam.api.userManagementExtension.reloadUser(): can be called to reload the user (e.g. after modifying user data via a REST call).
  • iam.api.translate(key, attributes): used to translate text elements.
  •  
    Info

    Have a look at the Send Message Example.

API usage and limitations

Consider the following when developing UMEs:

  • Only the mentioned JS API functions from IAM may be used. Calls to other IAM-specific JS functions may change at any time.
  • None of IAM's CSS classes may be used. They are considered implementation details of Airlock IAM that may change at any time. If the UME defines CSS classes, they must be prefixed with ume-<ume-id>-. To prevent IAM styles from leaking into the application, we recommend encapsulating the user management extension in a Web Component.
  • The UME must not manipulate or interact with any DOM Elements, except the UME's root and its children.
  • Keep in mind, that REST requests are executed in the scope of the Adminapp's session. This also implies that calls to protected API endpoints can be made with the session cookie of the logged-in Adminapp user.
 
Risk

User management extensions bear risks. They allow using the full power of JavaScript combined with the possibility of executing any Adminapp REST call with the privileges of the logged-in admin user.

Consider the following when implementing UMEs:

  • REST requests can be made with the session cookie of the logged-in Adminapp user.
  • Consider security implications carefully if changes to the CSP are necessary to call, for example, 3rd party scripts.
  • Do not implement access control just in the UME: the UME code is running in the browser and can therefore be manipulated. Access control has to be implemented on the server side. For example, do not use the method shouldShow() to implement access control.
  • The access control settings in Adminapp >> Access Control >> Display User Management Extensions (fine-grained) only determines whether a UME is displayed to the admin or not. It does not implement server-side REST API access control. Without additional proper server-side access control, an admin user may not see the UME but may possibly still call the REST endpoints.