Add groups functions

README.md

@@ -3,6 +3,8 @@
 Python Keycloak
 ====================
 
+For review- see https://bitbucket.org/agriness/python-keycloak
+
 **python-keycloak** is a Python package providing access to the Keycloak API.
 
 ## Installation
@@ -51,8 +53,7 @@ from keycloak import KeycloakOpenID
 keycloak_openid = KeycloakOpenID(server_url="http://localhost:8080/auth/",
                     client_id="example_client",
                     realm_name="example_realm",
-                    client_secret_key="secret",
-                    verify=True)
+                    client_secret_key="secret")
 
 # Get WellKnow
 config_well_know = keycloak_openid.well_know()

keycloak/exceptions.py

@@ -68,7 +68,7 @@ class KeycloakInvalidTokenError(KeycloakOperationError):
     pass
 
 
-def raise_error_from_response(response, error, expected_code=200):
+def raise_error_from_response(response, error, expected_code=200, skip_exists=False):
 
     if expected_code == response.status_code:
         if expected_code == requests.codes.no_content:
@@ -79,6 +79,9 @@ def raise_error_from_response(response, error, expected_code=200):
         except JSONDecodeError as e:
             return response.content
 
+    if skip_exists and response.status_code == 409:
+        return {"Already exists"}
+
     try:
         message = response.json()['message']
     except (KeyError, ValueError):

keycloak/keycloak_admin.py

@@ -15,9 +15,12 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+# Unless otherwise stated in the comments, "id", in e.g. user_id, refers to the internal Keycloak server ID, usually a uuid string
+
 from .urls_patterns import URL_ADMIN_USERS_COUNT, URL_ADMIN_USER, URL_ADMIN_USER_CONSENTS, \
     URL_ADMIN_SEND_UPDATE_ACCOUNT, URL_ADMIN_RESET_PASSWORD, URL_ADMIN_SEND_VERIFY_EMAIL, URL_ADMIN_GET_SESSIONS, \
-    URL_ADMIN_SERVER_INFO, URL_ADMIN_CLIENTS, URL_ADMIN_CLIENT, URL_ADMIN_CLIENT_ROLES, URL_ADMIN_REALM_ROLES, URL_ADMIN_USER_CLIENT_ROLES
+    URL_ADMIN_SERVER_INFO, URL_ADMIN_CLIENTS, URL_ADMIN_CLIENT, URL_ADMIN_CLIENT_ROLES, URL_ADMIN_REALM_ROLES, URL_ADMIN_USER_CLIENT_ROLES, \
+    URL_ADMIN_GROUP, URL_ADMIN_GROUPS, URL_ADMIN_GROUP_CHILD, URL_ADMIN_USER_GROUP, URL_ADMIN_USER_PASSWORD, URL_ADMIN_GROUP_PERMISSIONS
 from .keycloak_openid import KeycloakOpenID
 
 from .exceptions import raise_error_from_response, KeycloakGetError
@@ -106,14 +109,14 @@ class KeycloakAdmin:
         data_raw = self.connection.raw_get(URL_ADMIN_USERS.format(**params_path), **query)
         return raise_error_from_response(data_raw, KeycloakGetError)
 
-    def create_user(self, username, email='', firstName='', lastName='', emailVerified=False, enabled=True):
+    def create_user(self, username, email='', firstName='', lastName='', emailVerified=False, enabled=True, password=None, passwordTemp=False, skip_exists=False):
         """
         Create a new user Username must be unique
 
         UserRepresentation
         http://www.keycloak.org/docs-api/3.3/rest-api/index.html#_userrepresentation
 
-        :param payload: UserRepresentation
+        :param data: Http response
 
         """
         data={}
@@ -124,9 +127,29 @@ class KeycloakAdmin:
         data["emailVerified"]=emailVerified
         data["enabled"]=enabled
         params_path = {"realm-name": self.realm_name}
+
+        exists = self.get_user_id(username=username)
+
+        if exists is not None:
+            return str(exists)
+
         data_raw = self.connection.raw_post(URL_ADMIN_USERS.format(**params_path),
                                             data=json.dumps(data))
