Zarządzanie aktywnym dostępem za pomocą interfejsu API REST przy użyciu usługi Azure PIM

Artykuł
08/05/2023

Usługa Azure Privileged Identity Management (PIM) umożliwia ograniczenie stałego dostępu administratora do ról uprzywilejowanych, odnajdywanie osób z dostępem i przeglądanie dostępu uprzywilejowanego. W tym artykule opisano typowe sposoby zarządzania dostępem przy użyciu interfejsu API REST.

Wyświetlanie listy aktywnych przypisań

Aby wyświetlić listę aktywnych przypisań ról (dostęp do listy), możesz użyć jednego z wystąpień harmonogramu przypisań ról — lista dla harmonogramów zakresów lub harmonogramów przypisań ról — lista dla interfejsów API REST zakresu. Aby uściślić wyniki, należy określić zakres i opcjonalny filtr. Aby wywołać interfejs API, musisz mieć dostęp do Microsoft.Authorization/roleAssignments/read operacji w określonym zakresie. Wszystkie wbudowane role mają dostęp do tej operacji.

Ważne

Różnica między harmonogramami i wystąpieniami harmonogramu polega na tym, że podczas gdy wystąpienia harmonogramu obejmują tylko przypisania, które są aktywne w bieżącym czasie, harmonogramy obejmują również przypisania, które staną się aktywne w przyszłości.

Zacznij od następującego żądania:

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleInstances?api-version=2020-10-01&$filter={filter}

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentSchedules?api-version=2020-10-01&$filter={filter}

W identyfikatorze URI zastąp element {scope} zakresem, dla którego chcesz wyświetlić listę przypisań ról.

Zakres	Typ
`providers/Microsoft.Management/managementGroups/{mg-name}`	Grupa zarządzania
`subscriptions/{subscriptionId}`	Subskrypcja
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1`	Grupa zasobów
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1`	Zasób

Zastąp element {filter} warunkiem, który chcesz zastosować, aby filtrować listę przypisań ról.

Filtr	Opis
`$filter=atScope()`	Wyświetlanie listy przypisań ról tylko dla określonego zakresu, a nie w tym przypisań ról w podzakresach.
`$filter=principalId%20eq%20'{objectId}'`	Wyświetlanie listy przypisań ról dla określonego użytkownika, grupy lub jednostki usługi.
`$filter=roleDefinitionId%20eq%20'{roleDefinitionId}'`	Wyświetlanie listy przypisań ról dla określonej definicji roli.
`$filter=assignedTo('{objectId}')`	Wyświetl listę przypisań ról dla określonego użytkownika, w tym te dziedziczone z grup.
`$filter=asTarget()`	Wyświetl listę przypisań ról dla bieżącego użytkownika lub jednostki usługi, w tym te dziedziczone z grup.
`$filter=assignedTo('{objectId}')+and+atScope()`	Wyświetl listę przypisań ról dla określonego użytkownika, w tym te dziedziczone z grup tylko dla określonego zakresu, nie uwzględniając przypisań ról w podzakresach.

Przyznaj aktywne przypisanie

Aby utworzyć aktywne przypisanie roli (przyznać dostęp), użyj żądań harmonogramu przypisań ról — utwórz interfejs API REST i określ podmiot zabezpieczeń, definicję roli, harmonogram, typ żądania = AdminAssign i zakres. Aby wywołać ten interfejs API, musisz mieć dostęp do Microsoft.Authorization/roleAssignments/write operacji. We wbudowanych rolach tylko właściciel i administrator dostępu użytkowników mają dostęp do tej operacji.

Użyj interfejsu API REST definicji ról — lista lub zobacz Wbudowane role , aby uzyskać identyfikator definicji roli, którą chcesz przypisać.
Użyj narzędzia GUID, aby wygenerować unikatowy identyfikator, który będzie używany dla identyfikatora przypisania roli. Identyfikator ma format: 00000000-0000-0000-0000-000000000000

Zacznij od następującego żądania i treści:

PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

{
  "Properties": {
    "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
    "PrincipalId": "{principalId}",
    "RequestType": "AdminAssign",
    "ScheduleInfo": {
      "StartDateTime": "2020-09-09T21:31:27.91Z",
      "Expiration": {
        "Type": "AfterDuration", // Values: AfterDuration, AfterDateTime, NoExpiration
        "EndDateTime": null,
        "Duration": "P30D" // Use ISO 8601 format
      }
    }
  }
}

W identyfikatorze URI zastąp element {scope} zakresem przypisania roli.

Zakres	Typ
`providers/Microsoft.Management/managementGroups/{mg-name}`	Grupa zarządzania
`subscriptions/{subscriptionId}`	Subskrypcja
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1`	Grupa zasobów
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1`	Zasób

