Udostępnij za pośrednictwem

Używanie jednostek usługi i tożsamości zarządzanych w usłudze Azure DevOps

  • Artykuł

Azure DevOps Services

Uwaga

Azure Active Directory nosi teraz nazwę Microsoft Entra ID. Więcej informacji można znaleźć w sekcji Nowa nazwa usługi Azure AD.

Dodanie jednostek usługi Microsoft Entra i tożsamości zarządzanych do organizacji usługi Azure DevOps Services umożliwi im dostęp do zasobów organizacji. W przypadku wielu zespołów ta funkcja może być opłacalną i preferowaną alternatywą dla osobistych tokenów dostępu (PAT) podczas uwierzytelniania aplikacji, które przepływy pracy automatyzacji zasilania w firmie.

Informacje o jednostkach usługi i tożsamościach zarządzanych

Jednostki usługi to obiekty zabezpieczeń w aplikacji firmy Microsoft Entra, które definiują, co aplikacja może zrobić w danej dzierżawie. Są one konfigurowane w witrynie Azure Portal podczas procesu rejestracji aplikacji i skonfigurowane do uzyskiwania dostępu do zasobów platformy Azure, takich jak Azure DevOps. Dodając jednostki usługi do organizacji i konfigurując uprawnienia na ich podstawie, możemy określić, czy jednostka usługi jest autoryzowana do uzyskiwania dostępu do zasobów organizacji i które z nich.

Tożsamości zarządzane to inna funkcja firmy Microsoft Entra, która działa podobnie do jednostek usługi aplikacji. Te obiekty zapewniają tożsamości dla zasobów platformy Azure i umożliwiają łatwe korzystanie z usług obsługujących uwierzytelnianie Firmy Microsoft Entra w celu udostępniania poświadczeń. Jest to atrakcyjna opcja, ponieważ identyfikator Entra firmy Microsoft zajmuje się zarządzaniem poświadczeniami i rotacją. Podczas gdy konfiguracja tożsamości zarządzanej może wyglądać inaczej w witrynie Azure Portal, usługa Azure DevOps traktuje oba obiekty zabezpieczeń tak samo jak nowa tożsamość w organizacji ze zdefiniowanymi uprawnieniami. W pozostałej części tego artykułu odwołujemy się do tożsamości zarządzanych i jednostek usługi zamiennie jako jednostki usługi, chyba że określono.

Wykonaj poniższe kroki, aby uwierzytelnić te tożsamości w usłudze Azure DevOps, aby umożliwić im wykonywanie akcji w imieniu siebie.

Konfigurowanie tożsamości zarządzanych i jednostek usługi

Implementacja może się różnić, ale na wysokim poziomie poniższe kroki ułatwiają rozpoczęcie korzystania z jednostek usługi w przepływie pracy. Rozważ spojrzenie na jedną z naszych przykładowych aplikacji , aby móc naśladować.

1. Tworzenie nowej tożsamości zarządzanej lub jednostki usługi aplikacji

Utwórz jednostkę usługi aplikacji lub tożsamość zarządzaną w witrynie Azure Portal.

Tworzenie jednostki usługi aplikacji

Podczas tworzenia nowej rejestracji aplikacji obiekt aplikacji jest tworzony w identyfikatorze Entra firmy Microsoft. Jednostka usługi aplikacji jest reprezentacją tego obiektu aplikacji dla danej dzierżawy. Podczas rejestrowania aplikacji jako aplikacji wielodostępnej istnieje unikatowy obiekt jednostki usługi reprezentujący obiekt aplikacji dla każdej dzierżawy, do której jest dodawana aplikacja.

Dalsze informacje:

Tworzenie tożsamości zarządzanej