-        return raise_error_from_response(data_raw, KeycloakGetError, expected_code=201)
+        create_resp = raise_error_from_response(data_raw, KeycloakGetError, expected_code=201, skip_exists=skip_exists)
+
+        if password is not None:
+            user_id = self.get_user_id(username)
+            data={}
+            data["value"]=password
+            data["type"]="password"
+            data["temporary"]=passwordTemp
+
+            params_path = {"realm-name": self.realm_name, "id": user_id}
+            data_raw = self.connection.raw_put(URL_ADMIN_USER_PASSWORD.format(**params_path),
+                                                data=json.dumps(data))
+            return raise_error_from_response(data_raw, KeycloakGetError, expected_code=204)
+        else:
+            return create_resp
 
     def users_count(self):
         """
@@ -148,16 +171,16 @@ class KeycloakAdmin:
         clientId in UserRepresentation
         http://www.keycloak.org/docs-api/3.3/rest-api/index.html#_userrepresentation
 
-        :return: user_id (uuid as string)
+        :return: user_id
         """
         params_path = {"realm-name": self.realm_name, "username": username}
         data_raw = self.connection.raw_get(URL_ADMIN_USERS.format(**params_path))
         data_content = raise_error_from_response(data_raw, KeycloakGetError)
 
         for user in data_content:
-          thisusername = json.dumps(user["username"]).strip('"')
-          if thisusername == username:
-            return json.dumps(user["id"]).strip('"')
+            thisusername = json.dumps(user["username"]).strip('"')
+            if thisusername == username:
+                return json.dumps(user["id"]).strip('"')
 
         return None
 
@@ -175,12 +198,12 @@ class KeycloakAdmin:
         data_raw = self.connection.raw_get(URL_ADMIN_USER.format(**params_path))
         return raise_error_from_response(data_raw, KeycloakGetError)
 
-    def update_user(self, user_id, username, email='', firstName='', lastName='', emailVerified=False, enabled=True):
+    def update_user(self, user_id, username, email='', firstName='', lastName='', emailVerified=False, enabled=True, password=None, passwordTemp=False):
         """
         Update the user
 
         :param user_id: User id
-        :param payload: UserRepresentation
+        :param data: UserRepresentation
 
         :return: Http response
         """
@@ -191,11 +214,24 @@ class KeycloakAdmin:
         data["lastName"]=lastName
         data["emailVerified"]=emailVerified
         data["enabled"]=enabled
-        params_path = {"realm-name": self.realm_name}
         params_path = {"realm-name": self.realm_name, "id": user_id}
         data_raw = self.connection.raw_put(URL_ADMIN_USER.format(**params_path),
                                            data=json.dumps(data))
-        return raise_error_from_response(data_raw, KeycloakGetError, expected_code=204)
+        update_resp = raise_error_from_response(data_raw, KeycloakGetError, expected_code=204)
+
+        if password is not None:
+            user_id = self.get_user_id(username)
+            data={}
+            data["value"]=password
+            data["type"]="password"
+            data["temporary"]=passwordTemp
+
+            params_path = {"realm-name": self.realm_name, "id": user_id}
+            data_raw = self.connection.raw_put(URL_ADMIN_USER_PASSWORD.format(**params_path),
+                                                data=json.dumps(data))
+            return raise_error_from_response(data_raw, KeycloakGetError, expected_code=204)
+        else:
+            return update_resp
 
     def delete_user(self, user_id):
         """
@@ -261,7 +297,7 @@ class KeycloakAdmin:
         """
         Get sessions associated with the user
 
-        :param user_id: User id
+        :param user_id:  id of user
 
         UserSessionRepresentation
         http://www.keycloak.org/docs-api/3.3/rest-api/index.html#_usersessionrepresentation
@@ -284,6 +320,176 @@ class KeycloakAdmin:
         data_raw = self.connection.raw_get(URL_ADMIN_SERVER_INFO)
         return raise_error_from_response(data_raw, KeycloakGetError)
 
