Sdílet prostřednictvím

Použití instančních objektů a spravovaných identit v Azure DevOps

  • Článek

Služby Azure DevOps

Poznámka:

Azure Active Directory je nyní Microsoft Entra ID. Další informace najdete v článku Nový název pro Azure AD.

Přidání služebních principálů Microsoft Entra a spravovaných identit do organizací Azure DevOps Services poskytne přístup k prostředkům vaší organizace. U mnoha týmů může být tato funkce proveditelnou a upřednostňovanou alternativou k tokenům PAT při ověřování aplikací, které ve vaší společnosti používají pracovní postupy automatizace výkonu.

O instančních objektech a spravovaných identitách

Instanční objekty jsou objekty zabezpečení v aplikaci Microsoft Entra, které definují, co může aplikace v daném tenantovi dělat. Nastaví se na webu Azure Portal během procesu registrace aplikace a nakonfiguruje se pro přístup k prostředkům Azure, jako je Azure DevOps. Přidáním instančních objektů do vaší organizace a nastavením oprávnění nad nimi můžeme zjistit, jestli má instanční objekt oprávnění pro přístup k prostředkům organizace a k jakým prostředkům organizace má oprávnění.

Spravované identity jsou další funkcí Microsoft Entra, která funguje podobně jako instanční objekty aplikace. Tyto objekty poskytují identity pro prostředky Azure a umožňují snadný způsob, jak služby podporující ověřování Microsoft Entra sdílet přihlašovací údaje. Jedná se o atraktivní možnost, protože id Microsoft Entra se stará o správu a obměnu přihlašovacích údajů. I když nastavení spravované identity může vypadat jinak na webu Azure Portal, Azure DevOps považuje oba objekty zabezpečení za stejné jako novou identitu v organizaci s definovanými oprávněními. Ve zbytku tohoto článku odkazujeme na spravované identity a instanční objekty zaměnitelně jako instanční objekt, pokud není uvedeno.

Pomocí následujících kroků ověřte tyto identity v Azure DevOps, abyste jim umožnili provádět akce jménem sebe sama.

Konfigurace spravovaných identit a instančních objektů

Vaše implementace se může lišit, ale na vysoké úrovni vám následující kroky pomůžou začít používat instanční objekty ve vašem pracovním postupu. Zvažte, zda se chcete podívat na jednu z našich ukázkových aplikací , abyste mohli sledovat.

1. Vytvoření nové spravované identity nebo instančního objektu aplikace

Na webu Azure Portal vytvořte instanční objekt aplikace nebo spravovanou identitu .

Vytvoření instančního objektu aplikace

Při vytváření nové registrace aplikace se vytvoří objekt aplikace v Microsoft Entra ID. Instanční objekt aplikace představuje tento objekt aplikace pro daného tenanta. Když zaregistrujete aplikaci jako víceklientskou aplikaci, existuje jedinečný objekt instančního objektu, který představuje objekt aplikace pro každého tenanta, do kterého se aplikace přidá.

Další informace:

Vytvoření spravované identity

Vytváření spravovaných identit na webu Azure Portal se výrazně liší od nastavení aplikací s instančními objekty. Než začnete s procesem vytváření, musíte nejprve zvážit, jaký typ spravované identity chcete vytvořit:

  • Spravovaná identita přiřazená systémem: Některé služby Azure umožňují povolit spravovanou identitu přímo v instanci služby. Když povolíte spravovanou identitu přiřazenou systémem, vytvoří se identita v Microsoft Entra ID. Identita je svázaná s životním cyklem této instance služby. Když se prostředek odstraní, Azure automaticky odstraní identitu za vás. Z podstaty této identity vyplývá, že ji může k vyžadování tokenů z Microsoft Entra ID používat pouze daný prostředek Azure.
  • Spravovanou identitu přiřazenou uživatelem můžete také vytvořit jako samostatný prostředek Azure tak, že vytvoříte spravovanou identitu přiřazenou uživatelem a přiřadíte ji k jedné nebo více instancím služby Azure. Pro spravované identity přiřazené uživatelem se identita spravuje odděleně od prostředků, které ji používají.

Další informace najdete v následujících článcích a videu:

2. Přidání instančního objektu do organizace Azure DevOps

Jakmile nakonfigurujete instanční objekty v Centru pro správu Microsoft Entra, musíte to udělat v Azure DevOps přidáním instančních objektů do vaší organizace. Můžete je přidat prostřednictvím stránky Uživatelé nebo pomocí rozhraní API ServicePrincipalEntitlements. Vzhledem k tomu, že se nemůžou interaktivně přihlásit, musí je přidat uživatelský účet, který může přidávat uživatele do organizace, projektu nebo týmu. Tito uživatelé zahrnují správce kolekcí projektů (PCA) nebo správce projektů a správce týmu, pokud je povolená zásada Povolit správcům týmů a projektů pozvat nové uživatele.