Tworzenie tożsamości zarządzanych w witrynie Azure Portal znacznie różni się od konfigurowania aplikacji z jednostkami usługi. Przed rozpoczęciem procesu tworzenia należy najpierw rozważyć typ tożsamości zarządzanej, którą chcesz utworzyć:

  • Tożsamość zarządzana przypisana przez system: niektóre usługi platformy Azure umożliwiają włączenie tożsamości zarządzanej bezpośrednio w wystąpieniu usługi. Po włączeniu tożsamości zarządzanej przypisanej przez system tożsamość jest tworzona w identyfikatorze Entra firmy Microsoft. Tożsamość jest powiązana z cyklem życia tego wystąpienia usługi. Po usunięciu zasobu platforma Azure automatycznie usunie tożsamość. Zgodnie z projektem tylko ten zasób platformy Azure może używać tej tożsamości do żądania tokenów z usługi Microsoft Entra ID.
  • Tożsamość zarządzana przypisana przez użytkownika Możesz również utworzyć tożsamość zarządzaną jako autonomiczny zasób platformy Azure, tworząc tożsamość zarządzaną przypisaną przez użytkownika i przypisując ją do co najmniej jednego wystąpienia usługi platformy Azure. W przypadku tożsamości zarządzanych przypisanych przez użytkownika tożsamość jest zarządzana oddzielnie od zasobów, które go używają.

Aby uzyskać więcej informacji, zobacz następujące artykuły i wideo:

2. Dodawanie jednostki usługi do organizacji usługi Azure DevOps

Po skonfigurowaniu jednostek usługi w centrum administracyjnym firmy Microsoft Entra należy wykonać to samo w usłudze Azure DevOps, dodając jednostki usługi do organizacji. Można je dodać za pośrednictwem strony Użytkownicy lub interfejsów API ServicePrincipalEntitlements. Ponieważ nie mogą się zalogować interaktywnie, konto użytkownika, które może dodawać użytkowników do organizacji, projektu lub zespołu, musi je dodać. Tacy użytkownicy obejmują administratorów kolekcji projektów (PCA) lub administratorów projektu i administratorów zespołu, gdy zasady "Zezwalaj administratorom zespołu i projektu na zapraszanie nowych użytkowników" są włączone.

Napiwek

Aby dodać jednostkę usługi do organizacji, wprowadź nazwę wyświetlaną aplikacji lub tożsamości zarządzanej. Jeśli zdecydujesz się programowo dodać jednostkę usługi za pośrednictwem interfejsu ServicePrincipalEntitlements API, pamiętaj, aby przekazać identyfikator obiektu jednostki usługi, a nie identyfikator obiektu aplikacji.

Jeśli jesteś pcA, możesz również udzielić jednostce usługi dostępu do określonych projektów i przypisać licencję. Jeśli nie jesteś pcA, musisz skontaktować się z PCA, aby zaktualizować wszystkie członkostwa w projekcie lub poziomy dostępu licencji.

Zrzut ekranu przedstawiający jednostki usługi i tożsamości zarządzane w centrum użytkowników.

Uwaga

Tożsamość zarządzana lub jednostka usługi dla dzierżawy, z którą jest połączona twoja organizacja, można dodać tylko tożsamość zarządzaną. Aby uzyskać dostęp do tożsamości zarządzanej w innej dzierżawie, zobacz obejście w często zadawanych pytaniach.

3. Ustawianie uprawnień dla jednostki usługi

Po dodaniu jednostek usługi do organizacji można je traktować podobnie jak standardowe konta użytkowników. Uprawnienia można przypisywać bezpośrednio do jednostki usługi, dodawać do grup zabezpieczeń i zespołów, przypisywać je do dowolnego poziomu dostępu i usuwać je z organizacji. Można również użyć polecenia Service Principal Graph APIs , aby wykonać operacje CRUD na jednostkach usługi.

Ustawienie tych uprawnień może różnić się od sposobu konfigurowania uprawnień aplikacji w aplikacji Microsoft Entra dla innych zasobów platformy Azure. Usługa Azure DevOps nie polega na konfiguracji "Uprawnienia aplikacji" dostępnej dla rejestracji aplikacji za pośrednictwem witryny Azure Portal. Te uprawnienia aplikacji mają zastosowanie do jednostki usługi we wszystkich organizacjach powiązanych z dzierżawą i nie mają wiedzy o organizacji, projekcie lub uprawnieniach obiektów dostępnych w usłudze Azure DevOps. Aby oferować jednostki usługi bardziej szczegółowe uprawnienia, polegamy na naszym modelu uprawnień zamiast identyfikatora Entra.