+    def get_groups(self):
+        """
+        Get groups belonging to the realm. Returns a list of groups belonging to the realm
+
+        GroupRepresentation
+        http://www.keycloak.org/docs-api/3.2/rest-api/#_grouprepresentation
+
+        :return: array GroupRepresentation
+        """
+        params_path = {"realm-name": self.realm_name}
+        data_raw = self.connection.raw_get(URL_ADMIN_GROUPS.format(**params_path))
+        return raise_error_from_response(data_raw, KeycloakGetError)
+
+    def get_group(self, group_id):
+        """
+        Get group by id. Returns full group details
+
+        GroupRepresentation
+        http://www.keycloak.org/docs-api/3.2/rest-api/#_grouprepresentation
+
+        :return: array GroupRepresentation
+        """
+        params_path = {"realm-name": self.realm_name, "id": group_id}
+        data_raw = self.connection.raw_get(URL_ADMIN_GROUP.format(**params_path))
+        return raise_error_from_response(data_raw, KeycloakGetError)
+
+    def get_group_id(self, name=None, path=None, parent=None):
+        """
+        Get group id based on name or path.
+        A straight name or path match with a top-level group will return first.
+        Subgroups are traversed, the first to match path (or name with path) is returned.
+
+        :param name: group name
+        :param path: group path
+        :param parent: parent group's id. Required to find a sub-group below level 1.
+
+        GroupRepresentation
+        http://www.keycloak.org/docs-api/3.2/rest-api/#_grouprepresentation
+
+        :return: GroupID (string)
+        """
+        if parent is not None:
+          params_path = {"realm-name": self.realm_name, "id": parent}
+          data_raw = self.connection.raw_get(URL_ADMIN_GROUP.format(**params_path))
+          res = raise_error_from_response(data_raw, KeycloakGetError)
+          data_content = []
+          data_content.append(res)
+        else:
+          params_path = {"realm-name": self.realm_name}
+          data_raw = self.connection.raw_get(URL_ADMIN_GROUPS.format(**params_path))
+          data_content = raise_error_from_response(data_raw, KeycloakGetError)
+
+        for group in data_content:
+          thisgroupname = json.dumps(group["name"]).strip('"')
+          thisgrouppath = json.dumps(group["path"]).strip('"')
+          if (thisgroupname == name and name is not None) or (thisgrouppath == path and path is not None):
+            return json.dumps(group["id"]).strip('"')
+          for subgroup in group["subGroups"]:
+            thisgrouppath = json.dumps(subgroup["path"]).strip('"')
+            if (thisgrouppath == path and path is not None) or (thisgrouppath == name and name is not None):
+              return json.dumps(subgroup["id"]).strip('"')
+        return None
+
+    def create_group(self, name=None, client_roles={}, realm_roles=[], sub_groups=[], path=None, parent=None, skip_exists=False):
+        """
+        Creates a group in the Realm
+
+        :param name: group name
+        :param client_roles (map): Client roles to include in groupp # Not demonstrated to work
+        :param realm_roles (array): Realm roles to include in group # Not demonstrated to work
+        :param sub_groups (array): Subgroups to include in groupp # Not demonstrated to work
+        :param path: group path
+        :param parent: parent group's id. Required to create a sub-group.
+
+        GroupRepresentation
+        http://www.keycloak.org/docs-api/3.2/rest-api/#_grouprepresentation
+
+        :return: Http response
+        """
+        if name is None and path is not None:
+          name=path
+
+        data={}
+        data["name"]=name
+        data["path"]=path
+        data["clientRoles"]=client_roles
+        data["realmRoles"]=realm_roles
+        data["subGroups"]=sub_groups
+
+        if name is not None:
+            exists = self.get_group_id(name=name, parent=parent)
+        elif path is not None:
+            exists = self.get_group_id(path=path, parent=parent)
+
+        if exists is not None:
+            return str(exists)
+
+        if parent is None:
+          params_path = {"realm-name": self.realm_name}
+          data_raw = self.connection.raw_post(URL_ADMIN_GROUPS.format(**params_path),
+                                            data=json.dumps(data))
+        else:
+          params_path = {"realm-name": self.realm_name, "id": parent,}
+          data_raw = self.connection.raw_post(URL_ADMIN_GROUP_CHILD.format(**params_path),
+                                            data=json.dumps(data))
+        return raise_error_from_response(data_raw, KeycloakGetError, expected_code=201, skip_exists=skip_exists)
+
+    def group_set_permissions(self, group_id, enabled=True):
+        """
+        Enable/Disable permissions for a group. Cannot delete group if disabled
+
+        :param group_id: id of group
+        :param enabled: boolean
+
+        :return: {}
+        """
+        data={}
+        data["enabled"]=enabled
+
+        params_path = {"realm-name": self.realm_name, "id": group_id}
+        data_raw = self.connection.raw_put(URL_ADMIN_GROUP_PERMISSIONS.format(**params_path),
+                                          data=json.dumps(data))
+        return raise_error_from_response(data_raw, KeycloakGetError)
+
+    def group_user_add(self, user_id, group_id):
+        """
+        Add user to group (user_id and group_id)
+
+        :param group_id:  id of group
+        :param user_id:  id of user
+        :param group_id:  id of group to add to
+
+        :return: {}
+        """
+        data={}
+        data["realm"]=self.realm_name
+        data["userId"]=user_id
+        data["groupId"]=group_id
+
+        params_path = {"realm-name": self.realm_name, "id": user_id, "group-id": group_id}
+        data_raw = self.connection.raw_put(URL_ADMIN_USER_GROUP.format(**params_path),
+                                          data=json.dumps(data))
+        return raise_error_from_response(data_raw, KeycloakGetError, expected_code=204)
+
+    def group_user_remove(self, user_id, group_id):
+        """
+        Remove user from group (user_id and group_id)
+
+        :param group_id:  id of group
+        :param user_id:  id of user
+        :param group_id:  id of group to add to
+
+        :return: {}
+        """
+        params_path = {"realm-name": self.realm_name, "id": user_id, "group-id": group_id}
+        data_raw = self.connection.raw_delete(URL_ADMIN_USER_GROUP.format(**params_path))
+        return raise_error_from_response(data_raw, KeycloakGetError, expected_code=204)
+
+    def delete_group(self, group_id):
+        """
+        Deletes a group in the Realm
+
+        :param group_id:  id of group to delete
+
+        :return: Http response
+        """
+        params_path = {"realm-name": self.realm_name, "id": group_id}
+        data_raw = self.connection.raw_delete(URL_ADMIN_GROUP.format(**params_path))
+        return raise_error_from_response(data_raw, KeycloakGetError, expected_code=204)
+
     def get_clients(self):
         """
         Get clients belonging to the realm Returns a list of clients belonging to the realm
@@ -302,8 +508,7 @@ class KeycloakAdmin:
         Get internal keycloak client id from client-id.
         This is required for further actions against this client.
 
-        :param client_id_name:
-        clientId in ClientRepresentation
+        :param client_id_name: name in ClientRepresentation
         http://www.keycloak.org/docs-api/3.3/rest-api/index.html#_clientrepresentation
 
         :return: client_id (uuid as string)
@@ -313,9 +518,9 @@ class KeycloakAdmin:
         data_content = raise_error_from_response(data_raw, KeycloakGetError)
 
         for client in data_content:
-          client_id = json.dumps(client["clientId"]).strip('"')
-          if client_id == client_id_name:
-            return json.dumps(client["id"]).strip('"')
+            client_id = json.dumps(client["clientId"]).strip('"')
+            if client_id == client_id_name:
+               return json.dumps(client["id"]).strip('"')
 
         return None
 
@@ -326,7 +531,7 @@ class KeycloakAdmin:
         ClientRepresentation
         http://www.keycloak.org/docs-api/3.3/rest-api/index.html#_clientrepresentation
 
-        :param client_id: id of client (not client-id)
+        :param client_id:  id of client (not client-id)
 
         :return: ClientRepresentation
         """
