docs: @FFDCIgnore({ EntityNotFoundException.class, com.ibm.websphere.security.CertificateMapNotSupportedException.class,
                    com.ibm.websphere.security.CertificateMapFailedException.class })
      private LdapEntry mapCertificate(X509Certificate[] certs, LdapSearchControl srchCtrl) throws WIMException {
          LdapEntry result = null;
  
          String dn = null;
          String filter = null;
          String certMapMode = iLdapConfigMgr.getCertificateMapMode();
  
          if (ConfigConstants.CONFIG_VALUE_CERT_NOT_SUPPORTED_MODE.equalsIgnoreCase(certMapMode)) {
              if (tc.isDebugEnabled()) {
                  Tr.debug(tc, "Certificate authentication has been disabled for this LDAP registry.");
              }
              String msg = Tr.formatMessage(tc, WIMMessageKey.LDAP_REGISTRY_CERT_IGNORED);
              throw new CertificateMapNotSupportedException(WIMMessageKey.LDAP_REGISTRY_CERT_IGNORED, msg);
          } else if (ConfigConstants.CONFIG_VALUE_CUSTOM_MODE.equalsIgnoreCase(certMapMode)) {
              String mapping;
              try {
                  X509CertificateMapper mapper = iCertificateMapperRef.get();
                  if (mapper == null) {
                      String msg = Tr.formatMessage(tc, WIMMessageKey.LDAP_REGISTRY_MAPPER_NOT_BOUND);
                      throw new CertificateMapFailedException(WIMMessageKey.LDAP_REGISTRY_MAPPER_NOT_BOUND, msg);
                  }
  
                  if (tc.isDebugEnabled()) {
                      Tr.debug(tc, "Using custom X.509 certificate mapper: " + mapper.getClass());
                  }
  
                  mapping = mapper.mapCertificate(certs);
                  if (tc.isDebugEnabled()) {
                      Tr.debug(tc, "The custom X.509 certificate mapper returned the following mapping: " + mapping);
                  }
              } catch (com.ibm.websphere.security.CertificateMapNotSupportedException e) {
                  String msg = Tr.formatMessage(tc, WIMMessageKey.LDAP_REGISTRY_CUSTOM_MAPPER_NOT_SUPPORTED);
                  throw new CertificateMapNotSupportedException(WIMMessageKey.LDAP_REGISTRY_CUSTOM_MAPPER_NOT_SUPPORTED, msg, e);
              } catch (com.ibm.websphere.security.CertificateMapFailedException e) {
                  String msg = Tr.formatMessage(tc, WIMMessageKey.LDAP_REGISTRY_CUSTOM_MAPPER_FAILED);
                  throw new CertificateMapFailedException(WIMMessageKey.LDAP_REGISTRY_CUSTOM_MAPPER_FAILED, msg, e);
              }
  
              /*
               * The mapper should return some value.
               */
              if (mapping == null || mapping.trim().isEmpty()) {
                  String msg = Tr.formatMessage(tc, WIMMessageKey.LDAP_REGISTRY_INVALID_MAPPING);
                  throw new CertificateMapFailedException(WIMMessageKey.LDAP_REGISTRY_INVALID_MAPPING, msg);
              }
  
              /*
               * If in the form of a distinguished name
               */
              dn = LdapHelper.getValidDN(mapping);
              if (dn == null) {
                  filter = mapping;
              }
          } else if (ConfigConstants.CONFIG_VALUE_FILTER_DESCRIPTOR_MODE.equalsIgnoreCase(certMapMode)) {
              filter = iLdapConfigMgr.getCertificateLDAPFilter(certs[0]).trim();
          } else {
              dn = LdapHelper.getValidDN(certs[0].getSubjectX500Principal().getName());
          }
  
          /*
           * Try and validate the user with the LDAP server.
           */
          if (dn != null) {
              /*
               * We have a distinguished name. Search for the user directly.
               */
              try {
                  result = iLdapConn.getEntityByIdentifier(dn, null, null, null, srchCtrl.getPropertyNames(), false,
                                                           false);
              } catch (EntityNotFoundException e) {
                  /* User not found in this repository. */
              }
          } else {
              /*
               * We have a search filter. Search over all the base entries.
               */
              String[] searchBases = srchCtrl.getBases();
              int countLimit = srchCtrl.getCountLimit();
              int timeLimit = srchCtrl.getTimeLimit();
              List<String> entityTypes = srchCtrl.getEntityTypes();
              List<String> propNames = srchCtrl.getPropertyNames();
              int scope = srchCtrl.getScope();
  
              int count = 0;
              for (int i = 0; i < searchBases.length; i++) {
                  try {
                      Set<LdapEntry> ldapEntries = iLdapConn.searchEntities(searchBases[i], filter, null, scope, entityTypes,
                                                                            propNames, false, false, countLimit, timeLimit);
                      if (ldapEntries.size() > 1) {
                          //Uncomment this when MULTIPLE_PRINCIPALS_FOUND is added to LdapUtilMesssages.nlsprops
                          /*
                           * if(tc.isErrorEnabled()){
                           * Tr.error(tc, WIMMessageKey.MULTIPLE_PRINCIPALS_FOUND, WIMMessageHelper.generateMsgParms(sFilter));
                           * }
                           */
                          String msg = Tr.formatMessage(tc, WIMMessageKey.MULTIPLE_PRINCIPALS_FOUND, WIMMessageHelper.generateMsgParms(filter));
                          throw new CertificateMapFailedException(WIMMessageKey.MULTIPLE_PRINCIPALS_FOUND, msg);
                      } else if (ldapEntries.size() == 1) {
                          if (count == 0) {
                              result = ldapEntries.iterator().next();
                          }
                          count++;
                          if (count > 1) {
                              //Uncomment this when MULTIPLE_PRINCIPALS_FOUND is added to LdapUtilMesssages.nlsprops
                              /*
                               * if(tc.isErrorEnabled()){
                               * Tr.error(tc, WIMMessageKey.MULTIPLE_PRINCIPALS_FOUND, WIMMessageHelper.generateMsgParms(sFilter));
                               * }
                               */
                              String msg = Tr.formatMessage(tc, WIMMessageKey.MULTIPLE_PRINCIPALS_FOUND, WIMMessageHelper.generateMsgParms(filter));
                              throw new CertificateMapFailedException(WIMMessageKey.MULTIPLE_PRINCIPALS_FOUND, msg);
                          }
                      }
                  } catch (EntityNotFoundException e) {
                      /* User not found in this search base. */
                      continue;
                  }
              }
          }
  
          return result;
      }