Hizmet sorumlularını kullanarak yerel geliştirme sırasında Azure hizmetlerinde JavaScript uygulamalarının kimliğini doğrulama

Yerel geliştirme sırasında uygulamaların çeşitli Azure hizmetlerine erişmek için Azure'da kimlik doğrulaması yapmaları gerekir. Yerel kimlik doğrulamasına yönelik iki yaygın yaklaşım, geliştirici hesabı veya hizmet sorumlusu kullanmaktır. Bu makalede, uygulama hizmet sorumlusu nasıl kullanılacağı açıklanmaktadır. Aşağıdaki bölümlerde şunları öğrenirsiniz:

• Hizmet sorumlusu oluşturmak için bir uygulamayı Microsoft Entra'ya kaydetme
• İzinleri verimli bir şekilde yönetmek için Microsoft Entra gruplarını kullanma
• Kapsam izinlerine roller atama
• Uygulama kodunuzdan hizmet ilkesi kullanarak kimlik doğrulaması yapma

Ayrılmış uygulama hizmet sorumlularını kullanarak Azure kaynaklarına erişirken en az ayrıcalık ilkesine bağlı kalabilirsiniz. Geliştirme sırasında uygulamanın belirli gereksinimleriyle ilgili izinleri sınırlayarak diğer uygulama veya hizmetlere yönelik Azure kaynaklarına yanlışlıkla erişimi önleyin. Bu yaklaşım, uygulama geliştirme ortamında aşırı ayrıcalıklı olmadığından emin olarak üretime taşındığında karşılaşılan sorunları önlemeye de yardımcı olur.

Uygulamayı Azure'a kaydettiğinizde bir uygulama hizmet sorumlusu oluşturursunuz. Yerel geliştirme için:

• Her geliştiricinin kendi uygulama hizmet sorumlusuna sahip olması ve kimlik bilgilerini paylaşması gerekmemesi için uygulama üzerinde çalışan her geliştirici için ayrı bir uygulama kaydı oluşturun.
• Uygulamanın izinlerini yalnızca gerekli olanlarla sınırlamak için her uygulama için ayrı bir uygulama kaydı oluşturun.

Yerel geliştirme sırasında, uygulama hizmeti sorumlusunun kimliğiyle ortam değişkenlerini ayarlayın. Azure Kimlik kitaplığı, gerekli Azure kaynaklarında uygulamanın kimliğini doğrulamak için bu ortam değişkenlerini okur.

Uygulamayı Azure'a kaydetme

Uygulama hizmet sorumlusu nesneleri, Azure portalı ya da Azure CLI kullanılarak Azure'da bir uygulama kaydı aracılığıyla oluşturulur.

Azure portalı

1. Azure portalında arama çubuğunu kullanarak Uygulama kayıtları sayfasına gidin.

2. Uygulama kayıtları sayfasında + Yeni kayıt'ı seçin.

3. Uygulamayı kaydetme sayfasında:

   • Adı alanı için uygulama adını ve hedef ortamı içeren açıklayıcı bir değer girin.
   • Desteklenen hesap türleri için yalnızca bu kuruluş dizinindeki hesaplar (Yalnızca Microsoft Müşteri Liderliğinde - Tek kiracı) veya gereksinimlerinize en uygun seçeneğiseçin.

4. Uygulamanızı kaydetmek ve hizmet sorumlusunu oluşturmak için Kaydet seçin.

   

5. Uygulamanızın Uygulama kaydı sayfasında Uygulama (istemci) kimliği ve Dizin (kiracı) kimliği kopyalayın ve bunları uygulama kodu yapılandırmalarınızda daha sonra kullanmak üzere geçici bir konuma yapıştırın.

6. Uygulamanızın kimlik bilgilerini ayarlamak için Sertifika veya gizli dizi ekle'yi seçin.

7. Sertifikalar ve gizli anahtarlar sayfasında + Yeni istemci gizli anahtar'ı seçin.

8. İstemci sırrı ekle panosunda açılan panelde:

   • Açıklamaiçin Geçerli değerini girin.
   • Süresi Doluyor değeri için varsayılan önerilen 180 gün değerini bırakın.
   • Gizli diziyi eklemek için Ekle'yi seçin.

9. Sertifikalar & gizli anahtarları sayfasında, istemci gizli anahtarının Değer özelliğini gelecekte kullanmak üzere kopyalayın.

   Uyarı

   İstemci gizli anahtarı değeri, uygulama kaydı oluşturulduktan sonra yalnızca bir kez görüntülenir. Bu istemci sırrını geçersiz kılmadan daha fazla istemci sırrı ekleyebilirsiniz; ancak bu değeri yeniden görüntüleyebilmenin bir yolu yoktur.

