zscaler-sdk-python 1.0.0__py2.py3-none-any.whl

zscaler/zpa/provisioning.py

@@ -0,0 +1,271 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2023, Zscaler Inc.
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+
+from box import Box, BoxList
+from requests import Response
+
+from zscaler.utils import snake_to_camel
+from zscaler.zpa.client import ZPAClient
+
+
+def simplify_key_type(key_type):
+    # Simplify the key type for our users
+    if key_type == "connector":
+        return "CONNECTOR_GRP"
+    elif key_type == "service_edge":
+        return "SERVICE_EDGE_GRP"
+    else:
+        raise ValueError("Unexpected key type.")
+
+
+class ProvisioningKeyAPI:
+    def __init__(self, client: ZPAClient):
+        self.rest = client
+
+    def list_provisioning_keys(self, key_type: str, **kwargs) -> BoxList:
+        """
+        Returns a list of all configured provisioning keys that match the specified ``key_type``.
+
+        Args:
+            key_type (str): The type of provisioning key, accepted values are:
+                ``connector`` and ``service_edge``.
+            **kwargs: Optional keyword args.
+
+        Keyword Args:
+            max_items (int, optional):
+                The maximum number of items to request before stopping iteration.
+            max_pages (int, optional):
+                The maximum number of pages to request before stopping iteration.
+            pagesize (int, optional):
+                Specifies the page size. The default size is 20, but the maximum size is 500.
+            search (str, optional):
+                The search string used to match against features and fields.
+
+        Returns:
+            :obj:`BoxList`: A list containing the requested provisioning keys.
+
+        Examples:
+            List all App Connector provisioning keys.
+
+            >>> for key in zpa.provisioning.list_provisioning_keys(key_type="connector"):
+            ...    print(key)
+
+            List all Service Edge provisioning keys.
+
+            >>> for key in zpa.provisioning.list_provisioning_keys(key_type="service_edge"):
+            ...    print(key)
+
+        """
+        list, _ = self.rest.get_paginated_data(
+            path=f"/associationType/{simplify_key_type(key_type)}/provisioningKey",
+            **kwargs,
+        )
+        return list
+
+    def get_provisioning_key(self, key_id: str, key_type: str) -> Box:
+        """
+        Returns information on the specified provisioning key.
+
+        Args:
+            key_id (str): The unique id of the provisioning key.
+            key_type (str): The type of provisioning key, accepted values are:
+
+                ``connector`` and ``service_edge``.
+
+        Returns:
+            :obj:`Box`: The requested provisioning key resource record.
+
+        Examples:
+            Get the specified App Connector key.
+
+            >>> provisioning_key = zpa.provisioning.get_provisioning_key("999999",
+            ...    key_type="connector")
+
+            Get the specified Service Edge key.
+
+            >>> provisioning_key = zpa.provisioning.get_provisioning_key("888888",
+            ...    key_type="service_edge")
+
+        """
+        return self.rest.get(
+            f"associationType/{simplify_key_type(key_type)}/provisioningKey/{key_id}"
+        )
+
+    def add_provisioning_key(
+        self,
+        key_type: str,
+        name: str,
+        max_usage: str,
+        enrollment_cert_id: str,
+        component_id: str,
+        **kwargs,
+    ) -> Box:
+        """
+        Adds a new provisioning key to ZPA.
+
+        Args:
+            key_type (str): The type of provisioning key, accepted values are:
+
+                ``connector`` and ``service_edge``.
+            name (str): The name of the provisioning key.
+            max_usage (int): The maximum amount of times this key can be used.
+            enrollment_cert_id (str):
+                The unique id of the enrollment certificate that will be used for this provisioning key.
+            component_id (str):
+                The unique id of the component that this provisioning key will be linked to. For App Connectors, this
+                will be the App Connector Group Id. For Service Edges, this will be the Service Edge Group Id.
+            **kwargs: Optional keyword args.
+
+        Keyword Args:
+            enabled (bool): Enable the provisioning key. Defaults to ``True``.
+
+        Returns:
+            :obj:`Box`: The newly created Provisioning Key resource record.
+
+        Examples:
+            Add a new App Connector Provisioning Key that can be used a maximum of 2 times.
+
+            >>> key = zpa.provisioning.add_provisioning_key(key_type="connector",
+            ...    name="Example App Connector Provisioning Key",
+            ...    max_usage=2,
+            ...    enrollment_cert_id="99999",
+            ...    component_id="888888")
+
+            Add a new Service Edge Provisioning Key in the disabled state that can be used once.
+
+            >>> key = zpa.provisioning.add_provisioning_key(key_type="service_edge",
+            ...    name="Example Service Edge Provisioning Key",
+            ...    max_usage=1,
+            ...    enrollment_cert_id="99999",
+            ...    component_id="777777"
+            ...    enabled=False)
+
+        """
+
+        payload = {
+            "name": name,
+            "maxUsage": max_usage,
+            "enrollmentCertId": enrollment_cert_id,
+            "zcomponentId": component_id,
+        }
+
+        # Add optional parameters to payload
+        for key, value in kwargs.items():
+            payload[snake_to_camel(key)] = value
+
+        response = self.rest.post(
+            f"associationType/{simplify_key_type(key_type)}/provisioningKey",
+            json=payload,
+        )
+        if isinstance(response, Response):
+            # this is only true when the creation failed (status code is not 2xx)
+            status_code = response.status_code
+            # Handle error response
+            raise Exception(
+                f"API call failed with status {status_code}: {response.json()}"
+            )
+        return response
+
+    def update_provisioning_key(self, key_id: str, key_type: str, **kwargs) -> Box:
+        """
+        Updates the specified provisioning key.
+
+        Args:
+            key_id (str): The unique id of the Provisioning Key being updated.
+            key_type (str): The type of provisioning key, accepted values are:
+
+                ``connector`` and ``service_edge``.
+            **kwargs: Optional keyword args.
+
+        Keyword Args:
+            name (str): The name of the provisioning key.
+            max_usage (int): The maximum amount of times this key can be used.
+            enrollment_cert_id (str):
+                The unique id of the enrollment certificate that will be used for this provisioning key.
+            component_id (str):
+                The unique id of the component that this provisioning key will be linked to. For App Connectors, this
+                will be the App Connector Group Id. For Service Edges, this will be the Service Edge Group Id.
+
+        Returns:
+            :obj:`Box`: The updated Provisioning Key resource record.
+
+        Examples:
+            Update the name of an App Connector provisioning key:
+
+            >>> updated_key = zpa.provisioning.update_provisioning_key('999999',
+            ...    key_type="connector",
+            ...    name="Updated Name")
+
+            Change the max usage of a Service Edge provisioning key:
+
+            >>> updated_key = zpa.provisioning.update_provisioning_key('888888',
+            ...    key_type="service_edge",
+            ...    max_usage=10)
+
+        """
+
+        # Get the provided provisioning key record
+        payload = {
+            snake_to_camel(k): v
+            for k, v in self.get_provisioning_key(key_id, key_type=key_type).items()
+        }
+
+        # Add optional parameters to payload
+        for key, value in kwargs.items():
+            payload[snake_to_camel(key)] = value
+
+        resp = self.rest.put(
+            f"associationType/{simplify_key_type(key_type)}/provisioningKey/{key_id}",
+            json=payload,
+        ).status_code
+
+        # Return the object if it was updated successfully
+        if not isinstance(resp, Response):
+            return self.get_provisioning_key(key_id, key_type=key_type)
+
+        # Return the object if it was updated successfully
+        if not isinstance(resp, Response):
+            return self.get_provisioning_key(key_id, key_type=key_type)
+
+    def delete_provisioning_key(self, key_id: str, key_type: str) -> int:
+        """
+        Deletes the specified provisioning key from ZPA.
+
+        Args:
+            key_id (str): The unique id of the provisioning key that will be deleted.
+            key_type (str): The type of provisioning key, accepted values are:
+
+                ``connector`` and ``service_edge``.
+
+        Returns:
+            :obj:`int`: The status code for the operation.
+
+        Examples:
+            Delete an App Connector provisioning key:
+
+            >>> zpa.provisioning.delete_provisioning_key(key_id="999999",
+            ...    key_type="connector")
+
+            Delete a Service Edge provisioning key:
+
+            >>> zpa.provisioning.delete_provisioning_key(key_id="888888",
+            ...    key_type="service_edge")
+
+        """
+        return self.rest.delete(
+            f"associationType/{simplify_key_type(key_type)}/provisioningKey/{key_id}"
+        ).status_code

