CA API Gateway 9.1

9.4 9.1

LDAP Identity Provider Wizard

The LDAP Identity Provider Wizard guides you through adding or modifying an LDAP Identity Provider on the gateway.
gateway
The
LDAP Identity Provider Wizard
 guides you through adding or modifying an LDAP Identity Provider on the
CA API Gateway
.
You can click the [
Test
] button (when available) to test your configuration at any time.
Contents:
Step 1: Provider Configuration
This step defines the LDAP Identity Provider details.
Configure this step as follows:
  1. Select your LDAP Identity Provider type from the
    Provider Type
     drop-down list.
  2. Provider Name
    : Enter a descriptive name for the LDAP Identity Provider. This name appears in the [Identity Providers] tab and on the Search Identity Providers dialog.
  3. LDAP Host URL
    : 
    • Click [
      Add
      ] to enter the URL of the LDAP or LDAPS directory service you want to connect to—for example, ldap://oracle.companyx.com:389 or ldaps://oracle.companyx.com:636
      When configuring using the IPv6 address space, the host URL must be enclosed within "[ ]" if a literal IPv6 address is used, for example:
      ldap://oracle.companyx.com:389 (no brackets required)
      ldap://[2222::22]:389 (brackets required)
    • Click [
      Remove
      ] to remove a URL from the list.
    • Use [
      Move Up
      ] and [
      Move Down
      ] to change the order of the URLs.
  4. Use Client Authentication
    : Select this check box to present a certificate to the server during the SSL handshake, if one is requested. Clear this check box to never present a certificate, even if one is requested. Access may be denied in this case.
    When Client Authentication is enabled, it is used with the specified key when connecting to an LDAP server for any LDAP(S) connections. The Client Certification options have no effect if there are no LDAP(S) connections.
    • Keystore
      : From the drop-down list, select the keystore from which to retrieve the certificate. Used only if client certificates are used.
    • Search Base
      : Enter the search base for users and groups in the LDAP—for example, dc=companyx,dc=com.
    • Bind DN
      : Optionally enter a binding DN (Distinguished Name) identity for authenticating access to the LDAP directory—for example, cn=manager.
    • Bind Password
      : Optionally enter a password if you entered a bind DN identity.
      You may reference the 
      ${secpass.<name>.plaintext}
       context variable here, even if context variable reference has been disabled for stored passwords.
    • Allow assignment to administrative roles
      : Select this check box to allow LDAP users to be assigned to roles. Clear this check box to prevent the LDAP repository from being searched.
    • Allow updates from:
       Select this check box to allow the Write LDAP Assertion to update this LDAP Identity Provider. Clear this check box to disallow updates to this LDAP Identity Provider (default).
      • Write Base:
         If you are allowing updates, specify the DN branch from which updates are allowed. The Gateway prevents any attempts to update values that lie outside of this Write Base DN. If you do not specify a Write Base, then updates cannot be made to the LDAP repository (same as deselecting the check box).
    • Reconnect Timeout:
       The amount of time that must pass before the Gateway attempts to reconnect to an LDAP Host URL that failed. The availability of this field depends on the
      Use System Default
       setting:
      • If
        Use System Default
         is selected, then the Gateway always uses the timeout value that is defined in the
        ldap.reconnect.timeout
        cluster property. By default, this is
        60000
         ms.
        Note:
         Any changes to the cluster property are not reflected in the Reconnect Timeout box.
      • If
        Use System Default
         is not selected, then the Gateway uses the timeout value that is specified here (in milliseconds). The cluster property is ignored in this case.
    • Security Zone
      : Optionally choose a security zone. To remove this entity from a security zone (security role permitting), choose "No security zone". For more information about security zones, see Understanding Security Zones.
      Note: 
      This control is hidden if either: (a) no security zones have been defined, or (b) you do not have Read access to any security zone (regardless of whether you have Read access to entities inside the zones).
