Managing an Attribute Source

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

NOTE:You cannot delete an attribute source that is being used by a virtual attribute.

This section discusses the following topics:

Creating an Attribute Source

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

  2. Click + to add an attribute source.

  3. Specify a name and description for the attribute source.

  4. Select the data source.

  5. Specify the following details in Step 1: Provide input parameters:

    Field

    Description

    Name

    The default value is %P1% or {P1} based on the selection of data source.

    Specify the same name in Query or in fields that use the value of the attribute.

    Parameter Value

    Select an attribute from the list.

    Show / Add Test Values?

    Click this to display the test value, and specify a value in Test value.

    This value is used later when testing the query string or the web service.

    For REST web service, the input parameters can be used in creating resource API path, request headers, request body and the Advanced: Javascript response parsing functions. These can be tested using the test values. To use the input parameters, you must provide the parameter in the {<parameter name>} format, such as {P1}.

    When you click Test, the Test Results pane displays the status of the request and response based on the specified values.

    NOTE:For LDAP and database, the attribute source does not support multi-valued inputs. If you input multiple values, only one value is picked for the calculation.

    For REST web service, the attribute source supports multi-valued inputs for a parameter.

  6. (Conditional) For LDAP or database, specify the following details in Step 2: Provide query and output parameters:

    Field

    Description

    Query

    Specify an LDAP filter or a database query.

    The query must use the value specified in Step 1: Provide input parameters.

    Query Output Parameters

    Specify a name for the query output.

    To add multiple output parameters, click Add.

    • For an LDAP filter, specify the exact name of the attribute that you want to fetch.

    • For a database query, specify an alias for the attribute fetched. The order of the output parameters must match the sequence in which they are specified in the database query.

    Test

    Click to test the input values based on the filter and output parameters.

    For security reasons, you are prompted to enter the data source credentials. Test Result displays the status along with the test results. You can also view the error logs at the following location:

    /opt/novell/nam/adminconsole/logs/catalina.out

    Example 2-1 Sample configuration

    See A Sample LDAP Scenario and A Sample Database Scenario.

  7. (Conditional) For REST web service, specify the following details in Step 2: Configure Request and Response:

    Field

    Description

    Base URL

    Auto-populated based on the details specified for the data source.

    Resource/API Path

    Specify the path of resource or API to be used along with the base URL to send a request to the REST web service.

    For example, if you require to fetch attributes from the www.abc.com/rest/getUserInfo endpoint and the base URL is www.abc.com/rest/, then specify Resource/API Path as getUserInfo.

    If REST web service requires the input parameters defined in Step 1: Provide input parameters, select Plain Text or Javascript and use the parameter within Resource/ API Path.

    Plain Text

    Select this when you need to add simple values, such as a constant value and unmodified input parameter values. You can use Plain Text in the following scenarios:

    • If the REST web server requires a constant value, such as user1, to be available in the resource/ API path, select Plain Text and specify Resource/ API Path as /getuserinfo/user1.

    • If the REST web server requires a user name to be available in Resource/ API Path for different users, use the input parameter {P1} with the givenName value to specify Resource/ API Path, such as /getuserinfo/{P1}.

    Javascript

    Select this when you need to add and modify complex values in Resource/ API Path. For example, if in the endpoint URL, REST web server requires the user’s name in lower case along with the last name in lowercase, you can specify the following in Resource/ API Path:

    function main({P1},{P2})