4. Zarządzanie jednostką usługi

Zarządzanie jednostkami usługi różni się od kont użytkowników w następujący sposób:

  • Jednostki usługi nie mają wiadomości e-mail i w związku z tym nie mogą być zapraszane do organizacji za pośrednictwem poczty e-mail.
  • Reguły grupy dotyczące licencjonowania nie mają obecnie zastosowania do jednostek usługi. Jeśli chcesz przypisać poziom dostępu do jednostki usługi, najlepiej jest to zrobić bezpośrednio.
  • Jednostki usługi można dodawać do grup firmy Microsoft Entra (w witrynie Azure Portal). Obecnie istnieje ograniczenie techniczne uniemożliwiające wyświetlanie ich na liście członków grupy Firmy Microsoft Entra. To ograniczenie nie jest prawdziwe w przypadku grup usługi Azure DevOps. Oznacza to, że jednostka usługi nadal dziedziczy wszystkie uprawnienia grupy ustawione na podstawie grupy Microsoft Entra, do której należą.
  • Użytkownicy w grupie Microsoft Entra nie będą natychmiast częścią organizacji usługi Azure DevOps, ponieważ administrator tworzy grupę i dodaje do niej grupę Firmy Microsoft Entra. Mamy proces o nazwie "materializacja", który występuje po pierwszym zalogowaniu użytkownika z grupy Microsoft Entra do organizacji. Użytkownik logujący się do organizacji pozwala nam określić, którzy użytkownicy powinni otrzymać licencję. Ponieważ logowanie nie jest możliwe dla jednostek usługi, administrator musi jawnie dodać go do organizacji zgodnie z wcześniejszym opisem.
  • Nie można zmodyfikować nazwy wyświetlanej ani awatara jednostki usługi w usłudze Azure DevOps.
  • Jednostki usługi uzyskują licencje w każdej organizacji, do której są dodawane, nawet jeśli wybrano rozliczeń dla wielu organizacji.

5. Uzyskiwanie tokenu Microsoft Entra ID

(a) Programowe pozyskiwanie tokenu Microsoft Entra ID

Uzyskanie tokenu dostępu dla tożsamości zarządzanej można wykonać zgodnie z dokumentacją identyfikatora entra firmy Microsoft. Zobacz przykłady dla zasad usługi i tożsamości zarządzanych .

Zwrócony token dostępu to token internetowy JSON (JWT) ze zdefiniowanymi rolami, który może służyć do uzyskiwania dostępu do zasobów organizacji przy użyciu tokenu jako elementu nośnego .

(b) Uzyskać token Microsoft Entra ID za pomocą Azure CLI

W przypadku operacji ad hoc może być łatwiej uzyskać jednorazowy token Microsoft Entra ID za pośrednictwem Azure CLI. Jest to preferowane podejście w przypadku operacji, które nie wymagają regularnego odnawiania trwałego tokenu, takich jak wywołania API lub operacje klonowania git.

wymagania wstępne

  • identyfikator dzierżawcy platformy Azure i identyfikator subskrypcji: Upewnij się, że subskrypcja jest skojarzona z dzierżawcą połączonym z organizacją usługi Azure DevOps, do której próbujesz uzyskać dostęp. Jeśli nie znasz identyfikatora dzierżawy lub subskrypcji, możesz go znaleźć w witrynie Azure Portal.
  • identyfikator klienta aplikacji platformy Azure i klucz tajny klienta
  • Azure CLI

Te instrukcje są dostarczane przez dokumentacji usługi Databricks i więcej szczegółów można znaleźć na ich stronie.

  1. Zaloguj się do interfejsu wiersza polecenia platformy Azure jako jednostki usługi przy użyciu polecenia az devops login.
  2. Postępuj zgodnie z instrukcjami wyświetlanymi na ekranie i zakończ logowanie.
# To authenticate a service principal with a password or cert:
az login --service-principal -u <app-id> -p <password-or-cert> --tenant <tenant>

