Merge pull request #33677 from karel-harjono/enhance-user-registry-api

  1. added `getAttributesForUser()` and `getUsersByAttribute()` UserRegistry API as default methods.
  2. updated internal SearchBridge to get the user attribute information. 
  3. added FAT tests for `getAttributesForUser()` and `getUsersByAttribute()`.
  4. general code review changes.

Author: karel-harjono

dev/com.ibm.websphere.appserver.api.basics/bnd.bnd

@@ -1,5 +1,5 @@
 #*******************************************************************************
-# Copyright (c) 2017, 2022 IBM Corporation and others.
+# Copyright (c) 2017, 2026 IBM Corporation and others.
 # All rights reserved. This program and the accompanying materials
 # are made available under the terms of the Eclipse Public License 2.0
 # which accompanies this distribution, and is available at
@@ -11,7 +11,7 @@
 #     IBM Corporation - initial API and implementation
 #*******************************************************************************
 -include= ~../cnf/resources/bnd/bundle.props
-bVersion: 1.4
+bVersion: 1.5
 
 Bundle-Name: WebSphere Application Manager API
 Bundle-Description: WebSphere Application Manager API, version ${bVersion}

dev/com.ibm.websphere.appserver.features/visibility/protected/com.ibm.websphere.appserver.appmanager-1.0.feature

@@ -22,7 +22,7 @@ IBM-Process-Types: server, \
  com.ibm.ws.app.manager.ready; start-phase:=APPLICATION
 -jars=com.ibm.websphere.appserver.api.basics; location:="dev/api/ibm/,lib/",\
  com.ibm.websphere.appserver.spi.application; location:=dev/spi/ibm/
--files=dev/api/ibm/javadoc/com.ibm.websphere.appserver.api.basics_1.4-javadoc.zip, \
+-files=dev/api/ibm/javadoc/com.ibm.websphere.appserver.api.basics_1.5-javadoc.zip, \
  dev/spi/ibm/javadoc/com.ibm.websphere.appserver.spi.application_1.1-javadoc.zip
 kind=ga
 edition=core

dev/com.ibm.websphere.security/src/com/ibm/websphere/security/UserRegistry.java

@@ -15,6 +15,8 @@
 import java.rmi.RemoteException;
 import java.security.cert.X509Certificate;
 import java.util.List;
+import java.util.Map;
+import java.util.Set;
 
 /**
  * Registries. This should extend java.rmi.Remote as the registry can be in
@@ -393,4 +395,43 @@ public interface UserRegistry extends java.rmi.Remote {
      *
      **/
     public com.ibm.websphere.security.cred.WSCredential createCredential(String userSecurityName) throws NotImplementedException, EntryNotFoundException, CustomRegistryException, RemoteException;
+
+    /**
+     * Returns the attributes for <i>userSecurityName</i>.
+     *
+     * @param userSecurityName the name of the user.
+     * @param attributeNames
+     * @return a Map of attributes for the user.
+     *         <code>null</code> is not returned.
+     * @exception EntryNotFoundException  if userSecurityName does not exist.
+     * @exception CustomRegistryException if there is any registry specific problem
+     **/
+    @Deprecated
+    default Map<String, Object> getAttributesForUser(String userSecurityName, Set<String> attributeNames) throws EntryNotFoundException, CustomRegistryException, NotImplementedException {
+        throw new NotImplementedException("Reading user attributes is not supported.");
+    }
+
+    /**
+     * Gets a list of users that match an <i>attributeName</i> with specified
+     * <i>value</i> in the UserRegistry.
+     * The maximum number of users returned is defined by the <i>limit</i>
+     * argument. This is very useful in situations where there are thousands of
+     * users in the UserRegistry and getting all of them at once is not
+     * practical.
+     *
+     * @param attributeName the attributeName to match.
+     * @param value         the value of the attributeName to match.
+     * @param limit         the maximum number of users that should be returned.
+     *                          A value of 0 implies get all the users.
+     *                          Specifying a negative value returns an empty Result.
+     * @return a <i>Result</i> object that contains the list of users
+     *         requested and a flag to indicate if more users exist.
+     *         <code>null</code> is not returned.
+     * @exception CustomRegistryException if there is any UserRegistry specific problem
+     **/
+    @Deprecated
+    default Result getUsersByAttribute(String attributeName, String value, int limit) throws CustomRegistryException, NotImplementedException {
+        throw new NotImplementedException("Finding users from their attributes is not supported.");
+    }
+
 }