Zastąp element {roleAssignmentScheduleRequestName} identyfikatorem GUID przypisania roli.
W treści żądania zastąp ciąg {subscriptionId} identyfikatorem subskrypcji.
Zastąp element {roleDefinitionId} identyfikatorem definicji roli.
Zastąp element {principalId} identyfikatorem obiektu użytkownika, grupy lub jednostki usługi, która zostanie przypisana do roli.

Usuwanie aktywnego przypisania

Aby usunąć aktywne przypisanie roli (usunąć dostęp), użyj żądań harmonogramu przypisań ról — utwórz interfejs API REST, aby utworzyć nowe żądanie odwołania przypisania i określić podmiot zabezpieczeń, definicję roli, typ żądania = AdminRemove i zakres. Aby wywołać ten interfejs API, musisz mieć dostęp do Microsoft.Authorization/roleAssignments/write operacji. We wbudowanych rolach tylko właściciel i administrator dostępu użytkowników mają dostęp do tej operacji.

Użyj narzędzia GUID, aby wygenerować unikatowy identyfikator, który będzie używany dla identyfikatora przypisania roli. Identyfikator ma format: 00000000-0000-0000-0000-000000000000

Zacznij od następującego żądania:

PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

{
  "Properties": {
    "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
    "PrincipalId": "{principalId}",
    "RequestType": "AdminRemove"
    }
}

W identyfikatorze URI zastąp element {scope} zakresem usuwania przypisania roli.

Zakres	Typ
`providers/Microsoft.Management/managementGroups/{mg-name}`	Grupa zarządzania
`subscriptions/{subscriptionId}`	Subskrypcja
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1`	Grupa zasobów
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1`	Zasób

Zastąp element {roleAssignmentScheduleRequestName} identyfikatorem GUID przypisania roli.

Aktywowanie kwalifikującego się przypisania roli

Aby aktywować kwalifikujące się przypisanie roli (uzyskać aktywowany dostęp), użyj żądań harmonogramu przypisań ról — utwórz interfejs API REST, aby utworzyć nowe żądanie i określić podmiot zabezpieczeń, definicję roli, typ żądania = SelfActivate i zakres. Aby wywołać ten interfejs API, musisz mieć kwalifikujące się przypisanie roli w zakresie.

Użyj narzędzia GUID, aby wygenerować unikatowy identyfikator, który będzie używany dla identyfikatora przypisania roli. Identyfikator ma format: 00000000-0000-0000-0000-000000000000
[Opcjonalnie] Wybierz element RoleEligibilitySchedule , który chcesz aktywować, i pobierz element RoleEligibilityScheduleId z interfejsu API Harmonogramy uprawnień ról , który ma zostać przekazany jako LinkedRoleEligibilityScheduleId. Jest to opcjonalne, a jeśli system nie zostanie przekazany, wybierze wartość RoleEligibilitySchedule.

Zacznij od następującego żądania:

PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

 {
   "Properties": {
     "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
     "PrincipalId": "{principalId}",
     "RequestType": "SelfActivate",
     "ScheduleInfo": {
       "StartDateTime": "2020-09-09T21:31:27.91Z",
       "Expiration": {
         "Type": "AfterDuration", // Values: AfterDuration, AfterDateTime, NoExpiration
         "EndDateTime": null,
         "Duration": "PT8H" // Use ISO 8601 format
       }
     },
     "LinkedRoleEligibilityScheduleId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleAssignmentSchedules/{roleAssignmentScheduleId}" //Optional
   }
 }

W identyfikatorze URI zastąp element {scope} zakresem usuwania przypisania roli.

Zakres	Typ
`providers/Microsoft.Management/managementGroups/{mg-name}`	Grupa zarządzania
`subscriptions/{subscriptionId}`	Subskrypcja
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1`	Grupa zasobów
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1`	Zasób

Zastąp element {roleAssignmentScheduleRequestName} identyfikatorem GUID przypisania roli.

Dezaktywowanie aktywnego przypisania roli

Aby wyłączyć aktywowane przypisanie roli (usuń aktywowany dostęp), użyj żądań harmonogramu przypisań ról — utwórz interfejs API REST, aby utworzyć nowe żądanie i określić podmiot zabezpieczeń, definicję roli, wartość requestType = SelfDeactivate i zakres. Aby wywołać ten interfejs API, musisz mieć aktywowane przypisanie roli w zakresie.

Użyj narzędzia GUID, aby wygenerować unikatowy identyfikator, który będzie używany dla identyfikatora przypisania roli. Identyfikator ma format: 00000000-0000-0000-0000-000000000000

Zacznij od następującego żądania:

PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

 {
   "Properties": {
     "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
     "PrincipalId": "{principalId}",
     "RequestType": "SelfDeactivate"        
   }
 }

W identyfikatorze URI zastąp element {scope} zakresem usuwania przypisania roli.

