Přístup k tajným kódům z online nasazení pomocí injektáže tajných kódů (Preview)

PLATÍ PRO:Rozšíření Azure CLI ml v2 (aktuální)Python SDK azure-ai-ml v2 (aktuální)

V tomto článku se naučíte používat injektáž tajných kódů s online koncovým bodem a nasazením pro přístup k tajným kódům z úložiště tajných kódů.

Naučíte se:

  • Nastavení identity uživatele a jeho oprávnění
  • Vytvořte připojení pracovního prostoru a/nebo trezory klíčů, které se mají použít jako úložiště tajemství.
  • Vytvoření koncového bodu a nasazení pomocí funkce injektáže tajných kódů

Důležité

Tato funkce je v současné době ve verzi Public Preview. Tato verze Preview je poskytována bez smlouvy o úrovni služeb a nedoporučujeme ji pro produkční úlohy. Některé funkce se nemusí podporovat nebo mohou mít omezené možnosti.

Další informace najdete v dodatečných podmínkách použití pro verze Preview v Microsoft Azure.

Požadavky

  • Pokud chcete používat Azure Machine Learning, musíte mít předplatné Azure. Pokud ještě nemáte předplatné Azure, vytvořte si napřed bezplatný účet. Vyzkoušejte si bezplatnou nebo placenou verzi služby Azure Machine Learning ještě dnes.

  • Nainstalujte a nakonfigurujte rozšíření Azure Machine Learning CLI (v2) nebo sadu Azure Machine Learning Python SDK (v2).

  • Skupina prostředků Azure, ve které vy (nebo instanční objekt, který používáte) musíte mít User Access Administrator a Contributor přístup. Takovou skupinu prostředků budete mít, pokud jste nakonfigurovali rozšíření Azure Machine Learning, jak je uvedeno dříve.

  • Pracovní prostor služby Azure Machine Learning. Pokud jste nakonfigurovali rozšíření Azure Machine Learning, jak jste uvedli dříve, budete mít pracovní prostor.

  • Jakýkoli vytrénovaný model strojového učení připravený k bodování a nasazení

Výběr tajného úložiště

Tajné kódy (například klíče rozhraní API) můžete ukládat pomocí následujících:

  • Připojení pracovního prostoru v rámci pracovního prostoru: Pokud používáte tento druh úložiště tajných kódů, můžete později udělit oprávnění identitě koncového bodu (v době vytvoření koncového bodu) ke čtení tajných kódů z připojení pracovního prostoru automaticky za předpokladu, že jsou splněny určité podmínky. Na kartě identit přiřazené systémem, v části Vytvoření koncového bodu, najdete další informace.
  • Trezory klíčů, které nejsou nutně součástí pracovního prostoru: Pokud používáte tento druh úložiště tajemství, identitě koncového bodu nebude automaticky uděleno oprávnění k čtení tajemství z trezorů klíčů. Proto pokud chcete použít službu spravovaného trezoru klíčů, jako je Microsoft Azure Key Vault jako úložiště tajných kódů, musíte později přiřadit správnou roli.

Použití připojení pracovního prostoru jako úložiště tajných kódů

Můžete vytvořit připojení do pracovního prostoru, která použijete při nasazení. Můžete například vytvořit připojení k Microsoft Azure OpenAI v modelech Microsoft Foundry pomocí připojení pracovních prostorů – Vytvoření rozhraní REST API.

Případně můžete vytvořit vlastní připojení pomocí nástroje Azure Machine Learning Studio (viz Postup vytvoření vlastního připojení pro tok výzvy) nebo Foundry (viz Postup vytvoření vlastního připojení na portálu Foundry).

  1. Vytvořte připojení Azure OpenAI:

    PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}?api-version=2023-08-01-preview
Authorization: Bearer {{token}}
Content-Type: application/json