Step 2: Group Object Classes
This step defines LDAP group object classes for the provider that is defined in Step 1.
The wizard automatically populates default object classes based on the provider type. Review and modify as necessary.
Consult your LDAP Identity Provider for information about supported group object classes and attribute mapping details.
  • Group Object Classes
    : Select a group object class to see its details. To add a new class, click [
    Add
    ] and then complete the fields below. To remove a class from the list, select it and then click [
    Remove
    ].
  • Object Class Name
    : Enter the name of the group object class.
Map the attributes that are required by the group object class as described below. Mapping group object class attributes associates a Gateway attribute with the corresponding attribute in the LDAP schema.
  • Group Name
    : Enter the attribute of the group object class that specifies the group name. For example, a "cn" attribute specifies the name of the group in the "groupOfUniqueNames" group object class.
  • Group Member
    : Enter the attribute of the group object class that specifies the members of the group. For example, a "uniqueMember" attribute specifies the members of the group in the "groupOfUniqueNames" group object class.
  • Member Strategy
    : Select a member strategy to use from the drop-down list. 
Step 3: User Object Classes
This step defines LDAP user object classes for the provider that is defined in Step 1.
The wizard automatically populates default object classes based on the provider type. Review and modify as necessary.
Consult your LDAP Identity Provider for information about supported user object classes and attribute mapping details.
  • User Object Classes
    : Select a user object class to see its details. To add a new class, click [
    Add
    ] and then complete the fields below. To remove a class from the list, select it and then click [
    Remove
    ].
  • Object Class Name
    : Enter the name of the user object class.
Map the attributes that are required by the user object class as described below. Mapping user object class attributes associates a Gateway attribute with the corresponding attribute in the LDAP schema.
  • User Name
    : Enter the attribute of the user object class that specifies the user name. For example, the “cn” attribute specifies the name of the user in the “inetOrgPerson” user object class.
  • Login Name
    : Enter the attribute of the user object class that specifies the user login name. For example, the “uid” attribute specifies the login name in the "inetOrgPerson” user object class.
    If you are using MSAD (Microsoft Active Directory) as the LDAP provider and you need to support login names greater than 20 characters, change the mapping to "userPrincipalName".
  • Password
    : Enter the attribute of the user object class that specifies the user password. For example, the “userPassword” attribute specifies the user password in the "inetOrgPerson” user object class.
  • First Name
    : Enter the attribute of the user object class that specifies the first name of the user. For example, the "givenName” attribute specifies the first name of the user in the "inetOrgPerson” user object class.
  • Last Name
    : Enter the attribute of the user object class that specifies the last name of the user. For example, the “sn” attribute specifies the last name of the user in the "inetOrgPerson” user object class.
  • Email
    : Enter the attribute of the user object class that specifies the user’s email address. For example, the “mail” attribute specifies the user’s email address in the “inetOrgPerson” user object class.
  • Certificate
    : Enter the attribute of the user object class that contains the user's X.509 certificate. For example, the "userCertificate;binary" attribute specifies the user's X.509 certificate in the "inetOrgPerson" user object class. The wizard prepopulates this value for known certificates such as MSAD, OpenLDAP.
    If there is more than one X.509 certificate present, the Gateway uses the first one only.
This mapping allows the Gateway to use certificates that are stored in the LDAP repository at run time. If not mapped, you must first import the certificate into the Gateway certificate store.
The Gateway indexes all LDAP Identity Providers periodically for new certificates. The indexing interval is specified by the
ldap.certificateIndex.interval
cluster property.
  • Kerberos Principal
    : Enter the attribute of the user object class that specifies the unqualified standard principal name for the user. A standard principal name is in the form "user@REALM"; for this example name, the attribute value would be "user".
  • Kerberos Enterprise Principal
    : Enter the attribute of the user object class that specifies the unqualified enterprise principal name for the user. An enterprise principal name is in the form "user@domain@REALM"; for this example, the attribute value would be "user@domain".
