[keyvault] add scope enum (#13516)

sdk/keyvault/azure-keyvault-administration/azure/keyvault/administration/__init__.py

@@ -4,7 +4,9 @@
 # ------------------------------------
 from ._access_control_client import KeyVaultAccessControlClient
 from ._internal.client_base import ApiVersion
-from ._models import KeyVaultPermission, KeyVaultRoleAssignment, KeyVaultRoleDefinition
+from ._models import (
+    KeyVaultPermission, KeyVaultRoleAssignment, KeyVaultRoleDefinition, KeyVaultRoleScope
+)
 
 
 __all__ = [
@@ -13,4 +15,5 @@
     "KeyVaultPermission",
     "KeyVaultRoleAssignment",
     "KeyVaultRoleDefinition",
+    "KeyVaultRoleScope",
 ]

sdk/keyvault/azure-keyvault-administration/azure/keyvault/administration/_access_control_client.py

@@ -13,6 +13,7 @@
     from typing import Any, Union
     from uuid import UUID
     from azure.core.paging import ItemPaged
+    from ._models import KeyVaultRoleScope
 
 
 class KeyVaultAccessControlClient(KeyVaultClientBase):
@@ -27,10 +28,12 @@ class KeyVaultAccessControlClient(KeyVaultClientBase):
 
     @distributed_trace
     def create_role_assignment(self, role_scope, role_assignment_name, role_definition_id, principal_id, **kwargs):
-        # type: (str, Union[str, UUID], str, str, **Any) -> KeyVaultRoleAssignment
+        # type: (Union[str, KeyVaultRoleScope], Union[str, UUID], str, str, **Any) -> KeyVaultRoleAssignment
         """Create a role assignment.
 
-        :param str role_scope: scope the role assignment will apply over
+        :param role_scope: scope the role assignment will apply over. :class:`KeyVaultRoleScope` defines common
+            broad scopes. Specify a narrower scope as a string.
+        :type role_scope: str or KeyVaultRoleScope
         :param role_assignment_name: a name for the role assignment. Must be a UUID.
         :type role_assignment_name: str or uuid.UUID
         :param str role_definition_id: ID of the role's definition
@@ -54,10 +57,12 @@ def create_role_assignment(self, role_scope, role_assignment_name, role_definiti
 
     @distributed_trace
     def delete_role_assignment(self, role_scope, role_assignment_name, **kwargs):
-        # type: (str, Union[str, UUID], **Any) -> KeyVaultRoleAssignment
+        # type: (Union[str, KeyVaultRoleScope], Union[str, UUID], **Any) -> KeyVaultRoleAssignment
         """Delete a role assignment.
 
-        :param str role_scope: the assignment's scope, for example "/", "/keys", or "/keys/<specific key identifier>"
+        :param role_scope: the assignment's scope, for example "/", "/keys", or "/keys/<specific key identifier>"
+            :class:`KeyVaultRoleScope` defines common broad scopes. Specify a narrower scope as a string.
+        :type role_scope: str or KeyVaultRoleScope
         :param role_assignment_name: the assignment's name. Must be a UUID.
         :type role_assignment_name: str or uuid.UUID
         :returns: the deleted assignment
@@ -70,10 +75,12 @@ def delete_role_assignment(self, role_scope, role_assignment_name, **kwargs):
 
     @distributed_trace
     def get_role_assignment(self, role_scope, role_assignment_name, **kwargs):
-        # type: (str, Union[str, UUID], **Any) -> KeyVaultRoleAssignment
+        # type: (Union[str, KeyVaultRoleScope], Union[str, UUID], **Any) -> KeyVaultRoleAssignment
         """Get a role assignment.
 
-        :param str role_scope: the assignment's scope, for example "/", "/keys", or "/keys/<specific key identifier>"
+        :param role_scope: the assignment's scope, for example "/", "/keys", or "/keys/<specific key identifier>"
+            :class:`KeyVaultRoleScope` defines common broad scopes. Specify a narrower scope as a string.
+        :type role_scope: str or KeyVaultRoleScope
         :param role_assignment_name: the assignment's name. Must be a UUID.
         :type role_assignment_name: str or uuid.UUID
         :rtype: KeyVaultRoleAssignment
@@ -85,10 +92,12 @@ def get_role_assignment(self, role_scope, role_assignment_name, **kwargs):
 
     @distributed_trace
     def list_role_assignments(self, role_scope, **kwargs):
-        # type: (str, **Any) -> ItemPaged[KeyVaultRoleAssignment]
+        # type: (Union[str, KeyVaultRoleScope], **Any) -> ItemPaged[KeyVaultRoleAssignment]
         """List all role assignments for a scope.
 
-        :param str role_scope: scope of the role assignments
+        :param role_scope: scope of the role assignments. :class:`KeyVaultRoleScope` defines common broad scopes.
+            Specify a narrower scope as a string.
+        :type role_scope: str or KeyVaultRoleScope
         :rtype: ~azure.core.paging.ItemPaged[KeyVaultRoleAssignment]
         """
         return self._client.role_assignments.list_for_scope(
@@ -100,10 +109,12 @@ def list_role_assignments(self, role_scope, **kwargs):
 
     @distributed_trace
     def list_role_definitions(self, role_scope, **kwargs):
-        # type: (str, **Any) -> ItemPaged[KeyVaultRoleDefinition]
+        # type: (Union[str, KeyVaultRoleScope], **Any) -> ItemPaged[KeyVaultRoleDefinition]
         """List all role definitions applicable at and above a scope.
 
-        :param str role_scope: scope of the role definitions
+        :param role_scope: scope of the role definitions. :class:`KeyVaultRoleScope` defines common broad scopes.
+            Specify a narrower scope as a string.
+        :type role_scope: str or KeyVaultRoleScope
         :rtype: ~azure.core.paging.ItemPaged[KeyVaultRoleDefinition]
         """
         return self._client.role_definitions.list(

sdk/keyvault/azure-keyvault-administration/azure/keyvault/administration/_models.py

@@ -2,6 +2,7 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 # ------------------------------------
+from enum import Enum
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -11,6 +12,14 @@
 # pylint:disable=protected-access
 
 
+class KeyVaultRoleScope(str, Enum):
+    """Collection of well known role scopes. This list is not exhaustive"""
+
+    global_value = "/"  #: use this if you want role assignments to apply to everything on the resource
+
+    keys_value = "/keys"  #: use this if you want role assignments to apply to all keys
+
+
 class KeyVaultPermission(object):
     """Role definition permissions.
 

sdk/keyvault/azure-keyvault-administration/azure/keyvault/administration/aio/_access_control_client.py

@@ -14,6 +14,7 @@
     from typing import Any, Union
     from uuid import UUID
     from azure.core.async_paging import AsyncItemPaged
+    from .._models import KeyVaultRoleScope
 
 
 class KeyVaultAccessControlClient(AsyncKeyVaultClientBase):
@@ -29,15 +30,17 @@ class KeyVaultAccessControlClient(AsyncKeyVaultClientBase):
     @distributed_trace_async
     async def create_role_assignment(
         self,
-        role_scope: str,
+        role_scope: "Union[str, KeyVaultRoleScope]",
         role_assignment_name: "Union[str, UUID]",
         role_definition_id: str,
         principal_id: str,
         **kwargs: "Any"
     ) -> KeyVaultRoleAssignment:
         """Create a role assignment.
 
-        :param str role_scope: scope the role assignment will apply over
+        :param role_scope: scope the role assignment will apply over. :class:`KeyVaultRoleScope` defines common broad
+            scopes. Specify a narrower scope as a string.
+        :type role_scope: str or KeyVaultRoleScope
         :param role_assignment_name: a name for the role assignment. Must be a UUID.
         :type role_assignment_name: str or uuid.UUID
         :param str role_definition_id: ID of the role's definition
@@ -61,11 +64,13 @@ async def create_role_assignment(
 
     @distributed_trace_async
     async def delete_role_assignment(
-        self, role_scope: str, role_assignment_name: "Union[str, UUID]", **kwargs: "Any"
+        self, role_scope: "Union[str, KeyVaultRoleScope]", role_assignment_name: "Union[str, UUID]", **kwargs: "Any"
     ) -> KeyVaultRoleAssignment:
         """Delete a role assignment.
 
-        :param str role_scope: the assignment's scope, for example "/", "/keys", or "/keys/<specific key identifier>"
+        :param role_scope: the assignment's scope, for example "/", "/keys", or "/keys/<specific key identifier>".
+            :class:`KeyVaultRoleScope` defines common broad scopes. Specify a narrower scope as a string.
+        :type role_scope: str or KeyVaultRoleScope
         :param role_assignment_name: the assignment's name. Must be a UUID.
         :type role_assignment_name: str or uuid.UUID
         :returns: the deleted assignment
@@ -78,11 +83,13 @@ async def delete_role_assignment(
 
     @distributed_trace_async
     async def get_role_assignment(
-        self, role_scope: str, role_assignment_name: "Union[str, UUID]", **kwargs: "Any"
+        self, role_scope: "Union[str, KeyVaultRoleScope]", role_assignment_name: "Union[str, UUID]", **kwargs: "Any"
     ) -> KeyVaultRoleAssignment:
         """Get a role assignment.
 
-        :param str role_scope: the assignment's scope, for example "/", "/keys", or "/keys/<specific key identifier>"
+        :param role_scope: the assignment's scope, for example "/", "/keys", or "/keys/<specific key identifier>".
+            :class:`KeyVaultRoleScope` defines common broad scopes. Specify a narrower scope as a string.
+        :type role_scope: str or KeyVaultRoleScope
         :param role_assignment_name: the assignment's name. Must be a UUID.
         :type role_assignment_name: str or uuid.UUID
         :rtype: KeyVaultRoleAssignment
@@ -93,10 +100,14 @@ async def get_role_assignment(
         return KeyVaultRoleAssignment._from_generated(assignment)
 
     @distributed_trace
-    def list_role_assignments(self, role_scope: str, **kwargs: "Any") -> "AsyncItemPaged[KeyVaultRoleAssignment]":
+    def list_role_assignments(
+        self, role_scope: "Union[str, KeyVaultRoleScope]", **kwargs: "Any"
+    ) -> "AsyncItemPaged[KeyVaultRoleAssignment]":
         """List all role assignments for a scope.
 
-        :param str role_scope: scope of the role assignments
+        :param role_scope: scope of the role assignments. :class:`KeyVaultRoleScope` defines common broad
+            scopes. Specify a narrower scope as a string.
+        :type role_scope: str or KeyVaultRoleScope
         :rtype: ~azure.core.async_paging.AsyncItemPaged[KeyVaultRoleAssignment]
         """
         return self._client.role_assignments.list_for_scope(
@@ -107,10 +118,14 @@ def list_role_assignments(self, role_scope: str, **kwargs: "Any") -> "AsyncItemP
         )
 
     @distributed_trace
-    def list_role_definitions(self, role_scope: str, **kwargs: "Any") -> "AsyncItemPaged[KeyVaultRoleDefinition]":
+    def list_role_definitions(
+        self, role_scope: "Union[str, KeyVaultRoleScope]", **kwargs: "Any"
+    ) -> "AsyncItemPaged[KeyVaultRoleDefinition]":
         """List all role definitions applicable at and above a scope.
 
-        :param str role_scope: scope of the role definitions
+        :param role_scope: scope of the role definitions. :class:`KeyVaultRoleScope` defines common broad
+            scopes. Specify a narrower scope as a string.
+        :type role_scope: str or KeyVaultRoleScope
         :rtype: ~azure.core.async_paging.AsyncItemPaged[KeyVaultRoleDefinition]
         """
         return self._client.role_definitions.list(

sdk/keyvault/azure-keyvault-administration/tests/test_access_control.py

@@ -6,7 +6,7 @@
 import os
 import uuid
 
-from azure.keyvault.administration import KeyVaultAccessControlClient
+from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope
 from devtools_testutils import KeyVaultPreparer, ResourceGroupPreparer
 import pytest
 
@@ -41,7 +41,7 @@ def get_service_principal_id(self):
     @KeyVaultPreparer()
     @AccessControlClientPreparer()
     def test_list_role_definitions(self, client):
-        definitions = [d for d in client.list_role_definitions("/")]
+        definitions = [d for d in client.list_role_definitions(KeyVaultRoleScope.global_value)]
         assert len(definitions)
 
         for definition in definitions:
@@ -58,7 +58,7 @@ def test_list_role_definitions(self, client):
     @KeyVaultPreparer()
     @AccessControlClientPreparer()
     def test_role_assignment(self, client):
-        scope = "/"
+        scope = KeyVaultRoleScope.global_value
         definitions = [d for d in client.list_role_definitions(scope)]
 
         # assign an arbitrary role to the service principal authenticating these requests

sdk/keyvault/azure-keyvault-administration/tests/test_access_control_async.py

@@ -6,6 +6,7 @@
 import os
 import uuid
 
+from azure.keyvault.administration import KeyVaultRoleScope
 from azure.keyvault.administration.aio import KeyVaultAccessControlClient
 from devtools_testutils import KeyVaultPreparer, ResourceGroupPreparer
 import pytest
@@ -42,7 +43,7 @@ def get_service_principal_id(self):
     @AccessControlClientPreparer()
     async def test_list_role_definitions(self, client):
         definitions = []
-        async for definition in client.list_role_definitions("/"):
+        async for definition in client.list_role_definitions(KeyVaultRoleScope.global_value):
             definitions.append(definition)
         assert len(definitions)
 
@@ -60,9 +61,9 @@ async def test_list_role_definitions(self, client):
     @KeyVaultPreparer()
     @AccessControlClientPreparer()
     async def test_role_assignment(self, client):
-        scope = "/"
+        scope = KeyVaultRoleScope.global_value
         definitions = []
-        async for definition in client.list_role_definitions("/"):
+        async for definition in client.list_role_definitions(scope):
             definitions.append(definition)
 
         # assign an arbitrary role to the service principal authenticating these requests