Migration to realm-based access control

Migrating an existing IAM instance from role-based access control to realm-based access control requires a manual data migration. Automatic migration is not supported.

The following table compares the two access control modes and highlights their main differences. You can use it to decide whether migration to realm-based access control is appropriate for your setup.

Role-based access control

Realm-based access control

Configuration in Config Editor

  • All (admin) role-permission mappings

Configuration in Config Editor

  • Only role-permission mappings for global permissions
  • Configuration of the delegations repository for delegations and roles

Adminapp includes Administrators user interface/feature to manage administrators. This feature is used to assign admin roles to administrators.

Adminapp includes Realm Management functionality to manage realms and roles. This feature is used to list realms and to create realm roles, permissions, and delegations, and to assign the realm roles to users.

In the realm-based access control mode, there is only one database table for all users - this table includes both regular end-users and admin users. Whether a user may also perform admin tasks depends on the roles and delegations assigned to the user. As a consequence, there is no separate Administrators functionality in the Adminapp.

Relevant DB tables

  • medusa_user
  • medusa_admin

Relevant DB tables

  • medusa_user
  • realm_roles
  • delegations

Provides simple realm administration, based on a realm context-data item on admins and users; access is granted with ordinary roles.

Note that this lightweight feature may be deprecated in a future release.

It is not possible to define admin-role-specific settings in order to overwrite certain behavior of administrators with specified roles.

Migration

Step 1: Store current instance configuration

The first step of migrating to Realms mode is to download and store the current configuration of your IAM instance. To do this:

  1. Open the Config Editor.
  2. Click the Download icon in the horizontal menu bar on top of the Config Editor.
    • The current configuration of your IAM instance is downloaded as a configuration file.
  4. Give the configuration file an easy recognizable name. Ensure to have the file at hand; you need it later on.

Step 2: Configure realm-based access control

Configuring the Realms mode for your existing IAM instance includes a number of steps, among them the creation of a superadmin user, selection of realm administration as access controller to the Adminapp, as well as configuration of the delegation storage and the user persistence.

Follow the instructions in Configuration of realm-based access control, from step 2 to and including step 9.

Note: In step 4, you must reload the current instance configuration you just downloaded, not a start configuration! For this, use the Upload icon in the horizontal menu bar on top of the Config Editor.

When you have completed the above steps, you can continue with the manual migration of your admins and users. See the following section.

Step 3: Manually migrate user data

To manually migrate your admins and users to a realms-conform database, perform the following steps.

  1. Check that your database is up-to-date and that the user table <medusa_user> includes the realm column/attribute.
  2. Migrate your current administrators from the administrators database table into the users table <medusa_user>.
  3. In Realms mode, each user must carry a realm. A user without a realm cannot be assigned a delegation and can therefore no longer be managed in the Adminapp.

  4. Use the following SQL statement to put all users into one fixed realm (replace the name used with your desired realm name): 

  5. UPDATE medusa_user SET realm = 'userRealm' WHERE realm IS NULL;

Step 4: Activate Realms mode, perform final check

To enable the settings specified in the previous steps, activate your configuration in the Config Editor. IAM will now switch in Realms mode.

To check whether the realm configuration was successful, perform the steps described in Check realm configuration.

Step 5: Set up your realm administration

After successfully switching your instance into Realms mode, you must set up your realm administration environment.

  1. Bootstrap the Realm Management functionality. For instructions, see Initial bootstrapping.
  2. After bootstrapping, you must re-create your user management permissions as realm roles and delegations:
    • Create realm roles for every previously assigned admin role.
    • Add delegations to cover all the permissions that could not be copied over directly. These are all realm-specific permissions listed in Realm-specific permissions.
    • Assign the realm roles to the respective admin users, that is, the users who should perform the admin tasks.
  4.  
    Notice

    For an example of how to build a realm administration environment, see Use case - Set up a realm administration.