diff --git a/README.md b/README.md index a80448a..6f2b8d7 100644 --- a/README.md +++ b/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() diff --git a/keycloak/exceptions.py b/keycloak/exceptions.py index 95be231..300c5f7 100644 --- a/keycloak/exceptions.py +++ b/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): diff --git a/keycloak/keycloak_admin.py b/keycloak/keycloak_admin.py index c24dbc3..542fd7c 100644 --- a/keycloak/keycloak_admin.py +++ b/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 . +# 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 diff --git a/keycloak/urls_patterns.py b/keycloak/urls_patterns.py index 33c04e9..c9dc8a9 100644 --- a/keycloak/urls_patterns.py +++ b/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"