3.5.8 User Attribute Retrieval and Transformation

User Attribute Retrieval and Transformation helps you to perform the following activities:

User Attribute Retrieval and Transformation introduces the following configuration settings in Identity Server:

To perform complex user attribute transformations, you must have a basic understanding of JavaScript. To see sample JavaScripts with examples, see Sample JavaScripts with Examples.

The following are the limitations of the User Attribute Retrieval and Transformation feature:

You can create, edit, or delete a data source.

This section discusses the following topics:

You can create, edit, or delete an attribute source.

This section discusses the following topics:

You can create, edit, or delete a virtual attribute.

This section discusses the following topics:

This section provides examples that helps in understanding the following:

{
   "users": [
       {"id":"cn= user1,cn=system,cn=userapplication,cn=app1,ou=example,o=com"}
   ]
}

{
  "students": [
    {
      "name": "xyz",
      "id": 1234,
      "subjects": [
        "English", "French"
      ],
      "department": "dept1",
      "branch": "IND"
    },

    {
      "name": "abc",
      "id": 124,
      "subjects": [
        "French"
      ],
      "department": "dept2",
      "branch": "IND"
    },

     { "name": "pqr",
      "id": 223,
      "subjects": [
        "Spanish"    
    ],
      "department": "Dept1",
      "branch": "IND"
    }]
}

The following section provides sample JavaScripts with examples. These are used in the Virtual Attributes section.

Use Case 1:

Consider a scenario where a service provider wants to append PID with an attribute partnerId. For example: PID: P1.

To achieve this, fetch a user’s partnerId by using their existing “givenName” LDAP attribute (available from the logged in user store) from the external LDAP repository. Now, and add a string “PID:” to it. Later, send the value in web servers through the Identity injection policy.

Creating a Data Source:

Creating an Attribute Source:

Creating a Virtual Attribute:

Use Case 2:

Consider a scenario where, if the authenticated user is a manager and has administrator rights to a protected human resource application, then, when he accesses this application, his roles must be passed to the application.

In this scenario, the manager has a local LDAP attribute isManager and has roles of a recruiter and an employee. He also has a local LDAP attribute groupmembership, which contains the string "admins" (for example: adminsRecruitmentDep, adminsPoliciesDep ).

Create a virtual attribute: App1Admin.

In Step1: Provide input parameters, select the following input parameters:

Use the following code in the Step 2: Provide a modification function > Advanced Javascript:

function main(P1, P2, P3){
     if(P1 == 'true' && (/admins/i.test(P2) == true)){
       return P3;
     }else{
       return 'NA';
     }  
}

To test the JavaScript, click the + and add multiple test values. Specify the following test values:

Output: The output is a multi-valued virtual attribute recruiter,employee.

Explanation: In the function, /admins/i.test(P2) == true, /admins/i is a regular expression and test is a JavaScript in-built function. This function tests the regular expression in the string passed as the input parameter. The function returns true if the string contains the required pattern.

Use Case 3:

Consider a scenario where, an Access Manager user wants to access Amazon Web Services (AWS). AWS has multiple roles and each AWS role can have various access rights or policies assigned to it. Based on the level of access, you can access authorized Amazon services. This information about roles must be passed dynamically by Access Manager to AWS to provide single sign-on to the Access Manager user.

For more information about AWS configuration, see Section 5.2.12, Integrating Amazon Web Services with Access Manager.

In this scenario, you have a constant value created using <Role ARN, Trusted SAML Provider ARN> mapped to Remote AWS attribute Role (this value is the AWS format).

Let suppose you have configured the following roles in AWS: admin, finance. The role ARNs are:

For admin role, pass the following: arn:aws:iam::638116851885:role/admin,arn:aws:iam::638116851885:saml-provider/NAMIDP

For finance role, pass the following: arn:aws:iam::638116851885:role/finance,arn:aws:iam::638116851885:saml-provider/NAMIDP

In this example, to dynamically generate the AWS role, use the LDAP attribute Department Name in the user store. For the admin user, the department name is admin. For the finance user, the department name is finance. To make department name available as an LDAP attribute, ensure that you enable personal profile. Click Identity Servers > Edit > Liberty > Web Service Provider.

Solution:

Create a virtual attribute with the following information:

When the user logs in, the department name (finance) is fetched for the respective user and appended with the constant value of the role ARN. This value is then concatenated with the trusted SAML provider ARN in the following format: arn:aws:iam::638116851885:role/admin,arn:aws:iam::638116851885:saml-provider/NAMIDP

Map this virtual attribute with the AWS Remote Attribute role.

In Step1: Provide input parameters, select P1 parameter value as Department Name (Personal Profile).

Use the following code in the Step 2: Provide a modification function > Advanced Javascript:

function main(P1){
   var role_arn='arn:aws:iam::638116851885:role/'
   var provider_arn=',arn:aws:iam::638116851885:saml-provider/MyIDP_184-142';
   var aws_role;
   aws_role = role_arn+P1+provider_arn;
   return aws_role;
}

To test the JavaScript, click the + and add multiple test values. Specify the test value of P1: finance.