zscaler/zpa/saml_attributes.py

@@ -0,0 +1,100 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2023, Zscaler Inc.
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+
+from box import Box, BoxList
+
+from zscaler.zpa.client import ZPAClient
+
+
+class SAMLAttributesAPI:
+    def __init__(self, client: ZPAClient):
+        self.rest = client
+
+    def list_attributes(self, **kwargs) -> BoxList:
+        """
+        Returns a list of all configured SAML attributes.
+
+        Keyword Args:
+            **max_items (int):
+                The maximum number of items to request before stopping iteration.
+            **max_pages (int):
+                The maximum number of pages to request before stopping iteration.
+            **pagesize (int):
+                Specifies the page size. The default size is 20, but the maximum size is 500.
+            **search (str, optional):
+                The search string used to match against features and fields.
+
+        Returns:
+            :obj:`BoxList`: A list of all configured SAML attributes.
+
+        Examples:
+            >>> for saml_attribute in zpa.saml_attributes.list_attributes():
+            ...    pprint(saml_attribute)
+
+        """
+        list, _ = self.rest.get_paginated_data(
+            path="/samlAttribute", **kwargs, api_version="v2"
+        )
+        return list
+
+    def list_attributes_by_idp(self, idp_id: str, **kwargs) -> BoxList:
+        """
+        Returns a list of all configured SAML attributes for the specified IdP.
+
+        Args:
+            idp_id (str): The unique id of the IdP to retrieve SAML attributes from.
+
+        Keyword Args:
+            **max_items (int):
+                The maximum number of items to request before stopping iteration.
+            **max_pages (int):
+                The maximum number of pages to request before stopping iteration.
+            **pagesize (int):
+                Specifies the page size. The default size is 20, but the maximum size is 500.
+            **search (str, optional):
+                The search string used to match against features and fields.
+
+        Returns:
+            :obj:`BoxList`: A list of all configured SAML attributes for the specified IdP.
+
+        Examples:
+            >>> for saml_attribute in zpa.saml_attributes.list_attributes_by_idp('99999'):
+            ...    pprint(saml_attribute)
+
+        """
+        path = (
+            f"/samlAttribute/idp/{idp_id}"  # Correctly format the path with the idp_id
+        )
+        list, _ = self.rest.get_paginated_data(path=path, **kwargs, api_version="v2")
+        return list
+
+    def get_attribute(self, attribute_id: str) -> Box:
+        """
+        Returns information on the specified SAML attributes.
+
+        Args:
+            attribute_id (str):
+                The unique identifier for the SAML attributes.
+
+        Returns:
+            :obj:`dict`: The resource record for the SAML attributes.
+
+        Examples:
+            >>> pprint(zpa.saml_attributes.get_attribute('99999'))
+
+        """
+        return self.rest.get(f"samlAttribute/{attribute_id}")