Tip

Pokud chcete do organizace přidat instanční objekt, zadejte zobrazovaný název aplikace nebo spravované identity. Pokud se rozhodnete instanční objekt přidat prostřednictvím kódu programu prostřednictvím ServicePrincipalEntitlements rozhraní API, nezapomeňte předat ID objektu instančního objektu, nikoli ID objektu aplikace.

Pokud jste PCA, můžete také udělit instančnímu objektu přístup ke konkrétním projektům a přiřadit licenci. Pokud nejste PCA, musíte se obrátit na PCA, abyste aktualizovali členství v projektu nebo úrovně přístupu k licencím.

Snímek obrazovky s instančními objekty a spravovanými identitami v centru Users Hub

Poznámka:

Spravovanou identitu nebo instanční objekt můžete přidat jenom pro tenanta, ke kterému je vaše organizace připojená. Pokud chcete získat přístup ke spravované identitě v jiném tenantovi, podívejte se na alternativní řešení v nejčastějších dotazech.

3. Nastavení oprávnění pro instanční objekt

Po přidání instančních objektů do organizace s nimi můžete zacházet podobně jako se standardními uživatelskými účty. Oprávnění můžete přiřadit přímo u instančního objektu, přidat ho do skupin zabezpečení a týmů, přiřadit je k libovolné úrovni přístupu a odebrat je z organizace. Můžete také použít Service Principal Graph APIs k provádění operací CRUD s instančními objekty.

Nastavení těchto oprávnění se může lišit od způsobu nastavení oprávnění aplikace v aplikaci Microsoft Entra pro jiné prostředky Azure. Azure DevOps nespoléhá na nastavení Oprávnění aplikace dostupná pro registrace aplikací prostřednictvím webu Azure Portal. Tato aplikační oprávnění se vztahují na služebního principála napříč všemi organizacemi spojenými s tenantem a nemají žádné informace o organizačních oprávněních, projektech ani oprávněních k objektům dostupným v rámci Azure DevOps. Abychom mohli service principálům nabídnout podrobnější oprávnění, spoléháme na vlastní model oprávnění místo Entra ID.

4. Správa instančního objektu

Správa instančních objektů se liší od uživatelských účtů následujícími klíčovými způsoby:

  • Instanční objekty nemají e-maily a proto je nejde pozvat do organizace e-mailem.
  • Pravidla skupin pro licencování se v současné době nevztahují na instanční objekty. Pokud chcete instančnímu objektu přiřadit úroveň přístupu, je nejlepší to udělat přímo.
  • Servisní principy je možné přidat do skupin Microsoft Entra (v Azure portálu). V současné době existuje technické omezení, které nám brání v tom, abychom je mohli zobrazit v seznamu členů skupiny Microsoft Entra. Toto omezení neplatí pro skupiny Azure DevOps. To znamená, že instanční objekt stále dědí všechna oprávnění skupiny nastavená nad skupinou Microsoft Entra, do které patří.
  • Uživatelé ve skupině Microsoft Entra nebudou součástí organizace Azure DevOps okamžitě, protože správce vytvoří skupinu a přidá do ní skupinu Microsoft Entra. Máme proces označovaný jako materializace, který se stane, když se uživatel ze skupiny Microsoft Entra poprvé přihlásí k organizaci. Uživatel, který se přihlašuje k organizaci, nám umožňuje určit, kteří uživatelé by měli mít udělenou licenci. Vzhledem k tomu, že přihlášení není možné pro instanční objekty, musí ho správce explicitně přidat do organizace, jak je popsáno výše.
  • V Azure DevOps nemůžete změnit zobrazovaný název ani avatar instančního objektu.
  • Služební principály získají licence v každé organizaci, do které se přidají, i když je vybrána fakturace ve více organizacích.

5. Získání tokenu MICROSOFT Entra ID

a) Programově získejte token Microsoft Entra ID.

Získání přístupového tokenu pro spravovanou identitu je možné provést pomocí dokumentace k Microsoft Entra ID. Podívejte se na příklady služby principalů a spravovaných identit.

Vrácený přístupový token je webový token JSON (JWT) s definovanými rolemi, které lze použít pro přístup k prostředkům organizace pomocí tokenu jako Bearer.

(b) Získání tokenu MICROSOFT Entra ID pomocí Azure CLI

U ad hoc operací může být snazší získat jednorázový token ID Microsoft Entra prostřednictvím Azure CLI. Tento přístup je upřednostňovaný pro operace, které nevyžadují pravidelné obměny trvalý token, jako jsou volání rozhraní API nebo operace klonování Gitu.