At this point, test the configuration before clicking [
Finish
] to close the wizard. See "Testing the Configuration" later in this topic for details.
Step 4: Advanced Configuration
This step contains advanced settings that may improve performance during LDAP directory look-ups.
These settings are intended for advanced users who are experienced in LDAP directory configuration. Consult your LDAP administrator before changing any of the settings.
Group Options
This section configures group caching and nesting.
  • Cache size
    : Enter the maximum number of groups to cache. The default cache size is
    100
    . A value of '0' disables the cache.
    Base the cache size on the number of groups in frequent use. An overly large cache size actually decreases system performance. For very large number of groups or when groups are used infrequently, consider disabling the cache.
  • Cache maximum age
    : Specify how long to cache each group before the information is discarded.
  • Maximum nesting
    : Enter the number of nested groups to process. A nested group is a group that is a member of another group. You can enter "0" for unlimited group nesting or "1" to disable nesting if nested groups are not used.
    Many levels of group nesting can slow down authentication.
  • Use case insensitive group membership check
    : Select this option to have the Policy Manager ignore case when checking for group membership.
Attribute Options
This section configures the extra attributes to retrieve, or to select all attributes for retrieval. You can use the Extract Attributes for Authenticated User Assertion to retrieve the available attributes.
  • Retrieve all attributes
    : This option retrieves all LDAP attributes.
  • Retrieve mapped and specified attributes only
    : This option lets you specify which attributes to retrieve.
    • To enter an attribute, click [
      Add
      ] and then type the name of the attribute to retrieve.
    • To modify an attribute, select the attribute and then click [
      Modify
      ].
    • To remove an attribute from the list, select the attribute and then click [
      Remove
      ].
Step 5: NTLM Configuration
This step is used to enable NTLM configuration.
Basic Settings
Used to configure the NTLM configuration settings. Fields that are marked with an asterisk (*) are required.
  • Basic Settings
    : Used to configure the NTLM configuration settings. Fields that are marked with an asterisk (*) are required.
  • Server Name
    : Enter the DNS name of the server that is performing the NTLM client authentication.
  • Service Account
    : The computer account that has a trusted delegation to call a Netlogon service via the NTLM protocol.
    Note:
     The Service Account must be in the following format:
    <
    computerAccountName>
    $@
    <domainName>
    .
  • Service Password
    : Choose the service password from the drop-down list. If the password you require is not listed, click [
    Manage Stored Passwords
    ] to add it to the Gateway password storage. For more information, see Manage Stored Passwords.
    You cannot type the password directly here; it must be defined in the Gateway secure password storage.
  • Domain DNS Name
    : Optionally, enter the DNS name of the authenticating domain.
  • Domain Netbios Name
    : Enter the Windows name of the authenticating domain.
  • Host DNS Name
    : Enter the DNS name of the host. In most cases, this is the name of the Gateway.
  • Host Netbios Name
    : Enter the required Windows name of the computer account.
    Once the Basic Settings are complete, you can either click [
    Test Connection
    ] to verify the NTLM configuration or click [
    Next
    ] to proceed to step 6.
Advanced Settings
This section is used to add, edit, or remove any additional settings that are required to configure the NTLM protocol. This section is intended for advanced users.
Error Conditions
The following error conditions can be returned by the Gateway:
  • 401 - Unauthorized:
    This indicates that NTLM data was not present or not accepted yet.
  • 402 - Authentication Failed:
     This indicates that the client has presented invalid credentials.