zscaler/zpa/scim_attributes.py

@@ -0,0 +1,117 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2023, Zscaler Inc.
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+
+from box import Box, BoxList
+
+from zscaler.zpa.client import ZPAClient
+
+
+class ScimAttributeHeaderAPI:
+    def __init__(self, client: ZPAClient):
+        self.rest = client
+
+    def list_attributes_by_idp(self, idp_id: str, **kwargs) -> BoxList:
+        """
+        Returns a list of all configured SCIM attributes for the specified IdP.
+
+        Args:
+            idp_id (str): The unique id of the IdP to retrieve SCIM attributes for.
+            **kwargs: Optional keyword args.
+
+        Keyword Args:
+            max_items (int):
+                The maximum number of items to request before stopping iteration.
+            max_pages (int):
+                The maximum number of pages to request before stopping iteration.
+            pagesize (int):
+                Specifies the page size. The default size is 20, but the maximum size is 500.
+            search (str, optional):
+                The search string used to match against features and fields.
+
+        Returns:
+            :obj:`BoxList`: A list of all configured SCIM attributes for the specified IdP.
+
+        Examples:
+            >>> for scim_attribute in zpa.scim_attributes.list_attributes_by_idp('99999'):
+            ...    pprint(scim_attribute)
+
+        """
+        list, _ = self.rest.get_paginated_data(
+            path=f"/idp/{idp_id}/scimattribute",
+            **kwargs,
+            api_version="v1",
+        )
+        return list
+
+    def get_attribute(self, idp_id: str, attribute_id: str) -> Box:
+        """
+        Returns information on the specified SCIM attribute.
+
+        Args:
+            idp_id (str):
+                The unique id of the Idp corresponding to the SCIM attribute.
+            attribute_id (str):
+                The unique id of the SCIM attribute.
+
+        Returns:
+            :obj:`Box`: The resource record for the SCIM attribute.
+
+        Examples:
+            >>> pprint(zpa.scim_attributes.get_attribute('99999',
+            ...    scim_attribute_id="88888"))
+
+        """
+        response = self.rest.get(
+            f"/idp/{idp_id}/scimattribute/{attribute_id}", api_version="v1"
+        )
+        return response
+
+    def get_values(self, idp_id: str, attribute_id: str, **kwargs) -> BoxList:
+        """
+        Returns information on the specified SCIM attributes.
+
+        Args:
+            idp_id (str):
+                The unique identifier for the IDP.
+            attribute_id (str):
+                The unique identifier for the attribute.
+            **kwargs:
+                Optional keyword args.
+
+        Keyword Args:
+            max_items (int):
+                The maximum number of items to request before stopping iteration.
+            max_pages (int):
+                The maximum number of pages to request before stopping iteration.
+            pagesize (int):
+                Specifies the page size. Default is 20, maximum is 500.
+            search (str, optional):
+                The search string used to match against features and fields.
+
+        Returns:
+            :obj:`BoxList`: The resource record for the SCIM attribute values.
+
+        Examples:
+            >>> pprint(zpa.scim_attributes.get_values('99999', '88888'))
+
+        """
+        list, _ = self.rest.get_paginated_data(
+            path=f"/scimattribute/idpId/{idp_id}/attributeId/{attribute_id}",
+            **kwargs,
+            api_version="userconfig_v1",
+        )
+        return list