požadavky

  • ID tenanta Azure a ID předplatného: Ujistěte se, že je předplatné přidružené k tenantovi připojenému k organizaci Azure DevOps, ke které se pokoušíte získat přístup. Pokud neznáte ID tenanta nebo předplatného, najdete ho na webu azure Portal.
  • ID klienta aplikace Azure a tajný klíč klienta
  • Azure CLI

Tyto pokyny poskytuje dokumentace k Databricks a další podrobnosti najdete na jejich stránce.

  1. Přihlaste se k Azure CLI jako služební principál pomocí příkazu az devops login.
  2. Postupujte podle pokynů na obrazovce a dokončete přihlášení.
# 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. Zadáním příkazu nastavíte správné předplatné pro přihlášený instanční objekt:
az account set -s <subscription-id>
  1. Vygenerujte přístupový token Microsoft Entra ID pomocí az account get-access-token ID prostředku Azure DevOps: 499b84ac-1321-427f-aa17-267ca6975798.
$accessToken = az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query "accessToken" --output tsv
  1. Teď můžete použít az cli příkazy podle obvyklého použití. Zkusme volat rozhraní Azure DevOps API předáním tokenu Bearer v hlavičkách:
$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

Poznámka:

K vygenerování tokenů použijte ID aplikace Azure DevOps, ne identifikátor URI prostředku.

6. K ověření prostředků Azure DevOps použijte token ID Microsoft Entra.

V následujícím příkladu videa přecházíme z ověřování pomocí pat na použití tokenu z instančního objektu. Začneme používat tajný klíč klienta pro ověřování a pak přejdeme k použití klientského certifikátu.

Další příklad ukazuje, jak se připojit k Azure DevOps pomocí spravované identity přiřazené uživatelem v rámci funkce Azure Functions.

Postupujte podle těchto příkladů vyhledáním kódu aplikace v naší kolekci ukázkových aplikací.

Některé běžné scénáře ověřování pomocí služebních principálů kromě volání rozhraní REST API Azure DevOps najdete v těchto prostředcích:

Jak se služební identity liší od uživatelů?

  • V Azure DevOps nemůžete změnit zobrazovaný název ani avatar instančního objektu.
  • Instanční objekt se počítá jako licence pro každou organizaci, do které se přidá, i když je vybrána fakturace ve více organizacích.
  • Instanční objekty nemůžou být vlastníky organizace ani vytvářet organizace.
  • Instanční objekty nemůžou vytvářet tokeny, jako jsou osobní přístupové tokeny (PAT) nebo klíče SSH. Můžou vygenerovat vlastní tokeny ID Microsoft Entra a tyto tokeny je možné použít k volání rozhraní REST API Azure DevOps.
  • Azure DevOps OAuth nepodporujeme pro instanční objekty.

Nejčastější dotazy

OBECNÉ

Otázka: Proč mám místo PAT používat instanční objekt nebo spravovanou identitu?

A: Mnozí naši zákazníci hledají instanční objekt nebo spravovanou identitu, aby nahradili stávající token PAT (personal access token). Takové paty často patří k účtu služby (sdílený týmový účet), který je používá k ověření aplikace pomocí prostředků Azure DevOps. PAT se musí pracně otáčet každých tolikrát (minimálně 180 dní). Nesprávně uložené PATy se mohou dostat do nesprávných rukou a vydržet po dobu jejich často delší životnosti. Platnost tokenů Microsoft Entra vyprší každou hodinu, což omezuje celkový rizikový faktor při úniku. V běžných scénářích PAT některé příklady, jak můžete prozkoumat použití tokenu Microsoft Entra místo toho.

Instanční objekt nemůžete použít k vytvoření osobního přístupového tokenu.

Otázka: Jaké jsou limity četnosti instančních objektů a spravovaných identit?

A: Instanční objekty a spravované identity mají stejné limity rychlosti jako uživatelé.

Otázka: Bude použití této funkce stát více?

A: Instanční objekty a spravované identity jsou cenově podobné jako uživatelé na základě úrovně přístupu. Jedna z hledných změn se týká toho, jak zacházíme s "fakturací více organizací" pro instanční objekty. Uživatelé se započítávají jenom jako jedna licence bez ohledu na to, kolik organizací se nachází. Instanční objekty se počítají jako jedna licence pro každou organizaci, ve které uživatel je. Tento scénář se podobá standardní fakturaci na základě přiřazení uživatele.

Otázka: Můžu do své organizace přidat spravovanou identitu z jiného tenanta?