# To authenticate a managed identity:
az login --identity
  1. Ustaw odpowiednią subskrypcję dla zalogowanej jednostki usługi, wprowadzając polecenie:
az account set -s <subscription-id>
  1. Wygeneruj token dostępu identyfikatora Entra firmy Microsoft przy użyciu az account get-access-token identyfikatora zasobu usługi Azure DevOps: 499b84ac-1321-427f-aa17-267ca6975798.
$accessToken = az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query "accessToken" --output tsv
  1. Teraz możesz używać az cli poleceń w zwykły sposób. Spróbujmy wywołać interfejs API usługi Azure DevOps, przekazując go w nagłówkach jako token Bearer:
$apiVersion = "7.1-preview.1"
$uri = "https://dev.azure.com/${yourOrgname}/_apis/projects?api-version=${apiVersion}"
$headers = @{
    Accept = "application/json"
    Authorization = "Bearer $accessToken"
}
Invoke-RestMethod -Uri $uri -Headers $headers -Method Get | Select-Object -ExpandProperty value ` | Select-Object id, name

Uwaga

Użyj identyfikatora aplikacji usługi Azure DevOps, a nie identyfikatora URI zasobu do generowania tokenów.

6. Użyj tokenu identyfikatora Entra firmy Microsoft do uwierzytelniania w zasobach usługi Azure DevOps

W poniższym przykładzie wideo przechodzimy od uwierzytelniania za pomocą tokenu PAT do używania tokenu z jednostki usługi. Zaczynamy od używania klucza tajnego klienta do uwierzytelniania, a następnie przechodzimy do korzystania z certyfikatu klienta.

Inny przykład przedstawia sposób nawiązywania połączenia z usługą Azure DevOps przy użyciu tożsamości zarządzanej przypisanej przez użytkownika w ramach funkcji platformy Azure.

Postępuj zgodnie z tymi przykładami, wyszukując kod aplikacji w naszej kolekcji przykładowych aplikacji.

Niektóre typowe scenariusze uwierzytelniania za pomocą podmiotów usługi, poza wywoływaniem interfejsu API REST usługi Azure DevOps, można znaleźć w następujących zasobach:

Czym różnią się jednostki usługi od użytkowników?

  • Nie można zmodyfikować nazwy wyświetlanej ani awatara jednostki usługi w usłudze Azure DevOps.
  • Jednostka usługi liczy się jako licencja dla każdej organizacji, do których jest dodawana, nawet jeśli wybrano rozliczenia w wielu organizacjach.
  • Jednostki usług nie mogą być właścicielami organizacji ani tworzeniem organizacji.
  • Jednostki usługi nie mogą tworzyć tokenów, takich jak osobiste tokeny dostępu (PAT) lub klucze SSH. Mogą oni wygenerować własne tokeny identyfikatora Entra firmy Microsoft, a te tokeny mogą służyć do wywoływania interfejsów API REST usługi Azure DevOps.
  • Nie obsługujemy usługi Azure DevOps OAuth dla jednostek usługi.

Często zadawane pytania

Ogólne

Pytanie: Dlaczego należy używać jednostki usługi lub tożsamości zarządzanej zamiast identyfikatora PAT?

1: Wielu naszych klientów szuka jednostki usługi lub tożsamości zarządzanej, aby zastąpić istniejący token dostępu (osobisty token dostępu). Takie sieci PAT często należą do konta usługi (udostępnionego konta zespołu), które używa ich do uwierzytelniania aplikacji za pomocą zasobów usługi Azure DevOps. PaTs muszą być pracochłonne obracane co tak często (co najmniej 180 dni). Nieprawidłowo przechowywane PAT-y mogą trafić w niepowołane ręce i być używane przez cały okres ich często dłuższej żywotności. Tokeny firmy Microsoft Entra wygasają co godzinę, ograniczając ogólny czynnik ryzyka po wycieku. W przypadku typowych scenariuszy PAT udostępniamy kilka przykładów na temat tego, jak można rozważyć użycie tokenu Entra firmy Microsoft zamiast.

Nie można użyć jednostki usługi do utworzenia osobistego tokenu dostępu.

.: Jakie są limity szybkości dla jednostek usługi i tożsamości zarządzanych?

1: Jednostki usługi i tożsamości zarządzane mają te same limity szybkości co użytkownicy.

.: Czy korzystanie z tej funkcji będzie kosztować więcej?

1: Jednostki usługi i tożsamości zarządzane są wyceniane podobnie jak użytkownicy na podstawie poziomu dostępu. Jedną z godnych uwagi zmianą jest sposób traktowania "rozliczeń w wielu organizacjach" dla jednostek usługi. Użytkownicy są liczeni jako tylko jedna licencja, niezależnie od liczby organizacji, w których się znajdują. Jednostki usługi są liczone jako jedna licencja na każdą organizację, w której znajduje się użytkownik. Ten scenariusz jest podobny do standardowych "rozliczeń opartych na przypisaniach użytkowników".

.: Czy mogę dodać tożsamość zarządzaną z innej dzierżawy do mojej organizacji?

1: Tożsamość zarządzana można dodać tylko z tej samej dzierżawy, z którą jest połączona Twoja organizacja. Mamy jednak obejście, które umożliwia skonfigurowanie tożsamości zarządzanej w "dzierżawie zasobów", gdzie znajdują się wszystkie zasoby. Następnie możesz zezwolić na korzystanie z niej przez jednostkę usługi w "dzierżawie docelowej", w której twoja organizacja jest połączona. Wykonaj następujące kroki jako obejście:

  1. Utwórz tożsamość zarządzaną przypisaną przez użytkownika w witrynie Azure Portal dla dzierżawy zasobów.
  2. Połącz ją z maszyną wirtualną i przypisz do niej tę tożsamość zarządzaną.
  3. Utwórz magazyn kluczy i wygeneruj certyfikat (nie może być typu "PEM"). Podczas generowania tego certyfikatu jest również generowany wpis tajny o tej samej nazwie, którego używamy później.
  4. Udziel dostępu do tożsamości zarządzanej, aby mógł odczytywać klucz prywatny z magazynu kluczy. Utwórz zasady dostępu w magazynie kluczy z uprawnieniami "Get/List" (w obszarze "Uprawnienia wpisu tajnego" i wyszukaj tożsamość zarządzaną w obszarze "Wybierz podmiot zabezpieczeń".
  5. Pobierz utworzony certyfikat w formacie CER, co gwarantuje, że nie zawiera prywatnej części certyfikatu.
  6. Utwórz nową rejestrację aplikacji w dzierżawie docelowej.
  7. Przekaż pobrany certyfikat do tej nowej aplikacji na karcie "Certyfikaty i wpisy tajne".
  8. Dodaj jednostkę usługi tej aplikacji do organizacji usługi Azure DevOps, do której chcemy uzyskać dostęp i zapamiętać, aby skonfigurować jednostkę usługi z wymaganymi uprawnieniami.
  9. Pobierz token dostępu firmy Microsoft Entra z tej jednostki usługi, która korzysta z certyfikatu tożsamości zarządzanej przy użyciu tego przykładu kodu:

Uwaga

Zawsze regularnie wymieniaj certyfikaty.

public static async Task<string> GetSecret(string keyVaultName, string secretName)
{
	var keyVaultUri = new Uri("https://" + keyVaultName + ".vault.azure.net");
	var client = new SecretClient(keyVaultUri, new ManagedIdentityCredential());
	var keyVaultSecret = await client.GetSecretAsync(secretName);

	var secret = keyVaultSecret.Value;
	return secret.Value;
}

private static async Task<AuthenticationResult> GetAppRegistrationAADAccessToken(string applicationClientID, string appTenantId)
{
	IConfidentialClientApplication app;

	byte[] privateKeyBytes = Convert.FromBase64String(GetSecret(keyVaultName, secretName));
	X509Certificate2 certificateWithPrivateKey = new X509Certificate2(privateKeyBytes, (string)null, X509KeyStorageFlags.MachineKeySet);

	app = ConfidentialClientApplicationBuilder.Create(applicationClientID)
		.WithCertificate(certificateWithPrivateKey)
		.WithAuthority(new Uri(string.Format(CultureInfo.InvariantCulture, "https://login.microsoftonline.com/{0}", appTenantId)))
		.Build();
	app.AddInMemoryTokenCache();

	string AdoAppClientID = "499b84ac-1321-427f-aa17-267ca6975798/.default";
	string[] scopes = new string[] { AdoAppClientID };

	var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();

	return result;
}

Potencjalne błędy

Repozytorium Git o nazwie lub identyfikatorze {repoName}nie istnieje lub nie masz uprawnień do operacji, którą próbujesz wykonać.

Upewnij się, że podmiot usługi ma co najmniej licencję "Podstawowa", aby uzyskać dostęp do repozytoriów. Licencja "Uczestnik projektu" nie jest wystarczająca.

Nie można utworzyć jednostki usługi o identyfikatorze obiektu "{provided objectId}"

Nie ma jednostki usługi z dzierżawą połączoną z provided objectId twoją organizacją. Jedną z typowych przyczyn jest przekazanie identyfikatora obiektu rejestracji aplikacji zamiast identyfikatora obiektu jednostki usługi. Pamiętaj, że jednostka usługi jest obiektem reprezentującym aplikację dla danej dzierżawy, a nie samą aplikacją. Element service principal object ID można znaleźć na stronie "Aplikacje dla przedsiębiorstw" dzierżawy. Wyszukaj nazwę aplikacji i wybierz wynik "Aplikacja dla przedsiębiorstw", który zwraca. Ten wynik jest stroną jednostki usługi/aplikacji dla przedsiębiorstw i można użyć identyfikatora obiektu znalezionego na tej stronie, aby utworzyć jednostkę usługi w usłudze Azure DevOps.

Odmowa dostępu: {ID of the caller identity} wymaga następujących uprawnień do zasobu Użytkownicy, aby wykonać tę akcję: Dodaj użytkowników

Ten błąd może być spowodowany jedną z następujących przyczyn:

  • Nie jesteś właścicielem organizacji, administratora kolekcji projektów ani administratora projektu lub zespołu.
  • Jesteś administratorem projektu lub zespołu, ale zasady "Zezwalaj administratorom zespołu i projektu na zapraszanie nowych użytkowników" są wyłączone.
  • Jesteś administratorem projektu lub zespołu, który może zaprosić nowych użytkowników, ale próbujesz przypisać licencję podczas zapraszania nowego użytkownika. Administratorzy projektu lub zespołu nie mogą przypisywać licencji do nowych użytkowników. Każdy nowy zaproszony użytkownik zostanie dodany na domyślnym poziomie dostępu dla nowych użytkowników. Skontaktuj się z pca, aby zmienić poziom dostępu do licencji.

API Graph List usługi Azure DevOps zwraca pustą listę, mimo że wiemy, że w organizacji istnieją główne usługi.

Interfejs API listy wykresów usługi Azure DevOps może zwracać pustą listę, nawet jeśli jest jeszcze więcej stron, które mają zostać zwrócone. Użyj elementu , continuationToken aby wykonać iteracje na listach i w końcu można znaleźć stronę, na której są zwracane jednostki usługi. continuationToken Jeśli element zostanie zwrócony, oznacza to, że za pośrednictwem interfejsu API jest dostępnych więcej wyników. Chociaż planujemy ulepszyć tę logikę, w tej chwili możliwe jest, że pierwsze wyniki X zwracają puste.

TF401444: Zaloguj się co najmniej raz jako {tenantId'tenantId\servicePrincipalObjectId'} w przeglądarce internetowej, aby umożliwić dostęp do usługi.

Jeśli jednostka usługi nie została zaproszona do organizacji, może wystąpić następujący błąd. Upewnij się, że jednostka usługi została dodana do odpowiedniej organizacji i ma wszystkie uprawnienia wymagane do uzyskania dostępu do wszystkich wymaganych zasobów.