var ret='/getuserinfo/'+ {P1}.toLowerCase()+"/"+{P2}.toLowerCase();
return ret;
}

    The return type of JavaScript can be string or array.

    NOTE:The input parameter can include multiple values, such as email (it can have values abc@example.com and abc@gmail.com). The multi-valued input parameter in the JavaScript main function are sent as a JavaScript array. If this attribute contains a single value for a specific user, this attribute is sent as a string to the JavaScript main function. So, ensure to check whether a parameter is sent as a string (single value) or as an array (multiple values) before processing it in the JavaScript main function.

    Method

    Select the request method that is accepted by the REST web server.

    GET and POST are the supported methods.

    Request Headers and Body

    Add request headers based on the REST endpoint configuration. By default, the Authorization header gets generated if you have selected Basic Auth during the creation of the REST web service Data source.

    You can add multiple headers for specific endpoints when configuring request headers. You can use the input parameter in the header value such as, {P1}.

    Specify the body message in plain text or JSON format. To specify the message using JavaScript, select Javascript.

    When you write a script, ensure that you request for the values that are either in string or in JSON format.

    Plain Text

    Select to include a constant input value or any input parameter value in the request body.The following example helps in understanding how to use the values in request body using plain text format:

    • If the body request should contain the constant values such as, john123 (userid), and abc (department) then you can specify Request > Body as {"userid": "john123", "department" : "abc"}

    • If the body request should contain some specific value that is variable and is not modified, then you can specify Request > Body as { "userid": {P1}, "department" : {P2}}

    Javascript

    Select to include a complex request body that requires modified input parameter values.The following example helps in understanding how to use the values in request body using the JavaScript format:

    function main({P1}, {P2}){
var ret = '{ "userid":"'+ {P1} + '","department" : "'+ {P2}+'"}';
return ret;
  }

    Response Parsing Function and Parameters

    To extract a specific response portion from the REST web server response, select the required response parsing function from the list.

    When a response is returned, you can use response parsing function to retrieve specific parameters that get mapped to the response parameters. This helps in retrieving the required values from the response. The Advanced: Javascript response parsing function can return single value (string, number, JSON) or multi-valued (array of strings, array of JSON) that get mapped to response parameters.

    Choose the required response parsing function along with its inputs under Response Parsing Function and Parameters. If you do not require to use the functions, you can choose No Response Parsing Function.

    For more information about each function, see Response Parsing Functions.

    Add

    Click to add parameter names to map to the values retrieved from the analyzed response.

    Response_As_Is is the default parameter that includes the complete response as it is received from the web server. You cannot delete Response_As_Is.

    • Sample JSON Response:

      {
attribute1: "abc"
attribute2: "pqr"
}

      You get Response_As_Is under Response Parameters and you can specify attribute1 and attribute2 under Response Parameters. This maps the Response Parameters to the attribute values in the JSON response. Hence, attribute1 is mapped to abc and attribute2 is mapped to pqr.

    • Sample Array Response:

      result[0]
result[1]

      You get Response_As_Is under Response Parameters and you can specify param1 and param2 under Response Parameters. This maps the Response Parameters to the attribute values in the array response. Hence, param1 is mapped to result[0] and param2 is mapped to result[1].

      For more information about mapping the parameters with the required attribute, see Retrieving Attributes from a REST Web Service.

    Example 2-2 Sample configuration

    See A Sample REST Service Scenario.

  8. To test this configuration:

    1. In Step 1: Provide input parameters, select Show / Add Test Values?, and provide a test value that is available as an attribute in the REST web server endpoint.

    2. In Step 2: Configure Request and Response, click Test. Specify the credentials that is defined while creating the data source. (See Creating a Data Source)

      Test results display the status for request and response. You can view the request URL, Headers, and Body under Request and view response parameters and headers under Response. The value of the parameters as retrieved from the response parsing function gets displayed in the test result window.

      The test result window displays the error message when the test result fails. For more information about the error you can check the logs at the following location:

      /opt/novell/nam/adminconsole/logs/catalina.out

A Sample LDAP Scenario

You want to fetch an email address from an external LDAP directory for which a user’s LDAP attribute (from the external LDAP directory) UID matches with the local LDAP attribute cn.

To achieve this, perform the following steps:

  1. In Step 1: Provide input parameters, select LDAP attribute: cn as a parameter value. Add input parameter %P1% and map it to the LDAP attribute.

  2. In Step 2: Provide filter and output parameters:

    1. Specify (&(objectclass=*)(uid=%P1%)).

    2. Specify the filter output name as email. email is the alias name given for the column email.

  3. Test this configuration.

    1. In Step 1: Provide input parameters, select Show / Add Test Values? and provide the test value as admin.

    2. In Step 2: Provide filter and output parameters: Click Test. Enter the data source credentials.