Zakres	Typ
`providers/Microsoft.Management/managementGroups/{mg-name}`	Grupa zarządzania
`subscriptions/{subscriptionId}`	Subskrypcja
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1`	Grupa zasobów
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1`	Zasób

Zastąp element {roleAssignmentScheduleRequestName} identyfikatorem GUID przypisania roli.

Just-Enough-Access (JEA)

Jeśli użytkownik ma kwalifikujące się przypisanie roli w zasobie (nadrzędnym), może wybrać aktywowanie roli w zakresie poziomu podrzędnego zasobu nadrzędnego zamiast całego zakresu nadrzędnego. Jeśli na przykład użytkownik ma Contributor kwalifikowaną rolę w subskrypcji, może aktywować rolę na poziomie podrzędnej grupy zasobów subskrypcji.

Aby uzyskać listę wszystkich elementów podrzędnych zasobu, do którego masz uprawniony dostęp, możesz użyć interfejsu API Kwalifikowane zasoby podrzędne .

Zacznij od następującego żądania:

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/eligibleChildResources?api-version=2020-10-01&$filter={filter}

W identyfikatorze URI zastąp element {scope} zakresem, dla którego chcesz wyświetlić listę przypisań ról.

Zakres	Typ
`providers/Microsoft.Management/managementGroups/{mg-name}`	Grupa zarządzania
`subscriptions/{subscriptionId}`	Subskrypcja
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1`	Grupa zasobów

Zastąp element {filter} warunkiem, który chcesz zastosować, aby filtrować listę przypisań ról.

Filtr	Opis
`$filter=resourceType+eq+'Subscription'`	Wyświetl listę zasobów typu = "Subskrypcja".
`$filter=$filter=resourceType+eq+'subscription'+or+resourceType+eq+'resourcegroup''`	Wyświetl listę zasobów typu = "Subskrypcja" lub typ = "ResourceGroup".

id Użyj dowolnego zasobu podrzędnego do użycia jako scope elementu aktywacjiRoleAssignmentScheduleRequest

Typowe błędy zwracane dla nowego żądania

Poniżej znajduje się lista typowych błędów, które mogą wystąpić podczas tworzenia nowego żądania i sposobu ich ograniczania.

Komunikat o błędzie	Wygórowane	Ograniczanie ryzyka
`code`: RoleAssignmentExists `message`: Przypisanie roli już istnieje.	Podobne przypisanie roli już istnieje	`GET` Możesz to przypisanie roli i zweryfikować jego harmonogram.
`code`: RoleAssignmentRequestPolicyValidationFailed `message`: Następujące reguły zasad nie powiodły się: ["ExpirationRule"]	Określony `ScheduleInfo` w żądaniu przekracza maksymalny dozwolony czas trwania	W tym `RoleDefinitionId` celu możesz `GET` sprawdzić zasady RoleManagementPolicy`RoleManagementPolicyExpirationRule`
`code`: RoleAssignmentRequestPolicyValidationFailed `message`: Następujące reguły zasad nie powiodły się: ["UzasadnienieRule"]	Musisz określić element `Justification` w treści żądania	W tym `RoleDefinitionId` celu możesz `GET` sprawdzić zasady RoleManagementPolicy`RoleManagementPolicyEnablementRule`
`code`: RoleAssignmentRequestPolicyValidationFailed `message`: Następujące reguły zasad nie powiodły się: ["UprawnieniaRule"]	Prawidłowa `RoleEligibilityScheduleInstance` funkcja nie istnieje, aby aktywować tę rolę	Administrator zasobów musi utworzyć dla `RoleEligibilityScheduleRequest` tego podmiotu zabezpieczeń
`code`: RoleAssignmentRequestPolicyValidationFailed `message`: Następujące reguły zasad nie powiodły się: ["TicketingRule"]	Musisz określić element `TicketInfo` w treści żądania	W tym `RoleDefinitionId` celu możesz `GET` sprawdzić zasady RoleManagementPolicy`RoleManagementPolicyEnablementRule`
`code`: RoleAssignmentRequestPolicyValidationFailed `message`: Następujące reguły zasad nie powiodły się: ["MfaRule"]	Aby przesłać to żądanie, musisz ukończyć usługę Azure Multi-Factor Authentication	W tym `RoleDefinitionId` celu możesz `GET` sprawdzić zasady RoleManagementPolicy`RoleManagementPolicyEnablementRule`

Udostępnij za pośrednictwem

Zarządzanie aktywnym dostępem za pomocą interfejsu API REST przy użyciu usługi Azure PIM

Wyświetlanie listy aktywnych przypisań

Przyznaj aktywne przypisanie

Usuwanie aktywnego przypisania

Aktywowanie kwalifikującego się przypisania roli

Dezaktywowanie aktywnego przypisania roli

Just-Enough-Access (JEA)

Typowe błędy zwracane dla nowego żądania

Dodatkowe zasoby