Role mapper

Introduction

Role mapper scripts provide a flexible approach to mapping external roles from identity providers to internal EBX® roles as part of the synchronized directory functionality.

To create, modify and publish a role mapper script, use the EBX® Script IDE.

Configuration

Role mapper scripts are configured in the synchronized directory section of ebx.properties :

# Enable synchronized directory
ebx.directory.synchronized.source=LDAP
...

# Set role mapper to use scripts
ebx.directory.synchronized.role.mapper=SCRIPT

Initial script

When a role mapper script is first edited using the EBX® Script IDE, EBX® provides an initial script with the correct definition of the exported function.

An initial role mapper script has the following structure:

<unit usage statement 1>
<unit usage statement 2>
...
<unit usage statement N>

export function mapRoles(userAttributes: unmodifiable dictionary<set<string>>,
                        externalRoles: unmodifiable set<string>): set<profile>
begin
  ...
  <statement 1>
  <statement 2>
  ...
end

The following example is a basic role mapper script:

uses core.set as set;
uses core.profile as profile;

export function mapRoles(userAttributes: unmodifiable dictionary<set<string>>,
                        externalRoles: unmodifiable set<string>): set<profile>
begin
    var result := set.of<profile>();

    // Map external admin role to built-in administrator
    if set.contains(externalRoles, 'admin') then
    begin
        set.add(result, profile.ofAdministrator());
    end

    return result;
end

Function signature

The mapRoles function must have the following signature:

export function mapRoles(userAttributes: unmodifiable dictionary<set<string>>,
                        externalRoles: unmodifiable set<string>): set<profile>

Parameters

• userAttributes : a dictionary containing user attributes from the identity provider. Each key is an attribute name and each value is a set of strings representing the attribute values.

  Example: {'department': {'IT', 'Engineering'}, 'location': {'Paris'}, 'title': {'Senior Developer'}}

• externalRoles : a set of external roles assigned to the user by the identity provider.

  Example: {'admin', 'developer', 'manager'}

Return value

The function must return a set of profile objects representing the internal roles to be assigned to the user.

Note: If the function returns an empty set, no roles will be assigned to the user.

Available functions

The following profile functions are available using the core.profile unit:

• profile.ofAdministrator() : returns the built-in administrator profile.

• profile.ofReadOnly() : returns the built-in read-only profile.

• profile.ofOwner() : returns the built-in owner profile.

• profile.ofEveryone() : returns the built-in everyone profile.

• profile.forSpecificRole(roleName) : returns a specific role profile with the given name.

Examples

Basic role mapping

This example shows how to map external roles directly to internal EBX® profiles.

uses core.set as set;
uses core.profile as profile;

export function mapRoles(userAttributes: unmodifiable dictionary<set < string >>,
externalRoles: unmodifiable set<string>): set<profile>
begin
	var result := set.of<profile>();

	// Map external admin role to built-in administrator
	if set.contains(externalRoles, 'external_admin') then
		set.add(result, profile.ofAdministrator());

	// Map external read role to built-in read-only
	if set.contains(externalRoles, 'external_reader') then
		set.add(result, profile.ofReadOnly());

	return result;
end

Attribute-based role mapping

This example demonstrates how to use user attributes (like department) to determine role assignments.

uses core.dictionary as dict;
uses core.set as set;
uses core.profile as profile;

export function mapRoles(userAttributes: unmodifiable dictionary<set < string >>, externalRoles: unmodifiable set<string>): set<profile>
begin
	var result := set.of<profile>();

	// Get user department from attributes
	var departments := dict.get(userAttributes, 'department');

	if isNull(departments) then
		return result;

	if set.contains(departments, 'IT') then
		set.add(result, profile.ofAdministrator());

	if set.contains(departments, 'HR') then
		set.add(result, profile.forSpecificRole('HR_Manager'));

	return result;
end

Troubleshooting

Script not executing:

• Verify that ebx.directory.synchronized.role.mapper=SCRIPT is set in ebx.properties

• Check that the script is published and active in the EBX® Script IDE

• Review script logs for runtime errors