Azure CLI

Azure CLI komutları Azure Cloud Shell'de veya Azure CLI yüklü bir iş istasyonunda çalıştırılabilir.

1. Uygulama için yeni bir uygulama kaydı ve hizmet sorumlusu oluşturmak için az ad sp create-for-rbac komutunu kullanın.

   az ad sp create-for-rbac --name <service-principal-name>
   

   Bu komutun çıktısı aşağıdaki JSON'a benzer:

   {
     "appId": "00000000-0000-0000-0000-000000000000",
     "displayName": "<service-principal-name>",
     "password": "abcdefghijklmnopqrstuvwxyz",
     "tenant": "11111111-1111-1111-1111-111111111111"
   }
   

2. Bu değerlere gelecekteki bir adımda ihtiyaç duyacağınız için bu çıkışı metin düzenleyicisindeki geçici bir dosyaya kopyalayın.

   Uyarı

   İstemci gizli anahtarı değeri, uygulama kaydı oluşturulduktan sonra yalnızca bir kez görüntülenir. Bu istemci sırrını geçersiz kılmadan daha fazla istemci sırrı ekleyebilirsiniz; ancak bu değeri yeniden görüntüleyebilmenin bir yolu yoktur.

Yerel geliştirme için Microsoft Entra grubu oluşturma

Rolleri tek tek hizmet sorumlusu nesnelerine atamak yerine yerel geliştirmede uygulamanın ihtiyaç duyduğu rolleri (izinleri) kapsüllemek için bir Microsoft Entra grubu oluşturun. Bu yaklaşım aşağıdaki avantajları sunar:

• Her geliştirici, grup düzeyinde aynı rollere sahiptir.
• Uygulama için yeni bir rol gerekiyorsa, yalnızca uygulamanın grubuna eklenmesi gerekir.
• Ekibe yeni bir geliştirici katılırsa, geliştirici için yeni bir uygulama hizmet sorumlusu oluşturulur ve gruba eklenir ve geliştiricinin uygulama üzerinde çalışmak için doğru izinlere sahip olduğundan emin olun.

Azure portalı

1. Azure portalında Microsoft Entra Id genel bakış sayfasına gidin.

2. Sol taraftaki menüden Tüm gruplar'ı seçin.

3. Gruplar sayfasında Yeni grup'a tıklayın.

4. Yeni grup sayfasında aşağıdaki form alanlarını doldurun:

   • Grup türü: güvenlikseçin.
   • Grup adı: Uygulama veya ortam adına başvuru içeren grup için bir ad girin.
   • Grup açıklaması: Grubun amacını açıklayan bir açıklama girin.

   

5. Gruba üye eklemek için Üyeler'in altında Üye seçilmedi bağlantısını seçin.

6. Açılan açılır panelde, daha önce oluşturduğunuz hizmet sorumlusunu arayın ve filtrelenen sonuçlardan seçin. Seçiminizi onaylamak için panelin altındaki Seç düğmesini seçin.

7. Grubu oluşturmak ve Tüm gruplar sayfasına dönmek için Yeni grup sayfasının alt kısmındaki Oluştur'u seçin. Yeni grubu listede görmüyorsanız, bir dakika bekleyin ve sayfayı yenileyin.

Azure CLI

1. Microsoft Entra ID'de grup oluşturmak için az ad group create komutunu kullanın.

   az ad group create \
       --display-name <group-name> \
       --mail-nickname <group-mail-nickname> \
       --description <group-description>
   

   --display-name ve --mail-nickname parametreleri zorunludur. Gruba verilen ad, grubun amacını belirtmek için uygulamanın adına ve ortamına dayalı olmalıdır.

2. Gruba üye eklemek için, uygulama hizmet sorumlusunun uygulama kimliğinden farklı olan nesne kimliğine ihtiyacınız vardır. Kullanılabilir hizmet sorumlularını listelemek için az ad sp list komutunu kullanın:

   az ad sp list \
       --filter "startswith(displayName, '<group-name>')" \
       --query "[].{objectId:id, displayName:displayName}"
   

   --filter parametresi OData stili filtreleri kabul eder ve gösterildiği gibi listeyi filtrelemek için kullanılabilir. --query parametresi, çıkışı yalnızca ilgilendiğiniz sütunlara sınırlar.

3. az ad group member add komutunu kullanarak gruba üye ekleyin.

   az ad group member add \
       --group <group-name> \
       --member-id <object-id>
   