Step 6: Certificate Settings
This step is used to configure certificate settings for the LDAP identity provider.
Client Certificates 
Select how certificates are used in an LDAP:
  • Do not use certificates from this directory
    : Choose this option if certificates are not used from this directory.
  • Scan and index certificates in this directory
    : Choose this option if certificate indexing should be enabled.
  • Scan and index certificates in this directory with search filter
    : Choose this option if custom certificate indexing should be enabled. Enter the search filter for extracting the certificates from the directory.
    An example of a simplistic filter for a single certificate attribute:
    (<USER_CERTIFICATE_ATTRIBUTE>=*)
    An example of a simplistic filter for multiple certificate attributes:
    (|(<USER_CERT_ATTRIB1>=*)(<USER_CERT_ATTRIB2>=*)...)
    Only user certificate attributes are returned from the search. The search filter is in effect when you use the [
    Test
    ] button.
  •  
    Search for certificates in this directory
    : Choose this option if certificate lookup should be enabled. You can search for certificates based on:
    • Issuer Name and Serial Number or Subject Key Identifier
      . The following variables can be used:
      ${issuer}
       : Issuer name in default format
      ${issuer.canonical}
       : Issuer name in canonical format
      ${issuer.rfc2253}
       : Issuer name in RFC 2253 format
      ${serialNumber}
       : Serial number
    • Subject Key Identifier
      . The following variables can be used:
      ${subjectKeyIdentifier}
       : Subject Key Identifier in Base 64 format
      ${subjectKeyIdentifier.hex}
       : Subject Key Identifier in hexadecimal string format
The [
Test
] button only validates the syntax of the search filters. It cannot fully test the search string because actual values are not available to insert into the filter.
Examples of search filters
The following filter finds an object that has a
userCertificate
 attribute based on serial number and issuer. It assumes the directory supports RFC4523:
(&(objectclass=inetOrgPerson)(userCertificate={serialNumber ${serialNumber},issuer"${issuer}"}))
You could use the following syntax for either OpenLDAP or Oracle Internet Directory 10g Release 2 or later:
(&(objectclass=inetOrgPerson)(usercertificate=${serialNumber}$${issuer}))
The '$' is the separator for serialNumber and issuer.
Certificate Validation Options
This section specifies how certificates for this LDAP Identity Provider should be validated:
  • Use Default
    : Use the method that is defined for Identity Providers, as described in the Manage Certificate Validation dialog. Use the default method unless there is a specific need to override it for this Identity Provider.
  • Validate
    : Ensure that the certificate is valid and trusted.
  • Validate Certificate Path
    : Ensure that the certificate path is valid to a trust anchor.
  • Revocation Checking
    : Validate the certificate path and perform revocation checking according to the revocation checking policies.
Member Strategies
The following table describes the different member strategies available. These strategies are used in Step 2 of the wizard.
Strategy
Description
Complications
Member is User DN
Every value of the group's member attribute is a fully formed DN (distinguished name) that is unique within the search base.
When selected, the corresponding attribute in the Group Member field should be something like "cn=user,dc=companyx,dc=com".
Member is User Login
Every value of the group's member attribute is a unique attribute of a user in the directory.
When selected, the corresponding attribute in the Group Member field should be "user".
Member is NV Pair
Every value of the group's member attribute is a name=value pair such as "firstinitiallastname."
When selected, the corresponding attribute in the Group Member field should be "cn=user".
OU Group
If configuring an "organizationalUnit" group object class, then you must associate users to a group.
When an "ou" attribute is entered in the Group Name field, the membership of a user is not described in the group itself but rather by the DN of the user. For example, the Group Name attribute "ou=group,dc=companyx,dc=com" hints at the members. But if you come across a user "cn=user,ou=group,dc=companyx,dc=com," then "user" is a member of that group. When selected, no attribute in the Group Member field is required because the group members are implied by their DN. If their DN includes the "ou", then the members are automatically considered part of the group.
Testing and Troubleshooting the Configuration
Click [
Test
] to verify the configuration before completing the wizard. You should see a message validating the configuration of the LDAP Identity Provider. If an error message displays instead, note the configuration problems and take the appropriate corrective actions:
Configuration Error
Suggested Solution
Connection error
Return to Step 1 of the wizard and verify that all connection details are correct.
Group member retrieval warnings
Two possible solutions:
  • Return to Step 2 of the wizard and adjust the group object class mappings
  • Leave the mappings are they are. Even with the warning, the Gateway can still connect to the LDAP Identity Provider.
User retrieval error
Return to Step 3 of the wizard and fix the incorrect user object class mappings.
Click
Finish 
when done. The new LDAP Identity Provider appears in the Identity Providers tab of the Policy Manager interface. 

Content feedback and comments