A: Spravovanou identitu můžete přidat jenom ze stejného tenanta, ke kterému je vaše organizace připojená. Máme ale alternativní řešení, které umožňuje nastavit spravovanou identitu v tenantovi prostředků, kde jsou všechny vaše prostředky. Potom ho můžete povolit, aby ho používal instanční objekt v cílovém tenantovi, kde je vaše organizace připojená. Jako alternativní řešení postupujte následovně:

  1. Vytvořte spravovanou identitu přiřazenou uživatelem na webu Azure Portal pro vašeho tenanta prostředků.
  2. Připojte ho k virtuálnímu počítači a přiřaďte jí tuto spravovanou identitu .
  3. Vytvořte trezor klíčů a vygenerujte certifikát (nesmí být typu PEM). Když tento certifikát vygenerujete, vygeneruje se také tajný kód se stejným názvem, který použijeme později.
  4. Udělte přístup ke spravované identitě, aby mohl číst privátní klíč z trezoru klíčů. Vytvořte zásadu přístupu v trezoru klíčů s oprávněními Get/List (v části Oprávnění tajných kódů a vyhledejte spravovanou identitu v části Vybrat objekt zabezpečení.
  5. Stáhněte vytvořený certifikát ve formátu CER, který zajistí, že neobsahuje soukromou část vašeho certifikátu.
  6. Vytvořte novou registraci aplikace v cílovém tenantovi.
  7. Nahrajte stažený certifikát do této nové aplikace na kartě Certifikáty a tajné kódy.
  8. Přidejte instanční objekt této aplikace do organizace Azure DevOps, ke které chceme získat přístup, a nezapomeňte nastavit instanční objekt se všemi požadovanými oprávněními.
  9. Získejte přístupový token Microsoft Entra z tohoto instančního objektu, který používá certifikát spravované identity s tímto vzorovým kódem:

Poznámka:

Certifikáty pravidelně obměňujte.

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;
}

Potenciální chyby

Úložiště Git s názvem nebo identifikátorem {repoName} neexistuje nebo nemáte oprávnění k operaci, kterou se pokoušíte.

Ujistěte se, že instanční objekt má alespoň licenci Basic pro přístup k úložištím. Licence účastníka nestačí.

Vytvoření instančního objektu s ID objektu {provided objectId} se nezdařilo.

V tenantovi připojeném provided objectId k vaší organizaci není žádný instanční objekt. Jedním z běžných důvodů je, že předáváte ID objektu registrace aplikace místo ID objektu jeho instančního objektu. Nezapomeňte, že instanční objekt je objekt, který představuje aplikaci pro daného tenanta, nejedná se o samotnou aplikaci. Najdete ji service principal object ID na stránce Podnikové aplikace vašeho tenanta. Vyhledejte název aplikace a vyberte výsledek "Podniková aplikace", který se vrátí. Tento výsledek je stránka instančního objektu nebo podnikové aplikace a id objektu, které najdete na této stránce, můžete použít k vytvoření instančního objektu v Azure DevOps.

Přístup byl odepřen: {ID of the caller identity} potřebuje k provedení této akce následující oprávnění pro uživatele prostředku: Přidat uživatele

Příčinou této chyby může být jeden z následujících důvodů:

  • Nejste vlastníkem organizace, správce kolekce projektů ani projekt nebo správce týmu.
  • Jste správcem projektu nebo týmu, ale zásada Povolit správcům týmů a projektů pozvat nové uživatele je zakázaná.
  • Jste projekt nebo správce týmu, který může pozvat nové uživatele, ale pokoušíte se přiřadit licenci, když pozvete nového uživatele. Správci projektu nebo týmu nemají oprávnění přiřazovat licenci novým uživatelům. Každý nový pozvaný uživatel se přidá na výchozí úroveň přístupu pro nové uživatele. Pokud chcete změnit úroveň přístupu k licencím, obraťte se na PCA.

Rozhraní Azure DevOps Graph List API vrací prázdný seznam, přestože víme, že v organizaci existují služební principály.

Rozhraní Azure DevOps Graph List API může vrátit prázdný seznam, i když se vrátí ještě více stránek uživatelů. continuationToken Pomocí iterace v seznamech a nakonec můžete najít stránku, kde se vrátí instanční objekty. Pokud se vrátí, continuationToken znamená to, že prostřednictvím rozhraní API je k dispozici více výsledků. I když máme plány na zlepšení této logiky, v tuto chvíli je možné, že první výsledky X vrátí prázdné.

TF401444: Přihlaste se alespoň jednou jako {tenantId'tenantId\servicePrincipalObjectId'} ve webovém prohlížeči, abyste povolili přístup ke službě.

Pokud instanční objekt nebyl pozván do organizace, můžete narazit na následující chybu. Ujistěte se, že je instanční objekt přidaný do příslušné organizace a má všechna oprávnění potřebná pro přístup k požadovaným prostředkům.