{
    "properties": {
        "authType": "ApiKey",
        "category": "AzureOpenAI",
        "credentials": {
            "key": "<key>",
            "endpoint": "https://<name>.openai.azure.com/",
        },
        "expiryTime": null,
        "target": "https://<name>.openai.azure.com/",
        "isSharedToAll": false,
        "sharedUserList": [],
        "metadata": {
            "ApiType": "Azure"
        }
    }
}

  2. Alternativně můžete vytvořit vlastní připojení:

    PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}?api-version=2023-08-01-preview
Authorization: Bearer {{token}}
Content-Type: application/json

{
    "properties": {
        "authType": "CustomKeys",
        "category": "CustomKeys",
        "credentials": {
            "keys": {
                "OPENAI_API_KEY": "<key>",
                "SPEECH_API_KEY": "<key>"
            }
        },
        "expiryTime": null,
        "target": "_",
        "isSharedToAll": false,
        "sharedUserList": [],
        "metadata": {
            "OPENAI_API_BASE": "<oai endpoint>",
            "OPENAI_API_VERSION": "<oai version>",
            "OPENAI_API_TYPE": "azure",
            "SPEECH_REGION": "eastus",
        }
    }
}

  3. Ověřte, že identita uživatele může číst tajemství z připojení pracovního prostoru pomocí Workspace Connections - List Secrets REST API (preview).

    POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}/listsecrets?api-version=2023-08-01-preview
Authorization: Bearer {{token}}

Poznámka:

Předchozí fragmenty kódu používají token v Authorization hlavičce při volání rozhraní REST API. Token můžete získat spuštěním az account get-access-tokenpříkazu . Další informace o získání tokenu najdete v tématu Získání přístupového tokenu.

(Volitelné) Použití služby Azure Key Vault jako úložiště tajných kódů

Vytvořte trezor klíčů a nastavte tajný klíč pro použití v nasazení. Další informace o vytvoření trezoru klíčů najdete v tématu Nastavení a načtení tajného klíče ze služby Azure Key Vault pomocí Azure CLI. Navíc,

  1. Vytvoření služby Azure Key Vault:

    az keyvault create --name mykeyvault --resource-group myrg --location eastus

  2. Vytvoření tajného kódu:

    az keyvault secret set --vault-name mykeyvault --name secret1 --value <value>

    Tento příkaz vrátí verzi tajného klíče, kterou vytvoří. Můžete zkontrolovat id vlastnost odpovědi a získat verzi tajného kódu. Vrácená odpověď vypadá takto https://mykeyvault.vault.azure.net/secrets/<secret_name>/<secret_version>.

  3. Ověřte, že uživatelská identita může číst tajné údaje z Key Vault.

    az keyvault secret show --vault-name mykeyvault --name secret1 --version <secret_version>

Důležité

Pokud trezor klíčů používáte jako úložiště tajných kódů pro injektáž tajných kódů, musíte nakonfigurovat model oprávnění trezoru klíčů jako řízení přístupu na základě role v Azure (RBAC). Další informace najdete v tématu Azure RBAC vs. zásady přístupu ke službě Key Vault.

Volba identity uživatele

Zvolte identitu uživatele, kterou použijete k vytvoření online koncového bodu a online nasazení. Tato identita uživatele může být uživatelským účtem, instančním účtem nebo spravovanou identitou v Microsoft Entra ID. Pokud chcete nastavit identitu uživatele, postupujte podle kroků v tématu Nastavení ověřování pro prostředky a pracovní postupy služby Azure Machine Learning.