Output: arn:aws:iam::638116851885:role/finance,arn:aws:iam::638116851885:saml-provider/NAMIDP.

Use Case 4:

Consider a scenario where, for a service provider - cloudsp, you want to send the groups associated with the user to the service provider. However, you only want to send the groups relevant to that service, and not the complete group DN. Check for a function that checks if the group cn starts with “cloudsp”. If available, send it to the group cn.

In this scenario, the cn of the groups relevant to cloudsp start with “cloudsp” ( for example: "cn=cloudspa,ou=group,o=mycompany") So, when a cloudsp user authenticates at the Identity provider, you need to extract all the cn values from the local LDAP attribute groupMembership and filter only those names starting with cloudsp and send it in assertion to cloudsp.

Solution:

In Step1: Provide input parameters, select P1 as an attribute which has the groups.

Use the following code in the Step 2: Provide a modification function > Advanced Javascript:

function main( P1 ){
      return mapGroups(P1);
}

function mapGroups(attribute){
    var result = [];
      if(attribute instanceof Array){
        var j =0;
        for(var i=0; i<attribute.length; i++){
            var grp = checkGroup(attribute[i]);
            if( grp != 'NA')
               result[j++] = grp;
             }
    }else{
            var grp = checkGroup(attribute);
        if( grp != 'NA')
                  result[0] = grp;
    }
      return result;
}

function checkGroup(group){
    if(/^cn=cloudsp.*,/.test(group) == true){
        var startindex = 3;// it starts with cn
        var endindex = group.indexOf(",");
        return group.substring( startindex, endindex);
     }else
        return 'NA';
}

To test the JavaScript, click the + and add multiple test values. Specify the test values:

cn=cloudspgroupa,ou=group,o=mycompany cn=cloudspgroupb,ou=group,o=mycompany cn=cloudspgroupk,ou=group,o=mycompany

cn=testgroupa,ou=group,o=mycompany

Output:

cloudspgroupa
cloudspgroupb
cloudspgroupk

Explanation:

The JavaScript in-built string function substring is used to extract the cn value from the group./^cn=cloudsp.*,/.test(group) is a regular expression which matches a string that starts with cloudsp. It has 0 or more characters followed by a comma (,)

Use Case 5: (utility function reuse test case)Consider a scenario where, the Identity provider roles are in the format companyX:rolename, but a service provider abc wants the roles in the following format: rolename and is in upper case.

To achieve this, remove 'companyX:' from each role and convert each of them into upper case for sending them to the protected web server. Each role is specified as companyX:rolename.

For example: companyX:admin, companyX:guest.

Solution:

In Step 1: Provide input parameters, select P1: All Roles.

Use the following code in the Step 2: Provide a modification function > Advanced Javascript:

Copy the JavaScript from the following pre-defined functions: Remove Substring and To upperCase.

Remove Substring function:

function findReplace(attribute, findString, replaceString){
      var result;
    if(attribute instanceof Array){
             result = [];
         for(var i=0; i<attribute.length; i++){
                   result[i] =attribute[i].split(findString).join(replaceString);
         }
      }else{
         result = attribute.split(findString).join(replaceString);
      }
    return result;
}

To upperCase function:

function convertToUpperCase (attribute){
      var result ;
    if(attribute instanceof Array){
            result = [];
        for(var i=0; i<attribute.length; i++)
                  result[i] = attribute[i].toUpperCase();
    }else{
              result = attribute.toUpperCase();
    }
    return result;
}

Now, customize the code. In the Substring to remove parameter for findReplace (), specify companyX:

function main(P1){
    return convertToUpperCase(findReplace (P1, 'CompanyX:'));
}

function findReplace(attribute, findString, replaceString){
    var result ;
      if(attribute instanceof Array){
        result = [];
            for(var i=0; i<attribute.length; i++){
            result[i] =attribute[i].split(findString).join(replaceString);
            }
    }else{
            result = attribute.split(findString).join(replaceString);
    }
      return result;
}

function convertToUpperCase (attribute){
    var result;
      if(attribute instanceof Array){
        result = [];
            for(var i=0; i<attribute.length; i++)
            result[i] = attribute[i].toUpperCase();
        }else{
        result = attribute.toUpperCase();
      }
    return result;
}

To test the JavaScript, add the following test values in P1: 'companyX:admin', 'companyX:guest'.Output: ADMIN, GUEST.

Use Case 6:

Consider a scenario where you do not want to modify an attribute value that is retrieved from an external source. To send the same attribute value in the assertion to a federated provider or in the policies, perform the following:

Click Devices > Identity Server > Shared Settings > Virtual Attributes > Virtual Attribute.

In Step1: Provide input parameters, select P1 and map it to an attribute retrieved from an external source.

In Step 2: Provide a modification function, select Advanced JavaScript and specify the following script:

function main(P1){
    return P1;
}

Test the script. The results returns the value of the attribute source specified as P1.

Update Identity Server.

For troubleshooting information, see Section 31.13, Troubleshooting User Attribute Retrieval and Transformation.