dev/com.ibm.websphere.security/src/com/ibm/websphere/security/package-info.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2011,2018 IBM Corporation and others.
+ * Copyright (c) 2011, 2026 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
  * which accompanies this distribution, and is available at
@@ -11,7 +11,7 @@
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
 /**
- * @version 1.2.0
+ * @version 1.3.0
  */
-@org.osgi.annotation.versioning.Version("1.2.0")
+@org.osgi.annotation.versioning.Version("1.3.0")
 package com.ibm.websphere.security;

dev/com.ibm.ws.security.registry/src/com/ibm/ws/security/registry/UserRegistry.java

@@ -15,6 +15,8 @@
 import java.rmi.RemoteException;
 import java.security.cert.X509Certificate;
 import java.util.List;
+import java.util.Map;
+import java.util.Set;
 
 /**
  * Defines read-only API contract for UserRegistry implementations.
@@ -282,4 +284,45 @@ public SearchResult getUsersForGroup(String groupSecurityName,
      **/
     List<String> getGroupsForUser(String userSecurityName) throws EntryNotFoundException, RegistryException;
 
+    /**
+     * Returns the attributes for <i>userSecurityName</i>.
+     *
+     * @param userSecurityName the name of the user.
+     * @param attributeNames
+     * @return a Map of attributes for the user.
+     *         <code>null</code> is not returned.
+     * @exception EntryNotFoundException   if userSecurityName does not exist or is not unique.
+     * @exception RegistryException        if there is any UserRegistry specific problem
+     * @exception IllegalArgumentException if userSecurityName is <code>null</code> or empty
+     **/
+    @Deprecated
+    default Map<String, Object> getAttributesForUser(String userSecurityName, Set<String> attributeNames) throws EntryNotFoundException, RegistryException, NotImplementedException {
+        throw new NotImplementedException("Reading user attributes is not supported.");
+    }
+
+    /**
+     * Gets a list of users that match an <i>attributeName</i> with specified
+     * <i>value</i> in the UserRegistry.
+     * The maximum number of users returned is defined by the <i>limit</i>
+     * argument. This is very useful in situations where there are thousands of
+     * users in the UserRegistry and getting all of them at once is not
+     * practical.
+     *
+     * @param attributeName the attributeName to match.
+     * @param value         the value of the attributeName to match.
+     * @param limit         the maximum number of users that should be returned.
+     *                          A value of 0 implies get all the users.
+     *                          Specifying a negative value returns an empty SearchResult.
+     * @return a <i>SearchResult</i> object that contains the list of users
+     *         requested and a flag to indicate if more users exist.
+     *         <code>null</code> is not returned.
+     * @exception RegistryException        if there is any UserRegistry specific problem
+     * @exception IllegalArgumentException if attributeName is <code>null</code> or empty
+     * @exception IllegalArgumentException if value is <code>null</code> or empty
+     **/
+    @Deprecated
+    default SearchResult getUsersByAttribute(String attributeName, String value, int limit) throws RegistryException, NotImplementedException {
+        throw new NotImplementedException("Reading user from attributes is not supported.");
+    }
+
 }

dev/com.ibm.ws.security.registry/src/com/ibm/ws/security/registry/internal/UserRegistryWrapper.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2012 IBM Corporation and others.
+ * Copyright (c) 2012, 2026 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
  * which accompanies this distribution, and is available at
@@ -15,7 +15,9 @@
 import java.rmi.RemoteException;
 import java.security.cert.X509Certificate;
 import java.util.List;
+import java.util.Map;
 import java.util.Properties;
+import java.util.Set;
 
 import com.ibm.websphere.ras.annotation.Sensitive;
 import com.ibm.websphere.security.CertificateMapFailedException;
@@ -290,4 +292,37 @@ public Result getUsersForGroup(String groupSecurityName, int limit) throws NotIm
     public WSCredential createCredential(String userSecurityName) throws NotImplementedException, EntryNotFoundException, CustomRegistryException, RemoteException {
         throw new NotImplementedException("The createCredential method is not available");
     }