(Volitelné) Přiřazení role identitě uživatele

  • Pokud vaše uživatelská identita chce, aby identita přiřazená systémem koncového bodu (SAI) automaticky získala oprávnění ke čtení tajemství z připojení pracovního prostoru, musí mít role (nebo vyšší) v rámci pracovního prostoru.

    • Správce s Microsoft.Authorization/roleAssignments/write oprávněním může spustit příkaz rozhraní příkazového řádku pro přiřazení role identitě uživatele:

      az role assignment create --assignee <UserIdentityID> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

    Poznámka:

    Identita přiřazená systémem koncového bodu (SAI) nebude automaticky mít oprávnění ke čtení tajemství z úložišť klíčů. Proto nemusí být uživatelské identitě přiřazena role v Key Vault.

  • Pokud chcete pro koncový bod použít identitu přiřazenou uživatelem, nemusíte roli přiřazovat identitě uživatele. Místo toho, pokud máte v úmyslu použít funkci injektáže tajných kódů, musíte roli přiřadit uživatelskému rozhraní koncového bodu ručně.

    • Správce, který má Microsoft.Authorization/roleAssignments/write oprávnění, může spustit následující příkazy pro přiřazení role k identitě koncového bodu:

      "Pro připojení pracovního prostoru:"

      az role assignment create --assignee <EndpointIdentityID> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

      Pro úložiště klíčů:

      az role assignment create --assignee <EndpointIdentityID> --role "Key Vault Secrets User" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.KeyVault/vaults/<vaultName>

  • Ověřte, že identita (identita uživatele nebo identita koncového bodu) má přiřazenou roli, a to tak, že přejdete k prostředku na webu Azure Portal. Například v pracovním prostoru Azure Machine Learning nebo ve službě Key Vault:

    1. Vyberte kartu Řízení přístupu (IAM).
    2. Vyberte tlačítko Zkontrolovat přístup a vyhledejte identitu.
    3. Ověřte, že se na kartě Aktuální přiřazení rolí zobrazuje správná role.

Vytvoření koncového bodu

Návod

V tomto příkladu se pro zjednodušení používá ověřování založené na klíčích. V produkčních nasazeních microsoft doporučuje ověřováníaad_token založené na tokenech Microsoftu (Entra), které poskytuje rozšířené zabezpečení prostřednictvím řízení přístupu na základě identit. Další informace najdete v tématu Ověřování klientů pro online koncové body.

Pokud jako identitu koncového bodu používáte identitu přiřazenou systémem (SAI), určete, jestli chcete vynutit přístup k výchozím úložištím tajných kódů (konkrétně připojení pracovního prostoru v rámci pracovního prostoru) k identitě koncového bodu.

  1. Vytvořte soubor endpoint.yaml:

    $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key
properties:
    enforce_access_to_default_secret_stores: enabled  # default: disabled

  2. Vytvořte koncový bod pomocí endpoint.yaml souboru:

    az ml online-endpoint create -f endpoint.yaml

Pokud v definici koncového bodu nezadáte vlastnost identity, koncový bod použije ve výchozím nastavení SAI.

Pokud jsou splněny následující podmínky, identitě koncového bodu bude automaticky udělena role Azure Machine Learning Workspace Connection Secrets Reader (nebo vyšší) v rámci pracovního prostoru.

  • Identita uživatele, která vytvoří koncový bod, má oprávnění ke čtení tajných kódů z připojení pracovního prostoru (Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action).
  • Koncový bod používá SAI.
  • Koncový bod je definován příznakem pro vynucení přístupu k výchozím úložištům tajných informací, jako jsou připojení v rámci aktuálního pracovního prostoru, při jeho vytváření.

Identitě koncového bodu se automaticky nepřidělí role pro čtení tajných kódů ze služby Key Vault. Pokud chcete použít Key Vault jako úložiště tajných kódů, musíte ručně přiřadit správnou roli, jako je Key Vault Secrets User, k identitě koncového bodu v rámci služby Key Vault. Další informace o rolích najdete v tématu Vestavěné role Azure pro operace roviny dat služby Key Vault.

