3.5 Configuring the Identity Server Shared Settings

The Shared Settings tab on the Identity Servers page allows you to define the following shared settings:

  • Attribute sets: Sets of attributes that are exchangeable between identity and service providers.

  • User matching expressions: The logic of the query to the user store for identification when an assertion is received from an identity provider.

  • Shared Secret names: Custom shared secret names that you want to be available when configuring policies.

  • LDAP attributes: Custom LDAP attribute names that you want to be available when configuring policies.

  • Authentication card images: Custom images that you can assign to authentication cards to uniquely identify an authentication procedure.

  • Metadata Repositories: Import metadata of trusted providers.

You can reuse these settings. These are available in any Identity Server cluster configuration.

This section describes the following tasks:

3.5.1 Configuring Attribute Sets

The attributes you specify on the Identity Server are used in attribute requests and responses, depending on whether you are configuring a service provider (request) or identity provider (response). Attribute sets provide a common naming scheme for the exchange. For example, an attribute set can map an LDAP attribute such as givenName to the equivalent remote name used at the service provider, which might be firstName. These shared attributes can then be used for policy enforcement, user identification, and data injection.

For example, you could have a Web server application that requires the user’s e-mail address. For this scenario, you configure the Web server to be a protected resource of the Access Gateway, and you configure an Identity Injection policy to add the user’s email address to a custom HTTP header. When the user accesses the protected resource, the value of the email attribute is retrieved. However, if you create an attribute set with this attribute, then assign it to be sent with the authentication response of the Embedded Service Provider of the Access Gateway, the value is cached at authentication and is immediately available. If you have multiple attributes that you are using in policies, obtaining the values in one LDAP request at authentication time can reduce the amount of LDAP traffic to your user store.

You can define multiple attribute sets and assign them to different trusted relationships. You can also use the same attribute set for multiple trusted relationships.

To create and configure an attribute set:

  1. In the Administration Console, click Devices > Identity Server > Shared Settings > Attribute Sets > New.

  2. Specify the following fields:

    Set Name: Specify a name for identifying the attribute set.

    Select set to use as template: Select an existing attribute set that you have created, which you can use as a template for the new set, or select None. To modify an existing attribute set, select that set as a template.

  3. Click Next.

  4. To add an attribute to the set, click New.

  5. Specify the following fields:

    Specify the attribute. Select from the following:

    • Local Attribute: Select an attribute from the list of all server profile, LDAP, shared secret attributes and virtual attributes. For example, you can select All Roles to use in role policies, which enables trusted providers to send role information in authentication assertions. Share secret attributes must be created before they can be added to an attribute set. For instructions, see Creating Shared Secret Names.

    • Constant: Specify a value that is constant for all users of this attribute set. The name of the attribute that is associated with this value is specified in the Remote Attribute field.

    Remote Attribute: Specify the name of the attribute defined at the external provider. The text for this field is case sensitive.

    • A value is optional if you are mapping a local attribute. If you leave this field blank, the system sends an internal value that is recognized between Identity Servers.

      For a SAML 1.1 and SAML 2.0 identity consumer (service provider), a name identifier received in an assertion is automatically given a remote attribute name of saml:NameIdentifier. This allows the name identifier to be mapped to a profile attribute that can then be used in policy definitions.

    • A value is required if you are mapping a constant.

      An attribute set with a constant is usually set up when the Identity Server is acting as an identity provider for a SAML or Liberty service provider. The name must match the attribute name that the service provider is using.

    Remote namespace: Specify the namespace defined for the attribute by the remote system:

    • If you are defining an attribute set for LDAP, select none. If you want a service provider to accept any namespace specified by an identity provider, select none. If you want an identity provider to use a default namespace, select none. The urn:oasis:names:tc:SAML:1.0:assertion value is sent as the default.

    • If you are defining an attribute set for WS Federation, select the radio button next to the text box, then specify the following name in the text box.

      http://schemas.xmlsoap.org/claims
    • If you want to specify a new namespace, select the radial button by the text box, then specify the name in the text box.

    Remote format: Select one of the following formats:

    • unspecified: Indicates that the interpretation of the content is implementation-specific.

    • uri: Indicates that the interpretation of the content is application-specific.

    • basic: Indicates that the content conforms to the xs:Name format as defined for attribute profiles.

    Attribute value encoding: Select one of the following encoding options:

    • Special characters encoded: Encodes only the special characters in the attribute value.

    • Not encoded: Does not encode the attribute value.

    • Entire value encoded: Encodes the entire attribute value.

  6. Click OK.

    The system displays the map settings on the Define Attributes page, as shown below:

    New attribute set

    You can continue adding as many attributes as you need.

  7. Click Finish after you created the map.

    The system displays the map on the Attribute Sets page, as well as indicating whether it is in use by a provider.

  8. (Conditional) To configure a provider to use the attribute set, see Selecting Attributes for a Trusted Provider.

