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 (Azure AD) to teraz Microsoft Entra ID. Więcej informacji można znaleźć w sekcji Nowa nazwa usługi Azure AD.

Dodaj Microsoft Entra zasady usługi i tożsamości zarządzane jako tożsamości aplikacji do organizacji Azure DevOps Services, aby przyznać 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 ułatwiają automatyzację przepływów pracy w firmie.

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

Zasady usługi to obiekty zabezpieczeń w aplikacji 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 Microsoft Entra, która działa w sposób podobny do ról 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ść aplikacji w organizacji ze zdefiniowanymi uprawnieniami. W pozostałej części tego artykułu określamy tożsamości zarządzane i jednostki usługi zamiennie jako "jednostka usługi", chyba że podano inaczej.

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 pryncypałów 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. Aby nadążać, rozważ przyjrzenie się jednej z naszych przykładowych aplikacji.

1. Utwórz nową tożsamość zarządzaną lub główną usługę aplikacji

Utwórz główne konto usługowe aplikacji lub zarządzaną tożsamość w portalu Azure.

Opcja 1: Tworzenie głównej aplikacji usługi

Podczas tworzenia nowej rejestracji aplikacji obiekt aplikacji jest tworzony w identyfikatorze Entra firmy Microsoft. Główna usługa aplikacji jest reprezentacją tego obiektu aplikacji dla danego 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:

Opcja 2. 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 automatycznie 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 zarządzanej tożsamości przypisanej przez system, tożsamość jest tworzona w Microsoft Entra ID. Tożsamość jest powiązana z cyklem życia tego wystąpienia usługi. Po usunięciu zasobu platforma Azure automatycznie usunie tożsamość dla ciebie. 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 jednego lub więcej wystąpień 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 za pomocą interfejsów API ServicePrincipalEntitlements. Ponieważ oni nie mogą się zalogować interaktywnie, konto użytkownika, które może dodawać użytkowników do organizacji, projektu lub zespołu, musi ich 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 pomocą interfejsu API ServicePrincipalEntitlements, pamiętaj o przekazaniu identyfikatora obiektu jednostki usługi , a nie identyfikatora obiektu aplikacji.

Jeśli jesteś PCA, możesz przyznać głównej nazwie usługi dostęp do określonych projektów i przypisać licencję. Jeśli nie jesteś PCA, musisz skontaktować się z PCA, aby zaktualizować członkostwa w projekcie lub poziomy dostępu do licencji.

Zrzut ekranu przedstawiający zasadnicze jednostki usługi i tożsamości zarządzane w Users Hub.

Uwaga

Można dodać tylko zarządzaną tożsamość lub główny obiekt usługi dla dzierżawy, z którą jest połączona twoja organizacja. Zasady usługi można zmienić na wielodostępne, aby uzyskać dostęp do wielu dzierżaw jednocześnie. Tożsamości zarządzane mogą należeć tylko do jednego dzierżawcy. Aby uzyskać dostęp do tożsamości zarządzanej w innej dzierżawie, zobacz rozwiązanie w FAQ.

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 identyfikatorów Entra firmy Microsoft.

4. Zarządzanie jednostką usługi (service principal)

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 grupy Microsoft Entra nie stają się automatycznie częścią organizacji Azure DevOps tylko dlatego, że administrator utworzy i doda do niej grupę 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 podmiotów usługi, administrator musi jawnie dodać je do organizacji zgodnie z wcześniejszym opisem.
  • Nie można zmodyfikować nazwy wyświetlanej ani awatara jednostki usługi w usłudze Azure DevOps.
  • Podmioty usługi uzyskują licencje w każdej organizacji, do której są dodawane, nawet jeśli wybrano rozliczanie 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 uzyskać zgodnie z dokumentacją Microsoft Entra ID. 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 dokumentację Databricks, a więcej szczegółów można znaleźć na ich stronie internetowej.

  1. Zaloguj się do Azure CLI jako główna usługa, używając 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 z użyciem tożsamości usługi, inne niż wykonywanie wywołań API REST dla Azure DevOps, można znaleźć w następujących dokumentach:

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 jest liczone jako licencja dla każdej organizacji, do których dołącza, nawet w przypadku rozliczeń w wielu organizacjach.
  • Jednostki usługowe nie mogą być właścicielami organizacji ani tworzyć organizacji.
  • Jednostki usługi nie mogą tworzyć tokenów, takich jak osobistych tokenów dostępu (PATs) lub kluczy SSH . Mogą oni wygenerować własne tokeny Microsoft Entra ID do wywoływania interfejsów API REST usługi Azure DevOps.
  • Jednostki usługi nie obsługują usługi Azure DevOps OAuth.

Często zadawane pytania

Pytanie: Dlaczego powinienem używać jednostki usługi lub tożsamości zarządzanej zamiast osobistego tokenu dostępu (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ć regularnie obracane co pewien czas (minimum co 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?

Podstawowe zasady usług i tożsamości zarządzane są wyceniane podobnie do użytkowników 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ą. Główne 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?

Można dodać tożsamość zarządzaną tylko od tego samego dzierżawcy, z którym połączona jest 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 w portalu Azure przypisaną przez użytkownika tożsamość zarządzaną 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, który nie może być typu "PEM". Podczas generowania tego certyfikatu generowany jest również sekret o tej samej nazwie, który używamy później.
  4. Udziel dostępu do tożsamości zarządzanej, aby mogła odczytywać klucz prywatny z magazynu kluczy. Utwórz zasady dostępu w Key Vault z uprawnieniami "Get/List" (w sekcji "Uprawnienia tajnych informacji" i wyszukaj zarządzaną tożsamość w sekcji "Wybierz podmiot").
  5. Pobierz utworzony certyfikat w formacie CER, co gwarantuje, że nie zawiera prywatnej części certyfikatu.
  6. Utwórz nową rejestrację aplikacji w tenancie docelowym.
  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 przyznać dostęp, i pamiętaj, 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 istnieje jednostka usługi z provided objectId w dzierżawie powiązanej z 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 dzierżawy "Aplikacje dla przedsiębiorstw". 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 continuationToken do iteracji przez listy, aby w końcu znaleźć stronę, na której zwracane są jednostki główne usługi. Jeśli zostanie zwrócony continuationToken, 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żesz napotkać 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.