+
+    @Override
+    public Map<String, Object> getAttributesForUser(String userSecurityName, Set<String> attributeNames) throws EntryNotFoundException, CustomRegistryException, NotImplementedException {
+        try {
+            return wrappedUr.getAttributesForUser(userSecurityName, attributeNames);
+        } catch (RegistryException e) {
+            throw new CustomRegistryException(e.getMessage(), e);
+        } catch (com.ibm.ws.security.registry.EntryNotFoundException e) {
+            throw new EntryNotFoundException(e.getMessage(), e);
+        } catch (com.ibm.ws.security.registry.NotImplementedException e) {
+            throw new NotImplementedException(e.getMessage(), e);
+        }
+
+    }
+
+    @Override
+    public Result getUsersByAttribute(String attributeName, String value, int limit) throws CustomRegistryException, NotImplementedException {
+        try {
+            SearchResult ret = wrappedUr.getUsersByAttribute(attributeName, value, limit);
+            Result result = new Result();
+            result.setList(ret.getList());
+            if (ret.hasMore()) {
+                result.setHasMore();
+            }
+            return result;
+
+        } catch (RegistryException e) {
+            throw new CustomRegistryException(e.getMessage(), e);
+        } catch (com.ibm.ws.security.registry.NotImplementedException e) {
+            throw new NotImplementedException(e.getMessage(), e);
+        }
+    }
+
 }

dev/com.ibm.ws.security.registry/src/com/ibm/ws/security/registry/internal/package-info.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2011 IBM Corporation and others.
+ * Copyright (c) 2011, 2026 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
  * which accompanies this distribution, and is available at
@@ -12,9 +12,9 @@
  *******************************************************************************/
 
 /**
- * @version 1.0
+ * @version 1.1.0
  */
-@org.osgi.annotation.versioning.Version("1.0")
+@org.osgi.annotation.versioning.Version("1.1.0")
 @TraceOptions(traceGroup = TraceConstants.TRACE_GROUP, messageBundle = TraceConstants.MESSAGE_BUNDLE)
 package com.ibm.ws.security.registry.internal;
 

dev/com.ibm.ws.security.registry/src/com/ibm/ws/security/registry/package-info.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2011 IBM Corporation and others.
+ * Copyright (c) 2011, 2026 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
  * which accompanies this distribution, and is available at
@@ -12,9 +12,9 @@
  *******************************************************************************/
 
 /**
- * @version 1.0
+ * @version 1.1.0
  */
-@org.osgi.annotation.versioning.Version("1.0")
+@org.osgi.annotation.versioning.Version("1.1.0")
 @TraceOptions(traceGroup = "UserRegistry", messageBundle = "com.ibm.ws.security.registry.internal.resources.LoggingMessages")
 package com.ibm.ws.security.registry;
 

dev/com.ibm.ws.security.registry_test.servlet/src/com/ibm/ws/security/registry/test/UserRegistryServletConnection.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2011,2018 IBM Corporation and others.
+ * Copyright (c) 2011, 2026 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
  * which accompanies this distribution, and is available at
@@ -25,7 +25,10 @@
 import java.security.PrivilegedExceptionAction;
 import java.security.cert.X509Certificate;
 import java.util.ArrayList;
+import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
+import java.util.Set;
 import java.util.logging.Level;
 import java.util.logging.Logger;
 
@@ -255,6 +258,35 @@ private List<String> convertToList(String methodName, String str) {
         }
     }
 