3.5.2 Editing Attribute Sets

You can edit attribute sets that have been created in the system.

  1. In the Administration Console, click Devices > Identity Server > Shared Settings > Attribute Sets.

  2. Click the name of the attribute set that you want to edit.

  3. The system displays an attribute set page with the following tabs:

    General: Click to edit the name of the attribute set.

    Mapping: Click to edit the attribute map.

    Usage: Displays where the attribute set is used. Informational only.

  4. Click OK, then click Close.

3.5.3 Configuring User Matching Expressions

When a service provider receives an assertion from a trusted identity provider, the service provider tries to identify the user. The service provider can be configured to take one of the following actions:

  • Accept that the assertion contains a valid user and authenticate the user locally with a temporary identity and account. As soon as the user logs out, the account and identity are destroyed.

  • Use the attributes in the assertion to match a user in the local user store. When you want the service provider to take this action, you need to create a user matching expression.

  • Use the attributes in the assertion to match a user in the local user store and when the match fails, create an account (called provisioning) for the user in the local user store of the service provider. When you want the service provider to take this action, you need to create a user matching expression.

The user matching expression is used to format a query to the user store based on attributes received in the assertion from the identity provider. This query must return a match for one user.

  • If the query returns a match for multiple users, the request fails and the user is denied access.

  • If the query fails to find a match and you have selected provisioning, the service provider uses the attributes to create an account for this user in its user store. If you haven’t selected provisioning, the request fails and the user is denied access.

The user matching expression defines the logic of the query. You must know the LDAP attributes that are used to name the users in the user store in order to create the user’s distinguished name and uniquely identify the users.

For example, if the service provider user store uses the email attribute to identify users, the identity provider must be configured to send the email attribute. The service provider would use this attribute in a user matching expression to find the user in the user store. If a match is found, the user is granted access. If the user is not found, that attribute can be used to create an account for the user. The assertion must contain all the attributes that the user store requires to create an account.

To create a user matching expression:

  1. In the Administration Console, click Devices > Identity Servers > Shared Settings > User Matching Expressions.

  2. Click New, or click the name of an existing user matching expression.

  3. Specify a name for the user lookup expression.

  4. Click the Add Attributes icon (plus sign), then select attributes to add to the logic group. (Use the Shift key to select several attributes.)

  5. Click OK.

  6. To add logic groups, click New Logic Group.

    The Type drop-down (AND or OR) applies only between groups. Attributes within a group are always the opposite of the type selection. For example, if the Type value is AND, the attributes within the group are OR.

  7. Click the Add Attributes icon (plus sign) to add attributes to the next logic group, then click OK.

  8. Click Finish.

  9. (Conditional) If you selected attributes from the Custom, Employee, or Personal profile, you need to enable the profile so that the attribute can be shared:

    1. Click Servers > Edit > Liberty > Web Service Provider.

    2. Select the profiles that need to be enabled, then click Enable.

    3. Click OK, then update the Identity Server.

3.5.4 Adding Custom Attributes

You can add custom shared secret names or LDAP attribute names that you want to make available for selection when setting up policies.

Creating Shared Secret Names

The shared secret consists of a secret name and one or more secret entry names. You can create a secret name only, or a secret name and an entry name. For ease of use, the entry name must match the policy that uses it:

  • For a Form Fill policy, the entry name must match a form field name.

  • For an Identity Injection policy, the entry name must match the Custom Header Name.

  • For an External Attributes policy, Secret Name must match the policy name and Secret Entry Name must match the attribute name configured while creating the policy.

    For example, if the policy name is fetchattr and attribute name configured in the policy is address, then Secret Name must be fetchattr and Secret Entry Name must be address.

For more information about how to use shared secrets with policies, see Creating and Managing Shared Secrets.

The Identity Server needs to be configured to use shared secrets. For information about this process, see Configuring a User Store for Secrets.