Gruba rol atama

Ardından, uygulamanızın hangi kaynaklar üzerinde hangi rollere (izinlere) ihtiyacı olduğunu belirleyin ve bu rolleri oluşturduğunuz Microsoft Entra grubuna atayın. Gruplara kaynak, kaynak grubu veya abonelik kapsamında bir rol atanabilir. Bu örnekte, çoğu uygulama tüm Azure kaynaklarını tek bir kaynak grubunda gruplandırdığından kaynak grubu kapsamında rollerin nasıl atandığı gösterilmektedir.

Azure portalı

1. Azure portalında, uygulamanızı içeren kaynak grubunun Genel Bakış sayfasına gidin.

2. Sol gezinti bölmesinden Erişim denetimi (IAM) seçin.

3. Erişim denetimi (IAM) sayfasında + Ekle'yi ve ardından açılan menüden Rol ataması ekle'yi seçin. Rol ataması ekle sayfasında rolleri yapılandırmak ve atamak için birkaç sekme bulunur.

4. Rol sekmesinde, atamak istediğiniz rolü bulmak için arama kutusunu kullanın. Rolü seçin ve ardından İleri'yi seçin.

5. Üyeler sekmesinde:

   • Değere erişim ata için Kullanıcı, grup veya hizmet sorumlusu öğesini seçin.
   • Üyeler değeri için + Üyeleri seç'i seçerek Üyeleri seçin açılır penceresini açın.
   • Daha önce oluşturduğunuz Microsoft Entra grubunu arayın ve filtrelenen sonuçlardan seçin. Grubu seçmek ve açılır menü panelini kapatmak için Seç'i seçin.
   • Gözden Geçir ve Ata'yı, Üyeler sekmesinin alt kısmında seçin.

   

6. Gözden geçir ve ata sekmesinde, sayfanın alt kısmında Gözden geçir ve ata seçeneğini seçin.

Azure CLI

1. Bir Microsoft Entra grubu veya hizmet sorumlusuna atanabilecek rollerin adlarını almak için az role definition list komutunu kullanın.

   az role definition list \
       --query "sort_by([].{roleName:roleName, description:description}, &roleName)" \
       --output table
   

2. Oluşturduğunuz Microsoft Entra grubuna rol atamak için az role assignment create komutunu kullanın:

   az role assignment create \
       --assignee "<group-object-Id>" \
       --role "<role-name>" \
       --resource-group "<resource-group-name>"
   

   Azure CLI kullanarak kaynak veya abonelik düzeyinde izin atama hakkında bilgi için bkz. Azure CLI kullanarak Azure rolleri atama.

Uygulama ortamı değişkenlerini ayarlama

Çalışma zamanında, Azure Identity kitaplığındakiDefaultAzureCredential, EnvironmentCredentialve ClientSecretCredentialgibi bazı kimlik bilgileri, ortam değişkenlerinde kurala göre hizmet sorumlusu bilgilerini arar. Araçlarınıza ve ortamınıza bağlı olarak JavaScript ile çalışırken ortam değişkenlerini yapılandırmanın birden çok yolu vardır.

Seçtiğiniz yaklaşımdan bağımsız olarak, hizmet sorumlusu için aşağıdaki ortam değişkenlerini yapılandırın:

• AZURE_CLIENT_ID: Azure'da kayıtlı uygulamayı tanımlamak için kullanılır.
• AZURE_TENANT_ID: Microsoft Entra kiracısının kimliği.
• AZURE_CLIENT_SECRET: Uygulama için oluşturulan gizli kimlik bilgisi.

Visual Studio Code

Visual Studio Code'da ortam değişkenleri projenizin launch.json dosyasında ayarlanabilir. Bu değerler uygulama başlatıldığında otomatik olarak çekilir. Ancak bu yapılandırmalar dağıtım sırasında uygulamanızla birlikte hareket etmediğinden, hedef barındırma ortamınızda ortam değişkenleri ayarlamanız gerekir.