The test result returns the email address stored in the directory: admin123@example.com.

A Sample Database Scenario

You want to fetch an email address from the database for which a user’s name matches with the local LDAP attribute cn.

To achieve this, perform the following steps:

  1. In Step 1: Provide input parameters, select LDAP attribute: cn as the parameter value.

  2. In Step 2: Provide query and output parameters:

    1. Specify select email from Emp where name = '%P1%' (email and name are the column name and Emp is the table name)

    2. Specify the filter output name as mail (mail is the alias name given for the column email).

  3. Test this configuration.

    1. In Step 1: Provide input parameters, select Show / Add Test Values?, and provide a test value that represents a record in the column of the table.

    2. In Step 2: Provide query and output parameters: Click Test. Specify the data source credentials.

The test results return the email address stored in the database: admin123@example.com.

NOTE:Access manager also supports stored procedure queries in Database attribute sources.

For example: exec proc

exec proc @mail = 'bob@mf.in'

A Sample REST Service Scenario

You have a web service that returns the roles of a user and you require to retrieve the designation of the user from the response received.

The endpoint of the REST web service: https://10.10.10.1:8543/rest/catalog/user1/roles/role

Base URL: https://10.10.10.1:8543/rest/catalog/

Request body: 

"roles": [
    {
      "id": "cn=user1,cn=system,cn=usrapplication,ou=abc,ou=example,o=com"
    }
  ]
}

Response from REST web server (Response_As_Is):

{
    "roles": [
    {
      "id": "cn=user1,cn=system,cn=usrapplication,ou=abc,ou=example,o=com",
      "name": "user1",
      "designation": "Provisioning Administrator",
    "department": "Engineering",
      "level": 20,
      "subContainer": "system",
      "status": 50
    }
  ]
}

To retrieve the designation of user1 and map to Response Parameter, perform the following steps:

The response parameter mapped to the designation attribute value is used in virtual attribute.

  1. In Step1: Provide input parameters, specify {P1} with the givenName value.

    This input parameter is required because web server requires the user’s cn information in the request.

  2. In Step 2: Configure Request and Response:

    1. Select Plain Text and specify Resource/ API Path as {P1}/roles/role.

      Base URL is auto-populated from the value specified in the Data Source page, https://10.10.10.1:8543/rest/catalog/.

    2. Select Method as Post.

      In this scenario, the REST web service uses the POST method.

    3. In the Headers tab, Authorization is auto-populated. This header is retrieved from the REST Data Source page.

    4. Select Plain Text and specify the request body message:

      {
   "roles": 
  {"id":"cn={P1},cn=system,cn=usrapplication,ou=abc,ou=example,o=com"}
   ]
  }

    5. Select JSON Parse with Match Conditions.

    6. Specify the following Inputs:

      JSON Array Parse String: roles

      Match Conditions:

      Name: name

      Value: user1

  3. Test this configuration.

    1. In Step 2: Configure Request and Response, click Test. Specify the data source credentials.

      The Response_As_Is parameter is added by default.

    2. Click the edit icon next to the Response_As_Is parameter to view the complete response.

      To map designation attribute value to an output parameter, you must add designation as output parameter under Response Parameters.

      When the condition (name as user1) finds a match in the response, the designation value is retrieved and gets mapped to the designation parameter.

For information about retrieving response parameters, see Retrieving Attributes from a REST Web Service.

Editing an Attribute Source

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

  2. Click the attribute source you want to modify.

  3. On the Edit Attribute Source page, modify the details as required.

    For more information about the fields on this page, see Creating an Attribute Source.

  4. Click OK. Update Identity Server.

IMPORTANT:If the attribute source is being used by a virtual attribute, you need to update Identity Server every time you edit the properties of an attribute source.