Shared secret names can be created either on the Custom Attributes page or in the associated policy that consumes them.

  1. In the Administration Console, click Devices > Identity Servers > Shared Settings > Custom Attributes.

  2. To create shared secret names, click New.

  3. Enter a new shared secret name and, optionally, a secret entry name.

  4. Click OK.

  5. (Optional) To create additional entries for the secret, click the name of the secret, click New, specify an entry name, then click OK.

WARNING:The Identity Server currently has no mechanism to determine whether a secret is being used by a policy. Before you delete a shared secret, you must ensure that it is not being used.

Creating LDAP Attribute Names

LDAP attributes are available for all policies. LDAP attribute names can be created either on the Custom Attributes page or in the associated policy that consumes them. The attribute names that you specify must match the name of an attribute of the user class in your LDAP user store.

  1. In the Administration Console, click Devices > Identity Servers > Shared Settings > Custom Attributes.

    This list contains the attributes for the inetOrgPerson class. It is customizable.

    audio: Uses a u-law encoded sound file that is stored in the directory.

    businessCategory: Describes the kind of business performed by an organization.

    carLicense: Vehicle license or registration plate.

    cn: The X.500 commonName attribute, which contains a name of an object. If the object corresponds to a person, it is typically the person’s full name.

    departmentNumber: Identifies a department within an organization.

    displayName: The preferred name of a person to be used when displaying entries. When displaying an entry, especially within a one-line summary list, it is useful to use this value. Because other attribute types such as cn are multivalued, an additional attribute type is needed.

    employeeNumber: Numerically identifies a person within an organization.

    employeeType: Identifies the type of employee.

    givenName: Identifies the person’s name that is not his or her surname or middle name.

    homePhone: Identifies a person by home phone.

    homePostalAddress: Identifies a person by home address.

    initials: Identifies a person by his or her initials. This attribute contains the initials of an individual, but not the surname.

    jpegPhoto: Stores one or more images of a person, in JPEG format.

    labeledURI: Uniform Resource Identifier with an optional label. The label describes the resource to which the URI points.

    mail: A user’s e-mail address.

    manager: Identifies a person as a manager.

    mobile: Specifies a mobile telephone number associated with a person.

    o: The name of an organization.

    pager: The pager telephone number for an object.

    photo: Specifies a photograph for an object.

    preferredLanguage: Indicates an individual’s preferred written or spoken language.

    roomNumber: The room number of an object.

    secretary: Specifies the secretary of a person.

    sn: The X.500 surname attribute, which contains the family name of a person.

    uid: User ID.

    userCertificate: An attribute stored and requested in the binary form.

    userPKCS12: A format to exchange personal identity information. Use this attribute when information is stored in a directory service.

    userSMIMECertificate: PKCS#7 SignedData used to support S/MIME. This value indicates that the content that is signed is ignored by consumers of userSMIMECertificate values.

    x500uniqueIdentifier: Distinguishes between objects when a distinguished name has been reused. This is a different attribute type from both the uid and the uniqueIdentifier type.

  2. To add a name:

    1. Click New.

    2. If you want the attribute to return raw data rather binary data, select 64-bit Encode Attribute Data.

    3. Click OK.

  3. To modify the 64-bit attribute data encoding, click an attribute’s check box, then click one of the following links:

    Set Encode: Specifies that LDAP returns a raw format of the attribute rather than binary format, which Access Manager encodes to base64, so that the protected resource understands the attribute. You might use base64 encoding if you use certificates that require raw bites rather than binary string format.

    Clear Encode: Deletes the 64-bit data encoding setting.

  4. Click Apply to save changes, then click the Servers tab to return to the Servers page.

3.5.5 Adding Authentication Card Images

Each authentication contract and managed card template must have a card associated with it.

To add new images, the image files must be available from the workstation where you are authenticated to the Administration Console. Images must fall within the size bounds of 60 pixels wide by 45 pixels high through 200 pixels wide by 150 pixels high.To add a card image:

  1. In the Administration Console, click Devices > Identity Servers > Shared Settings > Authentication Card Images.

  2. Click New.

  3. Fill in the following fields.

    Name: Specify a name for the image.

    Description: Describe the image and its purpose.

    File: Click Browse, locate the image file, then click Open.

    Locale: From the drop-down menu, select the language for the card or select All Locales if the card can be used with all languages.

  4. Click OK.

  5. If you did not specify All Locales for the Locale, continue with Creating an Image Set.