zscaler/zpa/scim_groups.py

@@ -0,0 +1,146 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2023, Zscaler Inc.
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+
+from box import Box, BoxList
+
+from zscaler.zpa.client import ZPAClient
+
+
+class SCIMGroupsAPI:
+    def __init__(self, client: ZPAClient):
+        self.rest = client
+
+    def list_groups(self, idp_id: str, **kwargs) -> BoxList:
+        """
+        Returns a list of all configured SCIM groups for the specified IdP.
+
+        Args:
+            idp_id (str):
+                The unique id of the IdP.
+            sort_by (str):
+                The field name to sort by, supported values: id, name, creationTime or modifiedTime (default to name)
+            sort_order (str):
+                The sort order, values: ASC or DSC (default DSC)
+
+
+        Keyword Args:
+            **end_time (str):
+                The end of a time range for requesting last updated data (modified_time) for the SCIM group.
+                This requires setting the ``start_time`` parameter as well.
+            **idp_group_id (str):
+                The unique id of the IdP group.
+            **max_items (int):
+                The maximum number of items to request before stopping iteration.
+            **max_pages (int):
+                The maximum number of pages to request before stopping iteration.
+            **pagesize (int):
+                Specifies the page size. The default size is 20, but the maximum size is 500.
+            **scim_user_id (str):
+                The unique id for the SCIM user.
+            **search (str, optional):
+                The search string used to match against features and fields.
+            **sort_order (str):
+                Sort the last updated time (modified_time) by ascending ``ASC`` or descending ``DSC`` order. Defaults to
+                ``DSC``.
+            **start_time (str):
+                The start of a time range for requesting last updated data (modified_time) for the SCIM group.
+                This requires setting the ``end_time`` parameter as well.
+
+        Returns:
+            :obj:`list`: A list of all configured SCIM groups.
+
+        Examples:
+            >>> for scim_group in zpa.scim_groups.list_groups("999999"):
+            ...    pprint(scim_group)
+
+        """
+        list, _ = self.rest.get_paginated_data(
+            path=f"/scimgroup/idpId/{idp_id}",
+            **kwargs,
+            api_version="userconfig_v1",
+        )
+        return list
+        # params = {}
+        # if sort_order != "" and sort_by != "":
+        #     params["sortBy"] = sort_by
+        #     params["sortOrder"] = sort_order
+        # list, _ = self.rest.get_paginated_data(
+        #     path=f"/scimgroup/idpId/{idp_id}",
+        #     params=params,
+        #     **kwargs,
+        #     api_version="userconfig_v1",
+        # )
+        # return list
+
+    def get_group(self, group_id: str, **kwargs) -> Box:
+        """
+        Returns information on the specified SCIM group.
+
+        Args:
+            group_id (str):
+                The unique identifier for the SCIM group.
+            **kwargs:
+                Optional keyword args.
+
+        Returns:
+            :obj:`dict`: The resource record for the SCIM group.
+
+        Examples:
+            >>> pprint(zpa.scim_groups.get_group('99999'))
+
+        """
+        response = self.rest.get(
+            f"/scimgroup/{group_id}", **kwargs, api_version="userconfig_v1"
+        )
+        return response
+
+    def search_group(self, idp_id: str, group_name: str, **kwargs) -> dict:
+        """
+        Searches and returns the SCIM group with the specified name for the given IdP.
+        """
+        page_size = kwargs.get("pagesize", 500)  # Adjust the page size as needed
+
+        # Calculate the total pages using a synchronous call
+        total_pages = 1
+        page_number = 1
+
+        # Loop over each page to search for the group
+        while True:
+            page = self._get_page(idp_id, page_number, group_name, page_size)
+            total_pages = int(page.get("total_pages", "0"))
+            for group in page.get("list", []):
+                if group.get("name") == group_name:
+                    return group  # Return the found group immediately
+            if page_number >= total_pages:
+                break
+            page_number = page_number + 1
+        return None  # Return None if the group wasn't found
+
+    def _get_page(self, idp_id, page_number, search, page_size):
+        params = {
+            "page": page_number,
+            "search": search,
+            "pagesize": page_size,
+            "sortBy": "name",
+            "sortOrder": "DSC",
+        }
+        page = self.rest.get(
+            path=f"/scimgroup/idpId/{idp_id}",
+            params=params,
+            api_version="userconfig_v1",
+        )
+        return page