@@ -334,11 +539,15 @@ class KeycloakAdmin:
         data_raw = self.connection.raw_get(URL_ADMIN_CLIENT.format(**params_path))
         return raise_error_from_response(data_raw, KeycloakGetError)
 
-    def create_client(self, name, client_id, redirect_urls, protocol="openid-connect", public_client=True, direct_access_grants=True):
+    def create_client(self, name, client_id, redirect_uris, protocol="openid-connect", public_client=True, direct_access_grants=True, skip_exists=False):
         """
         Create a client
 
-        :param name: name of client, payload (ClientRepresentation)
+        :param name: name of client
+        :param client_id: (oauth client-id)
+        :param redirect_uris: Valid edirect URIs
+        :param redirect urls
+        :param protocol: openid-connect or saml
 
         ClientRepresentation
         http://www.keycloak.org/docs-api/3.3/rest-api/index.html#_clientrepresentation
@@ -347,14 +556,14 @@ class KeycloakAdmin:
         data={}
         data["name"]=name
         data["clientId"]=client_id
-        data["redirectUris"]=redirect_urls
+        data["redirectUris"]=redirect_uris
         data["protocol"]=protocol
         data["publicClient"]=public_client
         data["directAccessGrantsEnabled"]=direct_access_grants
         params_path = {"realm-name": self.realm_name}
         data_raw = self.connection.raw_post(URL_ADMIN_CLIENTS.format(**params_path),
                                             data=json.dumps(data))
-        return raise_error_from_response(data_raw, KeycloakGetError, expected_code=201)
+        return raise_error_from_response(data_raw, KeycloakGetError, expected_code=201, skip_exists=skip_exists)
 
     def delete_client(self, client_id):
         """
@@ -363,7 +572,7 @@ class KeycloakAdmin:
         ClientRepresentation
         http://www.keycloak.org/docs-api/3.3/rest-api/index.html#_clientrepresentation
 
-        :param client_id: id of client (not client-id)
+        :param client_id: keycloak client id (not oauth client-id)
 
         :return: ClientRepresentation
         """
@@ -375,11 +584,11 @@ class KeycloakAdmin:
         """
         Get all roles for the client
 