3.5.6 Creating an Image Set

You can create card images for specific locales as well as a default image for all locales. The images need to be placed in an image set that allows the browser to display the image associated with the requested locale. If the browser requests a locale for which you have not defined an image, the All Locales image is displayed. If an All Locales image is not available, the browser displays the Image not Available card.

  1. In the Administration Console, click Devices > Identity Servers > Shared Settings > Authentication Card Images.

  2. Click the card image.

  3. To add an image to the set, click New, then fill in the following fields:

    File: Click Browse, then browse to the location of the file.

    Locale: Select the locale from the drop-down menu.

  4. Click OK.

3.5.7 Metadata Repositories

Large scale federations have more than 100+ identity and or service providers and it is a tedious task to establish bi-lateral relationships with Access Manager. You as an identity provider can now configure several identity and or service providers using a multi-entity metadata file available in a central repository. The identity and/or service providers become partners of a community which maintains a single metadata file containing metadata of all the approved partners. The identity and or service providers submit their metadata which includes specifications of services offered (SAML 1.1 and SAML 2.0) and any other information. This feature is available only for SAML 1.1 and SAML 2.0.

For example, XYZ is an e-book store and several e-book stores, which are either identity or service providers are partner with it. XYZ maintains a single metadata file containing metadata of all the other stores. ABC an e-book identity provider wants to establish a federation with many other e-book stores. Hence, ABC partners with XYZ by sharing its metadata and XYZ in turn shares the metadata XML file. ABC imports the XML file available publicly on the internet (for example, http://xyz.commonfederation.org/xyz-metadata.xml) and establishes trusts with others in the federation which includes XYZ’s trusted provider sites.

Creating Metadata Repositories

  1. In the Administration Console, click Devices > Identity Servers > Shared Settings > Metadata Repositories.

  2. Click New and fill in the following fields:

    Name: Enter the name of the metadata repository.

    Description: Enter the description of the metadata repository.

    Source: From the drop-down menu, select the source from which you want to import the metadata file.

    • To specify the URL location of the XML file in the URL field, select Metadata URL.

    • To specify the path of the XML file in the File field, select Metadata File.

  3. Click Finish.

    The details of the metadata such as the number of identity servers and service providers present in the metadata, and expiry date of the metadata are displayed.

    You can select the metadata repository and click Delete to delete the repository. If the metadata file is in use, you cannot delete it. Delete the trusted provider first and then delete the metadata file.

  4. Select All to see a list of entities. If the entity is supporting it the respective protocol will be checked.

When the metadata repositories are imported, the entities available in the metadata repository can be assigned as trusted provider to any of the Identity Provider clusters. To create trusted providers, see Managing Trusted Providers.

Reimporting Metadata Repositories

You can reimport the metadata repository to get the updated XML.

  1. In the Administration Console, click Devices > Identity Servers > Shared Settings > Metadata Repositories.

  2. Click on the metadata repository you created and click Reimport.

  3. Specify the URL location of the XML file in the URL field and click Next.

  4. The screen displays the following:

    New Entities added to the repositories: If the entities are updated or deleted and are assigned as TrustedProviders to an Identity Server cluster then the Identity Server cluster name is displayed in brackets next to the entity ID.

    Entities Deleted from the repositories: If the entity is updated and is assigned as a trusted provider to an Identity Server cluster, that trusted provider will be updated. You must update the Identity Server cluster for the changes to take effect.

    Entities Updated in the repositories: If an entity is deleted and was assigned as trusted provider to an Identity Server cluster, then the link between the trusted provider and the metadata repository entity is deleted.

    NOTE:The corresponding trusted provider is not deleted and you will have to manually delete the trusted provider.

  5. Click Finish to apply the changes.

3.5.8 User Attribute Retrieval and Transformation

With this release of Access Manager, you can retrieve an attribute from an external source and transform it before sending it in an assertion. The User Attribute Retrieval and Transformation feature enables you to retrieve attributes from a data source (any database or LDAP repositories) and transform them. This feature also allows you to transform user’s local attributes (LDAP attributes, Shared Secrets, and various profiles such as Personal Profile and Employee Profile).

Virtual attributes can be used to generate dynamic data at runtime from the current values of the user attributes.

The transformed attribute values are not stored in any persistent data stores. They are in the memory as part of user’s session.

How User Attribute Retrieval and Transformation Helps

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

  • Retrieve attribute values from external sources other than the configured user stores. The sources can be an external database or any external LDAP repository.

  • Transform attribute values before they are sent as part of an assertion to a federated provider. For example, you can edit an attribute value before it is sent from identity provider to a service provider in a SAML 2.0 federation. You can also edit an attribute value sent from identity provider to the Access Gateway used in policies.

  • Transform the attribute value used in policies. For example, you can transform the Identity Server role-based policies.

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

  • Data Source: An entity that holds configuration properties that help in connecting to an external data source. The properties of the data source can be defined in the data source user interface. A data source can be an LDAP repository or a SQL database.

  • Attribute Source: Represents queries that fetch attributes from a data source. You can define either an LDAP search filter or a SQL query, based on the data source type.

  • Virtual Attribute: Helps you specify the attributes that must be transformed and in the way the transformations happen. A virtual attribute can transform multi- valued attributes.

Prerequisites

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.

Limitations

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

  • Multi-valued input parameters are not supported in the attribute source. If you input a multi-valued parameter, only one value is picked for the calculation.

  • You cannot use the existing Identity server user stores directly as an attribute source. You must create a separate data source to use the user stores.

  • You cannot edit or store any attribute value permanently in the existing LDAP attributes, shared secret attributes, or external database by using virtual attributes.

  • The risk-based policies do not support virtual attributes.

  • OAuth configuration does not support virtual attributes.

  • Virtual attributes do not support modifications of attribute sources that contain binary data. Only string, boolean, integer, date, and numeric values from database are supported.

  • SSL communication with SQL and Oracle databases that are used by virtual attributes (data sources) is not supported.

Managing a Data Source

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

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

This section discusses the following topics:

Creating a Data Source

To create a data source, perform the following steps:

  1. In the Administration Console, click Devices > Identity Server > Shared Settings > Data Sources.

  2. Click + to add a data source.

  3. From the list, select one of the data sources: Database or LDAP.

  4. Specify the database connection properties.

    1. For Database

      MS SQL and Oracle databases are supported.

      Field

      Description

      Database Name

      Specify the name of the database.

      Database Driver

      Select a driver from the list. The associated driver name is auto-populated. If you select Others (Unsupported), specify the driver name in the adjacent field.

      Max Connections

      Specify the maximum number of connections. By default, it is set to 20.

      Idle TimeOut

      Specify the idle timeout. By default, it is set to 600000 milliseconds. You can set this value based on the server setting. For example, if the server timeout is 600000 milliseconds, then the timeout value must not exceed 600000.

      Connection TimeOut

      Specify the connection timeout. By default, it is set to 10000 milliseconds. You can set this value based on the server setting.

      Username

      Specify the username used to read from the database.

      Password

      Specify the password used to read from the database.

      Confirm Password

      Specify the password once again.

      URL

      Specify the database URL based on the database driver selected.

      Based on the database type you select, you need to add the corresponding jars.

      1. For Oracle Database:

        1. Download the JDBC connector for the Oracle database from Oracle.com.

        2. Copy the JDBC connector jar to the following folder:

          On Windows

          • Administration Console: C:\Program Files (x86)\Novell\Tomcat\webapps\nps\WEB-INF\lib

          • Identity Server: C:\Program Files (x86)\Novell\Tomcat\webapps\nidp\WEB-INF\lib

          On Linux

          • Administration Console: /opt/novell/nam/adminconsole/webapps/nps/WEB-INF/lib

          • Identity Server: /opt/novell/nam/idp/webapps/nidp/WEB-INF/lib

        3. Restart the Administration Console and the Identity Server.

      2. For Microsoft SQL Server:

        1. Download the JDBC connector for the SQL Server database from Microsoft.com.

        2. Copy the JDBC connector jar file to the following folder:

          On Windows

          • Administration Console: C:\Program Files (x86)\Novell\Tomcat\webapps\nps\WEB-INF\lib

          • Identity Server: C:\Program Files (x86)\Novell\Tomcat\webapps\nidp\WEB-INF\lib

          On Linux

          • Administration Console: /opt/novell/nam/adminconsole/webapps/nps/WEB-INF/lib

          • Identity Provider: /opt/novell/nam/idp/webapps/nidp/WEB-INF/lib

        3. Restart the Administration Console and the Identity Server.

    2. For LDAP:

      eDirectory and Active Directory are supported.

      NOTE:The SunONE directory is currently not supported.

      Field

      Description

      LDAP Name

      Specify a display name for the LDAP database.

      Username

      Specify the username used to read from the database.

      Password

      Specify the password used to read from the database.

      Confirm Password

      Specify the password once again.

      Directory Type

      From the list, select the type of directory. If you select Others (Unsupported), specify a directory name in the adjacent field: sunonedir, custom1, custom2, custom3, custom4, others.

      Max Connections

      Specify the maximum number of connections. By default, it is set to 20.

      LDAP Operation TimeOut

      Specify the LDAP operation timeout. By default, it is set to 15000 milliseconds. You can set this value based on the server setting.

      Idle Connection TimeOut

      Specify the connection timeout. By default, it is set to 10000 milliseconds. You can set this value based on the server setting. For example, if the server timeout is 15000 milliseconds, then the LDAP timeout value must not exceed 15000.

      IP Address

      Specify the IP address of the LDAP directory.

      Port

      Specify the port number. By default, it is 389.

      For a secure connection, select Use Secure LDAP Connection. The port number changes to 636.

      You must import the trusted root if you select a secure connection. To import the trusted root, click Auto Import Trusted Root. The trusted certificate of the server will be imported to the Identity provider trust store. Update the Identity provider each time.

      Search Contexts

      The search context is used to locate users in the directory. If a user exists outside of the specified search context and its scope (or One level, Object or Subtree), the Identity Server cannot find the user and the search fails.

  5. Test Connectivity: Click Test to test the data source connection after specifying the details. You can also view the error logs at the following locations:

    • Linux: /opt/novell/nam/logs/adminconsole/tomcat/catalina.out

    • Windows: \Program Files (x86)\Novell\Tomcat\logs\stdout.log

Editing a Data Source

  1. In the Administration Console, click Devices > Identity Server > Shared Settings > Data Sources.

  2. Click the data source you want to modify.

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

    NOTE:If you change the IP address of the LDAP data source, then, you must import the trusted root of the updated server to the Identity server trust store.

    For more information about the fields on this page, see Creating a Data Source.

  4. Click OK.

  5. Update the Identity Server.

IMPORTANT:You must update the Identity Server every time you edit the properties of a data source that is being used by an attribute source and the attribute source in turn, being used by the virtual attribute.

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. In the Administration Console, click Devices > Identity Server > Shared Settings > Virtual Attributes > Attribute Source.

  2. Click + to add an attribute source.

  3. Specify an attribute source Name.

  4. Specify the description of the attribute source.

  5. From the list, select the data source.

  6. Click Step 1: Provide input parameters.

    1. Name: Specify a name for the attribute. You must specify the same name in the query field. The default value is %P1%.

    2. Parameter Value: Select an attribute from the list. The available options are: Server profile, LDAP, and shared secret attributes.

    3. Click Show / Add Test Values? to display the test value field. Specify a value in the Test value field.

    To provide additional parameter values, click +.

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

  7. Click Step 2: Provide query and output parameters.

    For one attribute source, you can provide only one output parameter.

    1. Filter / Query: Specify an LDAP filter or a database query. The query must use the input details specified in the Step 1: Provide input parameters section.

    2. Filter / Query Output Parameters: Specify a name for the filter / query output. To add multiple output parameters, click Add.

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

      • In the case of a database query, you can 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.

    3. Test: To test the input values based on the filter and output parameters, click Test. For security reasons, you are prompted to enter the data source credentials. The Test Result window displays the status along with the test results. You can also view the error logs at the following locations:

      • Linux: /opt/novell/nam/logs/adminconsole/tomcat/catalina.out

      • Windows: \Program Files (x86)\Novell\Tomcat\logs\stdout.log

    LDAP Scenario:

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

    To configure 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 the following query: (&(objectclass=*)(uid=%P1%))

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

    3. To 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 results return the email address stored in the directory: admin123@example.com.

    Database Scenario:

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

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

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

      1. Specify the following query: select email from Emp where name = '%P1%' (email and name is 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. To 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. Enter the data source credentials.

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

Editing an Attribute Source

To edit the properties of an attribute source, perform the following steps:

  1. In the Administration Console, 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 the Identity Server.

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

Managing a Virtual Attribute

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

NOTE:You cannot delete a virtual attribute that is being used by an attribute set. Also, before deleting a virtual attribute, ensure that it is not being used by a policy.

This section discusses the following topics:

Creating a Virtual Attribute

You can create a virtual attribute from an attribute source and an external data source.

  1. In the Administration Console, click Devices > Identity Server > Shared Settings > Virtual Attributes > Virtual Attribute.

  2. Click + to create a virtual attribute.

  3. Specify a name for the virtual attribute.

  4. Enter the description.

  5. Click Step 1: Provide input > parameters.

    1. Name: Specify a name for the attribute. If you use advanced JavaScript option, then, you need to specify the same name in the advanced JavaScript field. The default value is P1.

    2. Parameter Value: Select an attribute from the list. In addition to Server profile, LDAP, and shared secret attributes, attribute sources are also listed. To specify additional values, click +.

      NOTE:If an attribute source returns a null or an empty value, then the corresponding input parameter takes an empty string value.

    3. Click Show / Add Test Values? to display the test value field. Click + to add a test value. Click the edit icon to edit the test value. Click the delete icon to delete the test value.

  6. Click Step 2: Provide a modification function.

    1. Select a function: From the list, select a function. The corresponding JavaScript is displayed in the Script field. To view it, expand the script. You can further customize these scripts and use them in the Advanced JavaScript field.

      The following table lists the pre-defined JavaScript functions along with examples:

      Function

      Description

      Example: Pre-Defined Functions

      To UpperCase

      Converts the input value to upper case.This function works on arrays and single-valued input. It uses the following JavaScript function: toUpperCase()

      Works only on one input parameter that is selected in Step 1: Provide input parameters

      If P1=alice, then the result displays ALICE.

      To LowerCase

      Converts the input value to lower case.This function works on arrays and single-valued input. It uses the following JavaScript function: toLowerCase()

      Works only on one input parameter that is selected in Step 1: Provide input parameters

      If P1=ALICE, then the result displays alice.

      Remove Substring

      Removes a substring from all instances of the input value. This function does not remove a substring from the global option.This function works on arrays and single-valued input. It uses the following JavaScript function: split() and join()

      Works only on one input parameter that is selected in Step 1: Provide input parameters

      If P1=a@microfocus.com

      Remove=@microfocus, then the result is a.com.

      Find and Replace

      Finds and replaces a string from all instances of the input value.

      Works only on one input parameter that is selected in Step 1: Provide input parameters

      If P1=abcde

      Find=e

      Replace=a, then the result displays abcda

      Regex Replace

      Finds and replaces a substring from all instances of the input value by using a regular expression.

      For example, to search /, you must escape it first using \. Use the following syntax: /\//

      This function works on arrays and single-valued input. It uses the following JavaScript functions: replace()

      Works only on one input parameter that is selected in Step 1: Provide input parameters

      If P1=bob@novell.com

      Find=@novell.com

      Replace=@microfocus.com

      The result displays: bob@microfocus.com

      Find Subset by Regex

      Use this function if an input is multi-valued and you want a subset of values from it, satisfying a particular condition by using a regular expression.This function works on arrays and single-valued input. It uses the following JavaScript function: replace()

      Works only on one input parameter that is selected in Step 1: Provide input parameters

      If

      P1='’a@novell.com, b@novell.com,c @microfocus.com, d@microfocushr.com”

      regex= /microfocus/

      Then, the result displays:

      c@microfocus.com, d@microfocushr.com

      Concatenate Values in a Parameter

      Concatenates multiple values of a multi-valued input. You must add a separator between the values that you want to concatenate

      Works only on one input parameter that is selected in Step 1: Provide input parameters

      If P1=abc, def

      Separator=+

      Then, the result displays:

      abc+ def

      Concatenate Multiple Parameters

      Concatenates multiple input parameter values, where each input parameter can be multi-valued input. You must add a separator between the values that you want to concatenate

      If P1=abc, def

      and P2=123, 456

      Parameter Separator=+

      Multi value Separator=:

      Then, the result displays abc:def+123:456

      Advanced JavaScript

      Specify a customized JavaScript In this field. You need to create a JavaScript function with name “main” and specify the code in it. You can write your custom code or you can also copy the existing pre-defined code.You can also call multiple functions in the “main” function.

      See the Sample JavaScripts with Examples.

      NOTE:

      • After JavaScript processing, if the output is a null value, then the value of the virtual attribute is empty.

      • The pre-defined function can handle both single-valued and multi-valued inputs. If the input is multi-valued, then pre-defined function is applied on each of the values.

      Advanced JavaScript:

      Sample JavaScript:

      function main(P1, P2)
           {
                //some logic
                //you can call yourFunction(name) and use its return value
                return some value;
           }
           function yourFunction(name)
           {
                //some code
               //return some value;
           }

      In case of advanced JavaScript, the input parameter name in the main function of the JavaScript must match the input parameter name specified in the Step 1: Provide input parameters section. The return value can be a single value or an array.

      When the input is multi-valued, it is passed as an array to the main function.

      When the Identity Server computes the value of a virtual attribute, it calls a function named “main” that is available in the script provided for it. The value (single value or array) returned by main is the value of the virtual attribute.

      For example:Consider a scenario where P1 contains bmw and nissan, you can use the JavaScript instanceof function to check if the input is single-valued or multi-valued. If it is multi-valued, then JavaScript iterates over the values P1=['bmw', 'nissan']

      function main (P1){
        if( P1 instanceof Array) {
          var a =P1[0]    //will assign 'bmw' value to variable a
          //do something
        }
      }

      The following code checks if an input parameter has a value, is empty or undefined:

      function main(P1){
        if(hasNoValue(P1))
          // do something
             return something;        
      }
      function hasNoValue(P1){
         if(P1 == null || (typeof P1 == 'undefined') || P1.trim().length == 0)
              return true;
         else 
              return false;
      }
    2. Test: To test the input values based on the modification function, click Test. To test multi-valued inputs, click the + button.

      For example, if an attribute mail has two values: abc@example.com and def@example.com, then to test them, click the + button twice. In each field, add the values separately.

      The Test Result window displays the status along with the test results. You can view the error logs at the following locations:

      • Linux: /opt/novell/nam/logs/adminconsole/tomcat/catalina.out

      • Windows: \Program Files (x86)\Novell\Tomcat\logs\stdout.log

  7. Click OK.

  8. Update the Identity Server.

Editing a Virtual Attribute

  1. In the Administration Console, click Devices > Identity Server > Shared Settings > Virtual Attributes.

  2. Click the virtual attribute you want to modify.

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

    For more information about the fields on this page, see Creating a Virtual Attribute.

  4. Click OK. Update the Identity Server.

IMPORTANT:You must update the Identity Server every time you edit the properties of a virtual attribute.

Sample JavaScripts with Examples

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.

Solution: The solution is as follow:

Creating a Data Source:

  1. Configure an LDAP data source with name “dsLdap”. Specify the connection properties. Test the connection.

  2. Import the secure LDAP certificate to Identity Server trust store using the create Data Source screen.

  3. Click Update All to update the Identity Servers.

Creating an Attribute Source:

  1. In the Administration Console, click Devices > Identity Server > Shared Settings > Virtual Attributes > Attribute Source. Create an attribute source with name “dsLdapAttrSrc”.

  2. Select data source name “dsLdap”.

  3. Add input parameter %P1%. Map it to the LDAP attribute: givenName.

  4. Add a Filter: name=%P1%.

  5. Add output parameter: partnerID

  6. Test Filter: Test the input values.

Creating a Virtual Attribute:

  1. In the Administration Console, click Devices > Identity Server > Shared Settings > Virtual Attributes > Virtual Attribute. Create a virtual attribute with name “partnerID”.

  2. Add input parameter P1. Map it to dsLdapAttrSrc:partnerID (the attribute source that you created in Step 1 of the creating an Attribute Source section).

  3. In Step 2: Provide query and output parameters, specify the following script:

    function main(P1){
       return "PID:"+P1;
    }
  4. Test the script. The results return: PID: P1. For example, if partnerID=part123, then, the test result is PID:part123.

  5. Update the Identity Server.

  6. Use it in the Identity injection policy.

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 ).

Solution:

Create a virtual attribute: App1Admin.

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

  • P1: is mapped to LDAP attribute isManager

  • P2: is mapped to LDAP attribute groupmembership

  • P3: is mapped to LDAP attribute role value

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:

  • P1: true

  • P2: adminsRecruitmentDep

  • P3: recruiter,employee

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 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: arn:aws:iam::638116851885:role/admin

  • For finance: arn:aws:iam::638116851885:role/finance

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=netiq") 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=netiq cn=cloudspgroupb,ou=group,o=netiq cn=cloudspgroupk,ou=group,o=netiq

cn=testgroupa,ou=group,o=netiq

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:

In the Administration Console, 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 the Identity Server.

Troubleshooting User Attribute Retrieval and Transformation

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