Configuring an identity agent for authentication by using multiple attribute sources

Use this procedure to configure an identity agent with attributes from sources such as LDAP, PostgreSQL, Db2, and Oracle Database.

About this task

A combination of one or more on-prem data sources can be used as a single identity provider for IBM® Security Verify. This configuration enables your identity agent to authenticate and source user attributes from one or more data sources.

The data sources that are supported by this configuration are:
  • LDAP
  • IBM Db2
  • PostgreSQL
  • Oracle Database
Terminology
Authentication source
The data source against which you intend to perform authentication.
JavaScript configuration
An on-prem configuration file that specifies the configuration details of the data source.
JavaScript plug-in
Your code for handling interaction with the non-primary LDAP.
Primary LDAP
Built in LDAP handling, no JavaScript plug-in is needed for the primary LDAP.
Alternative data sources
One or more extra data sources to be used along with or instead of primary LDAP.
Note: A maximum of 10 data sources can be used in any order, but the configuration for the primary LDAP and the alternative data sources differ.

Procedure

  1. Select Integrations > Identity agents.
  2. Select Create agent configuration.
  3. Select Authentication as the purpose.
  4. Select the LDAP tile.
  5. Select Next.
  6. Configure the connection settings
    Provide the following information to define the LDAP connection properties.
    Note: The primary LDAP is optional and doesn’t need to be the authentication source. If you do not want to use a primary LDAP, use dummy values for this section. If you elect to not use a primary LDAP, you must specify the following code in one of your JavaScript configurations.
    "authenticationSource":{
    "isAuthenticationSource": false,
          "disablePrimaryLDAPLookup": false
        },
    
    External LDAP host URI
    This attribute is the on-premises LDAP server connection information. For a cluster LDAP fail-over setup, you can add multiple LDAP server URIs by selecting ADD URI.
    Base
    This attribute is the LDAP container search base for users.
    LDAP bind DN
    This attribute is the LDAP server connection user.
    LDAP bind password
    This attribute is the ldap server connection password.
    LDAP certificate authority certificate
    This optional attribute is the SSL certificate that is used if the on-premises agent requires a TLS connection to the LDAP server.
    View additional settings
    You can define the following settings.
    • Enable whether LDAP requires TLS.
    • The maximum number of simultaneous LDAP connections for the LDAP server.
    • How long a successful password authentication is cached.
    • How long the connection is maintained.
    • The idle time before the LDAP server closes a connection.
    • The maximum time to process a request.
  7. Click Next.
  8. Provide the user properties.
    Attributes
    This attribute is a list of comma-separated LDAP user attributes that are returned from a successful password verify operation. For primary LDAP attributes, use the LDAP attribute name. For alternative data sources, prefix the name of the user attributes with the name of the JavaScript plug-in that is expected to return the attributes in the format pluginName-Attribute.. For example, if you set
    "pluginName": "OcPlug",
    then any attributes that are returned by the OcPlug must be prefixed with OcPlug-. For example, OcPlugin-mobile instructs the JavaScript plug-in OcPlug to retrieve the mobile value.
    Attributes must be comma separated. For example,
    givenName, sh, displayName, manager, mail, mobile,
    memberOf, uid, OcPlug-OCD_SPEC_ID, db2PLUG-
    XTENDEDATTR, ldap-seeAlso
    Note: The example demonstrates how to specify plug-in attributes. Attributes without a prefix such as givenName, sn, displayName, manager, mail, mobile, memberOf, and uid are sourced from the primary LDAP. OcPlug returns the attribute OCD_SPEC_ID, db2Plug returns the attribute XTENDEDATTR and the plug-in “ldap” returns the attribute seeAlso.
    Binary attributes
    This attribute is a list of comma-separated binary LDAP user attributes that are returned from a successful password verify operation.
    Username attribute
    This attribute is the naming attribute such as user id that is used to look up a user for password verification.
    Note: Username identifier attributes are case-sensitive . The default attribute samAccountName applies to earlier versions of Windows Active Directory. For Active Directory 2016 and later, the attribute is sAMAAccountName.
    Object class
    This attribute is a list of comma-separated object classes that the LDAP user can have. The object classes are used with the username attribute to look up a user for password verification.
    Note: Binary attributes, username attributes, and Object classes are intended for the primary LDAP, but are all passed to the JavaScript plug-ins and must be handled manually by the plug-in implementation.
  9. Select Next.
  10. Map the identity provider attributes from the identity provider to the Verify Cloud Directory attributes.
    After you create the identity agent, you can change or update the mappings by using the edit function pencil icon on the agent's tile.
  11. Select Next.
  12. In Finalize configuration, provide the following information.
    • A unique and recognizable name for the agent
    • A description
    • A display name for the identity provider
    • A realm for the identity provider
  13. Optional: Select View advanced settings to add configuration attributes or to select a certificate for encryption.
    Note: Advanced settings are intended for consumption by the primary LDAP, but are passed to and made available to the JavaScript plug-ins for manual processing.
  14. Click Save and continue.
  15. In Next steps , do the following steps.
    1. Select View API credentials and use the copy to clipboard icon to copy and store the Client ID and Client secret.
      Note: Only users with the proper entitlements can see the client secret. For more information, see Security updates for entitlements.
    2. If nor already downloaded, download the bridge agent from the IBM Container Repository (ICR). See Installing and configuring the Verify Bridge on Docker.
    3. Add your API credentials to the agent configuration.
  16. Click Finish.
    The configuration is added to Identity agents and the identity provider is listed in Authentication > Identity providers.
  17. Configuring JavaScript plug-ins.
    The bridge executable searches the following directories relative to itself.
    • ./jsconfig/ - The location of the configuration files.
    • ./jsplugins/ - The location of the JavaScript plug-ins.

    To make these directories available to a docker container, you can perform a bind mount from the host file system.

    volumes:
                    - ./jsconfig:/go/src/jsconfig:ro
                    - ./jsplugins:/go/src/jsplugins:ro
    
    This example shows the plug-in configuration for an Oracle database plug-in.
    {
        "pluginName": "OcPlug",
        "pluginType": "oracledb",
        "executionOrder": 1,
        "hardFail": true,
        "authenticationSource": {
          "isAuthenticationSource": true,
          "disablePrimaryLDAPLookup": false
        },
        "bindingConfig": {
          "connectionString": "oracle://system:oraclepass@host.docker.internal:1521/XE?CONNECTION TIMEOUT=5",
          "maxPoolSize": 50,
          "minPoolSize": 10,
          "agedTimeout": 60,
          "maxIdleTime": 10
        },
        "custom": {
          "table": "users"
        }
      }
    
    The following example shows a configuration for an LDAP plug-in.
    {
        "pluginName": "plugin1",
        "pluginType": "ldap",
        "executionOrder": 1,
        "hardFail": false,
        "authenticationSource": {
          "isAuthenticationSource": true,
          "disablePrimaryLDAPLookup": false
        },
        "bindingConfig": {
          "bindDn": "cn=admin,dc=ibm,dc=com",
          "bindPassword": "pass",
          "uris": [
            "ldaps://localhost:8636",
            "ldap://localhost:8389"
          ],
          "maxPoolSize": 50,
          "agedTimeout": 60,
          "connectTimeout": 5,
          "filter": "(|(|(objectclass=ePerson)(objectclass=person))(objectclass=User))", 
          "userObjectClasses": "top,Person,organizationalPerson,inetOrgPerson",
          "selector": "objectClass,cn,sn,givenName,userPassword,streetAddress,seeAlso,mobile", 
          "userIdentifier": "uid",
          "baseDn": "dc=ibm,dc=com",
          "tlsConfig": {
            "caCert": "-----BEGIN CERTIFICATE-----\nMIIDbzCCAlegAwIBAgIULjAe6hySQZ8C8d1LnWKHlpirro4wDQYJKoZIhvcNAQEL\nBQAwRzELMAkGA1UEBhMC…",
            "insecureSkipVerify": false,
            "tlsMinVersion": 0,
            "clientCertLabel": "extauthn.client"
          }
        },
        "custom": {
          "table": "users"
        }
      }
    
    Property Definition
    pluginName The name of the plug-in. The bridge searches ./jsplugins/<pluginName>.js for this file, relative to the bridge executable.
    pluginType
    • oracledb
    • postgres
    • Db2
    • ldap
    Execution order The order in which the plug-in runs. Lowest to highest.
    hardFail When false, bridge skips this plug-in if an error occurs retrieving attributes. Otherwise, and error is returned and authentication fails
    isAuthenticationSource Set to true if this plug-in is where authentication occurs.
    Note: Setting this property to true automatically causes the plug-in to hardfail.
    disablePrimaryLDAPLookup Disables the primary LDAP.
    connectionString The appropriate connection string for your database. It is applicable for
    • Db2
    • PostgreSQL
    • Oracle Database.

    Leave blank for LDAP.

    LDAP only
    filter LDAP filters.
    bindDn The bind DN.
    bindPassword The bind password.
    uris LDAP URIs. You can specify multiple for failover scenarios. Specify the protocol ldaps for TLS.
    userObjectClasses User object selectors.
    selector Selectors. The user attributes that you want must appear here.
    userIdentifier Identifier used when it performs a standard lookup.
    baseDn The location in the directory hierarchy where the search begins.
    caCert The CA cert that is used to validate the certificate presented by the LDAP server.
    insecureSkipVerify Skip TLS certificate checks.
    tlsMinVersion

    Minimum TLS version

    • 769 – v1.0
    • 770 – v.1.1
    • 771 – v1.2 (Default)
    • 772 – v1.3
    clientCertLabel

    For MTLS. It is the label of the cert and key that is used to sign traffic that is presented to the LDAP server.

    The agent searches for cert at

    /cert/<clientCertLabel>_cert.pem /cert/<clientCertLabel>_key.pem

    custom The custom values that can be passed via the configuration to the plug-in for manual processing.
    Example connection strings.
    Db2
    HOSTNAME=host.docker.internal;PORT=50000;UID=db2inst1;PWD=db2_password;DATABASE=usersdb"
    PostgreSQL
    host=host.docker.internal port=8788 dbname=postgres user=postgres password=postgrespassword connect_timeout=5
    LDAP TLS
    To use TLS to connect to LDAP via a JavaScript plug-in, make sure to specify the ldaps:// in the uris section and specify a valid caCert..
    "uris": [
            "ldaps://localhost:8636"
          ],
    
    To perform MTLS from an LDAP plug-in, you can place the client certificate and client certificate private in the /cert/ directory of your container by using bind mounts.
    - ./cert/:/cert:ro
    Make sure that the certificate names are of the format <clientCertLabel>_cert.pem and <clientCertLabel>_key.pem, where clientCertLabel is the clientCertLabel that is specified in the plug-in configuration for LDAP plug-ins.