+    /**
+     * @param methodName
+     * @param str
+     * @return
+     */
+    private Map<String, Object> convertToMap(String methodName, String str) {
+        /*
+         * Something unlikely to occur in a DN, yet still readable. If this value changes
+         * remember to update UserRegistryServlet#convertFromList() as well.
+         */
+        final String delimiter = " :: ";
+
+        Map<String, Object> map = new HashMap<>();
+        if (str.startsWith("{") && str.endsWith("}")) {
+            if (str.length() == 2) {
+                return map;
+            } else {
+                String[] contents = str.substring(1, str.length() - 1).split(delimiter);
+                for (String entry : contents) {
+                    String[] mapEntry = entry.split("=");
+                    map.put(mapEntry[0], mapEntry[1]);
+                }
+                return map;
+            }
+        } else {
+            throw new IllegalStateException(methodName + "expected {...}, but was: " + str);
+        }
+    }
+
     /**
      * @param methodName
      * @param str
@@ -451,4 +483,25 @@ public String getType() {
         return makeServletMethodCall(methodName, servletRequest);
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public Map<String, Object> getAttributesForUser(String userSecurityName, Set<String> attributeNames) throws EntryNotFoundException, RegistryException {
+        String methodName = "getAttributesForUser";
+        String servletRequest = "?method=" + methodName +
+                "&userSecurityName=" + encodeForURI(userSecurityName) + "&attributeNames=" + String.join(",", attributeNames);
+        String servletResponse = makeServletMethodCallWithExceptions(methodName, servletRequest);
+
+        return convertToMap(methodName, servletResponse);
+    }
+
+    /** {@inheritDoc} */
+    @Override
+    public SearchResult getUsersByAttribute(String attributeName, String value, int limit) throws RegistryException {
+        String methodName = "getUsersByAttribute";
+        String servletRequest = "?method=" + methodName +
+                "&attributeName=" + encodeForURI(attributeName) + "&value=" + value + "&limit=" + limit;
+        String servletResponse = makeServletMethodCallWithException(methodName, servletRequest);
+
+        return convertToSearchResult(methodName, servletResponse);
+    }
 }

dev/com.ibm.ws.security.registry_test.servlet/test-applications/userRegistry/src/web/UserRegistryServlet.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2011, 2021 IBM Corporation and others.
+ * Copyright (c) 2011, 2026 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
  * which accompanies this distribution, and is available at
@@ -18,7 +18,10 @@
 import java.rmi.RemoteException;
 import java.security.AccessController;
 import java.security.PrivilegedAction;
+import java.util.Arrays;
 import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
 
 import javax.servlet.Servlet;
 import javax.servlet.ServletException;
@@ -219,6 +222,18 @@ private void handleMethodRequest(HttpServletRequest req, PrintWriter pw, UserReg
                 String groupSecurityName = req.getParameter("groupSecurityName");
                 int limit = Integer.valueOf(req.getParameter("limit"));
                 response = convertFromSR(ur.getUsersForGroup(groupSecurityName, limit));
+            } else if ("getAttributesForUser".equals(method)) {
+                String userSecurityName = req.getParameter("userSecurityName");
+                String attributeNames = req.getParameter("attributeNames");
+                response = convertFromMap(ur.getAttributesForUser(
+                        userSecurityName,
+                        Arrays.stream(attributeNames.split(",")).collect(Collectors.toSet())
+                )).replaceAll("\n", "");
+            } else if ("getUsersByAttribute".equals(method)) {
+                String attributeName = req.getParameter("attributeName");
+                String value = req.getParameter("value");
+                int limit = Integer.parseInt(req.getParameter("limit"));
+                response = convertFromSR(ur.getUsersByAttribute(attributeName, value, limit));
             } else {
                 pw.println("Usage: url?method=name&paramName=paramValue&...");
             }
@@ -317,6 +332,38 @@ private static String convertFromList(List<?> results) {
         return sb.toString();
     }
 
+    private static String convertFromMap(Map<String, ?> map) {
+        System.out.println("UserRegistryServlet.convertFromMap(): " + map.getClass() + " " + map);
+
+        if (map.isEmpty()) {
+            return "{}";
+        }
+
+        /*
+         * Something unlikely to occur in a DN, yet still readable. If this value changes
+         * remember to update UserRegistryServletConnection#convertToList() as well.
+         */
+        final String delimiter = " :: ";
+
+        StringBuilder sb = new StringBuilder();
+        sb.append('{');
+
+        int idx = 0;
+        for (Map.Entry<String, ?> entry : map.entrySet()) {
+            sb.append(entry.getKey());
+            sb.append('=');
+            sb.append(entry.getValue());
+
+            if (idx < map.size() - 1) {
+                sb.append(delimiter);
+            }
+            idx++;
+        }
+
+        sb.append('}');
+        return sb.toString();
+    }
+
     /**
      * Create a DN safe string representation of a SearchResult. The problem with just
      * using the List.toString() method is that it separates entries by a ", ". That