+        :param client_id: id of client (not client-id)
+
         RoleRepresentation
         http://www.keycloak.org/docs-api/3.3/rest-api/index.html#_rolerepresentation
 
-        :param client_id: id of client (not client-id)
-
         :return: RoleRepresentation
         """
         params_path = {"realm-name": self.realm_name, "id": client_id}
@@ -391,11 +600,11 @@ class KeycloakAdmin:
         Get client role id
         This is required for further actions with this role.
 
+        :param client_id: id of client (not client-id), role_name: name of role
+
         RoleRepresentation
         http://www.keycloak.org/docs-api/3.3/rest-api/index.html#_rolerepresentation
 
-        :param client_id: id of client (not client-id), role_name: name of role
-
         :return: role_id
         """
         params_path = {"realm-name": self.realm_name, "id": client_id}
@@ -403,9 +612,9 @@ class KeycloakAdmin:
         data_content = raise_error_from_response(data_raw, KeycloakGetError)
 
         for role in data_content:
-          this_role_name = json.dumps(role["name"]).strip('"')
-          if this_role_name == role_name:
-            return json.dumps(role["id"]).strip('"')
+            this_role_name = json.dumps(role["name"]).strip('"')
+            if this_role_name == role_name:
+                return json.dumps(role["id"]).strip('"')
 
         return None
 
@@ -422,11 +631,11 @@ class KeycloakAdmin:
         data_raw = self.connection.raw_get(URL_ADMIN_REALM_ROLES.format(**params_path))
         return raise_error_from_response(data_raw, KeycloakGetError)
 
-    def create_client_role(self, client_id, role_name):
+    def create_client_role(self, client_id, role_name, skip_exists=False):
         """
         Create a client role
 
-        :param client_id: id of client (not client-id), payload (RoleRepresentation)
+        :param client_id: id of client (not client-id), role_name: name of role
 
         RoleRepresentation
         http://www.keycloak.org/docs-api/3.3/rest-api/index.html#_rolerepresentation
@@ -438,13 +647,13 @@ class KeycloakAdmin:
         params_path = {"realm-name": self.realm_name, "id": client_id}
         data_raw = self.connection.raw_post(URL_ADMIN_CLIENT_ROLES.format(**params_path),
                                             data=json.dumps(data))
-        return raise_error_from_response(data_raw, KeycloakGetError, expected_code=201)
+        return raise_error_from_response(data_raw, KeycloakGetError, expected_code=201, skip_exists=skip_exists)
 
     def delete_client_role(self, client_id, role_name):
         """
         Create a client role
 
-        :param client_id: id of client (not client-id), payload (RoleRepresentation)
+        :param client_id: id of client (not client-id), role_name: name of role
 
         RoleRepresentation
         http://www.keycloak.org/docs-api/3.3/rest-api/index.html#_rolerepresentation

keycloak/urls_patterns.py

@@ -34,9 +34,16 @@ URL_ADMIN_SEND_VERIFY_EMAIL = "admin/realms/{realm-name}/users/{id}/send-verify-
 URL_ADMIN_RESET_PASSWORD = "admin/realms/{realm-name}/users/{id}/reset-password"
 URL_ADMIN_GET_SESSIONS = "admin/realms/{realm-name}/users/{id}/sessions"
 URL_ADMIN_USER_CLIENT_ROLES = "admin/realms/{realm-name}/users/{id}/role-mappings/clients/{client-id}"
+URL_ADMIN_USER_GROUP = "admin/realms/{realm-name}/users/{id}/groups/{group-id}"
+URL_ADMIN_USER_PASSWORD = "admin/realms/{realm-name}/users/{id}/reset-password"
 
 URL_ADMIN_SERVER_INFO = "admin/serverinfo"
 
+URL_ADMIN_GROUPS = "admin/realms/{realm-name}/groups"
+URL_ADMIN_GROUP = "admin/realms/{realm-name}/groups/{id}"
+URL_ADMIN_GROUP_CHILD = "admin/realms/{realm-name}/groups/{id}/children"
+URL_ADMIN_GROUP_PERMISSIONS = "admin/realms/{realm-name}/groups/{id}/management/permissions"
+
 URL_ADMIN_CLIENTS = "admin/realms/{realm-name}/clients"
 URL_ADMIN_CLIENT = "admin/realms/{realm-name}/clients/{id}"
 URL_ADMIN_CLIENT_ROLES = "admin/realms/{realm-name}/clients/{id}/roles"