CA API Gateway 9.1

9.4 9.1

LDAP Identity Provider Wizard

This topic describes about the LDAP Identity Provider Wizard that helps you add or edit an LDAP Identity Provider in the Federated Gateway B.
gateway83
This topic describes about the LDAP Identity Provider Wizard that helps you add or edit an LDAP Identity Provider in the Federated Gateway B.
 
When the [
Test
] button is available, you can click it to test your configuration at any time.
 
Step 1: Provider Configuration
This step defines the LDAP Identity Provider details.
Configure this step as follows:
  1. Select the LDAP Identity Provider type from the Provider Type drop-down list.
  2. Complete the following details. Fields marked with an asterisk (*) are required.
  3. 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.
  4. 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.
  5. 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. Note that 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. If there are no LDAP(S) connections, then the Client Certification options will have no effect.
    • 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.
      Tip:
       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.
    • 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 defined in Step 1.
The wizard automatically populates default object classes based on the provider type. Review and modify as necessary.
 If unsure, you should consult your LDAP Identity Provider for information about supported group object classes and attribute mapping details before modifying this list.
  • 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 required by the group object class as described below. Mapping group object class attributes associates a 
API 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 defined in Step 1.
The wizard automatically populates default object classes based on the provider type. Review and modify as necessary.
If unsure, you should consult your LDAP Identity Provider for information about supported user object classes and attribute mapping details before modifying this list.
  • 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 required by the user object class as described below. Mapping user object class attributes associates a 
API 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 will prepopulate 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 enables certificates stored in the LDAP repository to be used by the
API Gateway
 at run time, rather than requiring you to first import the certificate into the
API Gateway
 certificate store. All LDAP Identity Providers are periodically indexed for new certificates based on the interval 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". The default is sAMAccountName.
  • 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". The default is userPrincipalName.
At this point, test the configuration before clicking [
Finish
] to close the wizard. See Testing the Configuration for details.
Step 4: Advanced Configuration
This step contains advanced settings that may improve performance during LDAP directory lookups.
These settings are intended for advanced users experienced in LDAP directory configuration. Consult your LDAP administrator before changing any of the settings.
There are two sections in this step:
  • Group Options
    : Used to configure group caching and nesting.
    • Cache size
      : Enter the maximum number of groups to cache. The default cache size is 100.
The cache size should be based on the number of groups in frequent use. Setting 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.
      Having 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
    : Used to configure 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.
There are two sections in this step:
  • Basic Settings
    : Used to configure the NTLM configuration settings. Fields 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
      API Gateway
       password storage. For more information, see Manage Stored Passwords.
      You cannot type the password directly here; it must be defined in the
      API 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
      API 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 required to configure the NTLM protocol. This section is intended for advanced users.
Error Conditions
The following error conditions can be returned by the
API 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>=*)...)
    The attributes returned from the search are only the user certificate attributes. The search filter is included in the testing when the [
    Test
    ] button is clicked.
  •  
    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 hexidecimal string format
The [
Test
] button will only validate 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 if the directory supports RFC4523:
(&( objectclass = inetOrgPerson )( userCertificate = { serialNumber ${serialNumber},issuer "${issuer}" } ))
You could use the following syntax for either Open LDAP or Oracle Internet Directory 10g Release 2 or later:
(&( objectclass = inetOrgPerson )( usercertificate=${serialNumber}$${issuer} ))
Note that '$' is the separator for serialNumber and issuer.
The search string examples shown above include spaces to enhance readability. Actual search strings should not contain any spaces, except between name/values such as serialNumber ${serialNumber}.
Certificate Validation Options
This section specifies how certificates for this LDAP Identity Provider should be validated:
  • Use Default
    : Use the method defined for Identity Providers, as described under Manage Certificate Validation.
  • 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 (distinguished name) of the user. For example, the Group Name attribute "ou=group,dc=companyx,dc=com" hints at what the members are, 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, and if their DN includes the "ou", then the members are automatically considered part of the group.
Testing 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
Either return to Step 2 of the wizard and adjust the group object class mappings, or you can leave the mappings are they are. Even with the warning, the
API Gateway
 will still be able to connect to the LDAP Identity Provider.
User retrieval error
Return to Step 3 of the wizard and fix the incorrect user object class mappings.
Repeat the testing and fixing until no more errors appear. 
Click
Finish 
when done. The new LDAP Identity Provider appears in the [
Identity Providers
] tab.

Content feedback and comments