feat: add an optional search criteria to the get_realm_roles function (#504)

* feat: add an optional search criteria to the get_realm_roles function

* style: reformat code to fix linting error

* test: add unit test for get_realm_roles function with search_text param

README.md

@@ -249,6 +249,9 @@ client = keycloak_admin.get_client(client_id="client_id")
 # Get all roles for the realm or client
 realm_roles = keycloak_admin.get_realm_roles()
 
+# Get all roles for the realm or client that their names includes the searched text
+realm_roles = keycloak_admin.get_realm_roles(search_text="CompanyA_")
+
 # Get all roles for the client
 client_roles = keycloak_admin.get_client_roles(client_id="client_id")
 

src/keycloak/keycloak_admin.py

@@ -2322,7 +2322,7 @@ class KeycloakAdmin:
         )
         return raise_error_from_response(data_raw, KeycloakGetError, expected_codes=[200])
 
-    def get_realm_roles(self, brief_representation=True):
+    def get_realm_roles(self, brief_representation=True, search_text=""):
         """Get all roles for the realm or client.
 
         RoleRepresentation
@@ -2330,14 +2330,24 @@ class KeycloakAdmin:
 
         :param brief_representation: whether to omit role attributes in the response
         :type brief_representation: bool
+        :param search_text: optional search text to limit the returned result.
+        :type search_text: str
         :return: Keycloak server response (RoleRepresentation)
         :rtype: list
         """
+        url = urls_patterns.URL_ADMIN_REALM_ROLES
         params_path = {"realm-name": self.connection.realm_name}
         params = {"briefRepresentation": brief_representation}
         data_raw = self.connection.raw_get(
             urls_patterns.URL_ADMIN_REALM_ROLES.format(**params_path), **params
         )
+
+        # set the search_text path param, if it is a valid string
+        if search_text is not None and search_text.strip() != "":
+            params_path["search-text"] = search_text
+            url = urls_patterns.URL_ADMIN_REALM_ROLES_SEARCH
+
+        data_raw = self.connection.raw_get(url.format(**params_path), **params)
         return raise_error_from_response(data_raw, KeycloakGetError)
 
     def get_realm_role_members(self, role_name, query=None):

src/keycloak/urls_patterns.py

@@ -144,6 +144,7 @@ URL_ADMIN_CLIENT_SCOPES_ADD_MAPPER = URL_ADMIN_CLIENT_SCOPE + "/protocol-mappers
 URL_ADMIN_CLIENT_SCOPES_MAPPERS = URL_ADMIN_CLIENT_SCOPES_ADD_MAPPER + "/{protocol-mapper-id}"
 
 URL_ADMIN_REALM_ROLES = "admin/realms/{realm-name}/roles"
+URL_ADMIN_REALM_ROLES_SEARCH = URL_ADMIN_REALM_ROLES + "?search={search-text}"
 URL_ADMIN_REALM_ROLES_MEMBERS = URL_ADMIN_REALM_ROLES + "/{role-name}/users"
 URL_ADMIN_REALMS = "admin/realms"
 URL_ADMIN_REALM = "admin/realms/{realm-name}"

tests/test_keycloak_admin.py

@@ -1103,6 +1103,12 @@ def test_realm_roles(admin: KeycloakAdmin, realm: str):
     assert "uma_authorization" in role_names, role_names
     assert "offline_access" in role_names, role_names
 
+    # Test get realm roles with search text
+    searched_roles = admin.get_realm_roles(search_text="uma_a")
+    searched_role_names = [x["name"] for x in searched_roles]
+    assert "uma_authorization" in searched_role_names, searched_role_names
+    assert "offline_access" not in searched_role_names, searched_role_names
+
     # Test empty members
     with pytest.raises(KeycloakGetError) as err:
         admin.get_realm_role_members(role_name="does-not-exist")