"configurations": [
{
    "env": {
        "NODE_ENV": "development",
        "AZURE_CLIENT_ID": "<your-client-id>",
        "AZURE_TENANT_ID":"<your-tenant-id>",
        "AZURE_CLIENT_SECRET": "<your-client-secret>"
    }
}

Windows

Windows için ortam değişkenlerini komut satırından ayarlayabilirsiniz. Ancak, değerler o işletim sisteminde çalışan tüm uygulamalar tarafından erişilebilir ve çakışmalara neden olabilir, bu nedenle bu yaklaşımda dikkatli olun. Ortam değişkenleri kullanıcı veya sistem düzeyinde ayarlanabilir.

# Set user environment variables
setx NODE_ENV "development"
setx AZURE_CLIENT_ID "<your-client-id>"
setx AZURE_TENANT_ID "<your-tenant-id>"
setx AZURE_CLIENT_SECRET "<your-client-secret>"

# Set system environment variables - requires running as admin
setx NODE_ENV "development" /m
setx AZURE_CLIENT_ID "<your-client-id>" /m
setx AZURE_TENANT_ID "<your-tenant-id>" /m
setx AZURE_CLIENT_SECRET "<your-client-secret>" /m

PowerShell, ortam değişkenlerini kullanıcı veya sistem düzeyinde ayarlamak için de kullanılabilir:

# Set user environment variables
[Environment]::SetEnvironmentVariable("NODE_ENV", "development", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "<your-client-id>", "User")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "<your-tenant-id>", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "<your-client-secret>", "User")

# Set system environment variables - requires running as admin
[Environment]::SetEnvironmentVariable("NODE_ENV", "development", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "<your-client-id>", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "<your-tenant-id>", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "<your-client-secret>", "Machine")

.env dosyası

Yerel geliştirme için bir .env dosya kullanabilirsiniz. Node.js 20.6.0 ve sonrası, --env-file bayrağı kullanılarak bir .env dosyasından ortam değişkenlerini otomatik olarak yüklemeyi destekler.

1. Proje kökünde bir .env dosya oluşturun:

   AZURE_CLIENT_ID=<your-client-id>
   AZURE_TENANT_ID=<your-tenant-id>
   AZURE_CLIENT_SECRET=<your-client-secret>
   

2. Uygulamanızı şu bayrakla --env-file çalıştırın:

   node --env-file=.env app.js
   

Önceki Node.js sürümler için dotenv npm paketini kullanabilirsiniz:

1. dotenv Paketi yükleyin:

   npm install dotenv
   

2. Uygulamanıza ortam değişkenlerini yükleyin:

   import 'dotenv/config';
   

Dikkat

Hiçbir zaman kaynak denetimine dosyaları veya istemci sırlarını .env işlemeyin. Dosyanıza .env ekleyin.gitignore.

Uygulamanızdan Azure hizmetlerinde kimlik doğrulaması

Azure Kimlik kitaplığı, farklı senaryoları ve Microsoft Entra kimlik doğrulama akışlarını TokenCredential desteklemeye uyarlanmış uygulamaları gibi çeşitli kimlik bilgileri sağlar. İlerideki adımlarda, kullanıcı hesaplarıyla yerel olarak çalışırken DefaultAzureCredential nasıl kullanılacağı gösterilmektedir.

Kodu uygulama

DefaultAzureCredential, Microsoft Entra ID'de kimlik doğrulaması yapmak için özenle hazırlanmış ve sıralı bir mekanizma dizisidir. Her kimlik doğrulama mekanizması TokenCredential sınıfından türetilen bir sınıftır ve kimlik bilgisi olarak bilinir. Çalışma zamanında, DefaultAzureCredential ilk kimlik bilgisini kullanarak kimlik doğrulamayı dener. Bu kimlik bilgisi bir erişim belirteci alamazsa, bir erişim belirteci başarıyla alınana kadar dizideki bir sonraki kimlik bilgisi denenir ve bu şekilde devam edilir. Bu şekilde, uygulamanız ortama özgü kod yazmadan farklı ortamlarda farklı kimlik bilgilerini kullanabilir.

Kullanmak için DefaultAzureCredential, @azure/kimlik paketlerini uygulamanıza ekleyin. Seçtiğiniz bir terminalde uygulama projesi dizinine gidin ve aşağıdaki komutu çalıştırın:

npm install @azure/identity

Azure hizmetlerine çeşitli Azure SDK istemci kitaplıklarından özel istemci sınıfları kullanılarak erişilir. Bu sınıflar ve kendi özel hizmetleriniz, uygulamanız genelinde erişilebilmeleri için kayıtlı olmalıdır. Bir istemci sınıfı ve DefaultAzureCredential oluşturmak için aşağıdaki programatik adımları tamamlayın.

1. @azure/identity paketini içeri aktarın.
2. Azure hizmet istemcisini oluşturun ve ona DefaultAzureCredential yeni bir örnek aktarın.

import { DefaultAzureCredential } from "@azure/identity";
import { SomeAzureServiceClient } from "@azure/arm-some-service";

const client = new SomeAzureServiceClient(new DefaultAzureCredential());