Vytvořte nasazení

  1. Vytvořte bodovací skript nebo soubor Dockerfile a související skripty, aby nasazení mohlo využívat tajemství prostřednictvím proměnných prostředí.

    • Není nutné volat rozhraní API pro načítání tajných kódů pro připojení pracovního prostoru nebo trezory klíčů. Proměnné prostředí se naplní tajnými kódy, když se spustí kontejner uživatele v nasazení.

    • Hodnota, která se vloží do proměnné prostředí, může být jedním ze tří typů:

      • Celá odpověď rozhraní API pro výčet tajemství (náhled) Budete muset porozumět struktuře odpovědí rozhraní API, analyzovat ji a používat ji v kontejneru uživatele.
      • Individuální tajný klíč nebo metadata z připojení pracovního prostoru. Můžete ho použít i bez pochopení struktury odpovědi rozhraní API pro připojení pracovního prostoru.
      • Individuální verze tajného kódu ze služby Key Vault. Můžete ho použít, aniž byste porozuměli struktuře odpovědí rozhraní API služby Key Vault.

  2. Spusťte vytvoření nasazení pomocí hodnoticího skriptu (pokud používáte vlastní model) nebo souboru Dockerfile (pokud použijete přístup BYOC k nasazení). Zadejte proměnné prostředí, které uživatel očekává v rámci kontejneru uživatele.

    Pokud hodnoty mapované na proměnné prostředí dodržují určité vzory, použije se identita koncového bodu k provádění načítání a vložení tajných dat.

    Vzor Chování
    ${{azureml://connections/<connection_name>}} Celá odpověď rozhraní API pro seznam tajemství (náhled) se vloží do proměnné prostředí.
    ${{azureml://connections/<connection_name>/credentials/<credential_name>}} Hodnota autentizačních údajů je vložena do proměnné prostředí.
    ${{azureml://connections/<connection_name>/metadata/<metadata_name>}} Hodnota metadat je zasunuta do proměnné prostředí.
    ${{azureml://connections/<connection_name>/target}} Hodnota cíle (je-li to možné) se umístí do proměnné prostředí.
    ${{keyvault:https://<keyvault_name>.vault.azure.net/secrets/<secret_name>/<secret_version>}} Hodnota verze tajného kódu se vloží do proměnné prostředí.

    Příklad:

    1. Vytvořit deployment.yaml:

      $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
#…
environment_variables:
    AOAI_CONNECTION: ${{azureml://connections/aoai_connection}}
    LANGCHAIN_CONNECTION: ${{azureml://connections/multi_connection_langchain}}

    OPENAI_KEY: ${{azureml://connections/multi_connection_langchain/credentials/OPENAI_API_KEY}}
    OPENAI_VERSION: ${{azureml://connections/multi_connection_langchain/metadata/OPENAI_API_VERSION}}

    USER_SECRET_KV1_KEY: ${{keyvault:https://mykeyvault.vault.azure.net/secrets/secret1/secretversion1}}

    2. Vytvořte nasazení:

      az ml online-deployment create -f deployment.yaml

enforce_access_to_default_secret_stores Pokud byl příznak nastavený pro koncový bod, oprávnění identity uživatele ke čtení tajných kódů z připojení pracovního prostoru se zkontroluje jak při vytváření koncového bodu, tak při vytváření nasazení. Pokud identita uživatele nemá oprávnění, vytvoření se nezdaří.

Pokud se při vytváření nasazení namapuje nějaká proměnná prostředí na hodnotu, která odpovídá vzorům v předchozí tabulce, provede se načtení a injektování tajných klíčů použitím identity koncového bodu (buď SAI, nebo UAI). Pokud identita koncového bodu nemá oprávnění ke čtení tajemství z určených úložišť tajemství (prostorová připojení nebo trezory klíčů), nasazení se nezdaří. Pokud zadaný odkaz na tajný kód v úložištích tajných kódů neexistuje, vytvoření nasazení selže.

Další informace o chybách, ke kterým může dojít při nasazování online koncových bodů služby Azure Machine Learning, najdete v tématu Chyby injektáže tajných kódů.

Přijmout tajemství

Tajemství můžete využívat načtením z proměnných prostředí v uživatelském kontejneru spuštěném jako součást vašich nasazení.

Související obsah

  • Last updated on