Toegang tot geheimen van onlineimplementatie met behulp van geheime injectie (preview)

  • Artikel

VAN TOEPASSING OP:Azure CLI ml extension v2 (current)Python SDK azure-ai-ml v2 (current)

In dit artikel leert u hoe u geheime injectie gebruikt met een online-eindpunt en implementatie om toegang te krijgen tot geheimen uit een geheim archief.

U leert het volgende:

  • Uw gebruikersidentiteit en de bijbehorende machtigingen instellen
  • Werkruimteverbindingen en/of sleutelkluizen maken voor gebruik als geheime opslag
  • Het eindpunt en de implementatie maken met behulp van de geheime injectiefunctie

Belangrijk

Deze functie is momenteel beschikbaar als openbare preview-versie. Deze preview-versie wordt geleverd zonder een service level agreement en we raden deze niet aan voor productieworkloads. Misschien worden bepaalde functies niet ondersteund of zijn de mogelijkheden ervan beperkt.

Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure-previews voor meer informatie.

Vereisten

  • Als u Azure Machine Learning wilt gebruiken, moet u een Azure-abonnement hebben. Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint. Probeer vandaag nog de gratis of betaalde versie van Azure Machine Learning.

  • Installeer en configureer de Azure Machine Learning CLI-extensie (v2) of de Azure Machine Learning Python SDK (v2).

  • Een Azure-resourcegroep waarin u (of de service-principal die u gebruikt) toegang moet hebben en Contributor er toegang toe moet hebbenUser Access Administrator. U hebt zo'n resourcegroep als u uw Azure Machine Learning-extensie hebt geconfigureerd zoals eerder vermeld.

  • Een Azure Machine Learning-werkruimte. U hebt een werkruimte als u uw Azure Machine Learning-extensie hebt geconfigureerd zoals eerder is aangegeven.

  • Elk getraind machine learning-model dat gereed is voor scoren en implementatie.

Een geheim archief kiezen

U kunt ervoor kiezen om uw geheimen (zoals API-sleutels) op te slaan met behulp van:

  • Werkruimteverbindingen onder de werkruimte: Als u dit type geheimarchief gebruikt, kunt u later toestemming verlenen aan de eindpuntidentiteit (tijdens het maken van eindpunten) om geheimen automatisch te lezen van werkruimteverbindingen, mits aan bepaalde voorwaarden wordt voldaan. Zie het tabblad Door het systeem toegewezen identiteit in de sectie Een eindpunt maken voor meer informatie.
  • Sleutelkluizen die niet noodzakelijkerwijs onder de werkruimte staan: als u dit type geheimarchief gebruikt, wordt de eindpuntidentiteit niet automatisch gemachtigd om geheimen uit de sleutelkluizen te lezen. Als u daarom een beheerde sleutelkluisservice zoals Microsoft Azure Key Vault wilt gebruiken als geheimarchief, moet u later een juiste rol toewijzen.

Werkruimteverbinding gebruiken als een geheim archief

U kunt werkruimteverbindingen maken die u in uw implementatie kunt gebruiken. U kunt bijvoorbeeld een verbinding maken met de Microsoft Azure OpenAI-service met behulp van werkruimte-Verbinding maken ions - REST API maken.

U kunt ook een aangepaste verbinding maken met behulp van Azure Machine Learning-studio (zie Een aangepaste verbinding maken voor promptstroom) of Azure AI Studio (zie Een aangepaste verbinding maken in AI Studio).

  1. Een Azure OpenAI-verbinding maken:

    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. U kunt ook een aangepaste verbinding maken:

    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. Controleer of de gebruikersidentiteit de geheimen uit de werkruimteverbinding kan lezen met behulp van werkruimte-Verbinding maken ions - 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}}

Notitie

De vorige codefragmenten gebruiken een token in de Authorization header bij het maken van REST API-aanroepen. U kunt het token ophalen door uit te voeren az account get-access-token. Zie Een toegangstoken ophalen voor meer informatie over het ophalen van een token.

(Optioneel) Azure Key Vault gebruiken als een geheim archief

Maak de sleutelkluis en stel een geheim in voor gebruik in uw implementatie. Zie Een geheim instellen en ophalen uit Azure Key Vault met behulp van Azure CLI voor meer informatie over het maken van de sleutelkluis. Ook

  1. Een Azure Key Vault maken:

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

  2. Een geheim maken:

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

    Met deze opdracht wordt de geheime versie geretourneerd die wordt gemaakt. U kunt de id eigenschap van het antwoord controleren om de geheime versie op te halen. Het geretourneerde antwoord ziet er als volgt https://mykeyvault.vault.azure.net/secrets/<secret_name>/<secret_version>uit.

  3. Controleer of de gebruikersidentiteit het geheim uit de sleutelkluis kan lezen:

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

Belangrijk

Als u de sleutelkluis gebruikt als een geheim archief voor geheime injectie, moet u het machtigingsmodel van de sleutelkluis configureren als op rollen gebaseerd toegangsbeheer van Azure (RBAC). Zie Azure RBAC versus toegangsbeleid voor Key Vault voor meer informatie.

Een gebruikersidentiteit kiezen

Kies de gebruikersidentiteit die u gaat gebruiken om het online-eindpunt en de onlineimplementatie te maken. Deze gebruikersidentiteit kan een gebruikersaccount, een service-principal-account of een beheerde identiteit in Microsoft Entra-id zijn. Volg de stappen in Verificatie instellen voor Azure Machine Learning-resources en -werkstromen om de gebruikersidentiteit in te stellen.

(Optioneel) Een rol toewijzen aan de gebruikersidentiteit

  • Als uw gebruikersidentiteit wil dat de door het eindpunt toegewezen identiteit (SAI) automatisch wordt gemachtigd om geheimen van werkruimteverbindingen te lezen, moet de gebruikersidentiteit de Azure Machine Learning Workspace Connection Secrets Reader rol (of hoger) hebben voor het bereik van de werkruimte.

    • Een beheerder met de Microsoft.Authorization/roleAssignments/write machtiging kan een CLI-opdracht uitvoeren om de rol toe te wijzen aan de gebruikersidentiteit:

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

    Notitie

    Aan de door het eindpunt toegewezen identiteit (SAI) wordt niet automatisch toestemming verleend voor het lezen van geheimen uit sleutelkluizen. Daarom hoeft de gebruikersidentiteit geen rol voor de Sleutelkluis toe te wijzen.

  • Als u een door de gebruiker toegewezen identiteit (UAI) voor het eindpunt wilt gebruiken, hoeft u de rol niet toe te wijzen aan uw gebruikersidentiteit. Als u de functie voor geheime injectie wilt gebruiken, moet u de rol handmatig toewijzen aan de UAI van het eindpunt.

    • Een beheerder met de Microsoft.Authorization/roleAssignments/write machtiging kan de volgende opdrachten uitvoeren om de rol toe te wijzen aan de eindpuntidentiteit:

      Voor werkruimteverbindingen:

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

      Voor sleutelkluizen:

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

  • Controleer of aan een identiteit (een gebruikersidentiteit of eindpuntidentiteit) de rol is toegewezen door naar de resource in Azure Portal te gaan. Bijvoorbeeld in de Azure Machine Learning-werkruimte of de Key Vault:

    1. Selecteer het tabblad Toegangsbeheer (IAM).
    2. Selecteer de knop Toegang controleren en zoek de identiteit.
    3. Controleer of de juiste rol wordt weergegeven op het tabblad Huidige roltoewijzingen .

Een eindpunt maken

Als u een door het systeem toegewezen identiteit (SAI) als eindpuntidentiteit gebruikt, geeft u op of u toegang tot standaardgeheimarchieven (namelijk werkruimteverbindingen onder de werkruimte) wilt afdwingen naar de eindpuntidentiteit.

  1. Maak een endpoint.yaml-bestand:

    $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. Maak het eindpunt met behulp van het endpoint.yaml bestand:

    az ml online-endpoint create -f endpoint.yaml

Als u de eigenschap in de identity eindpuntdefinitie niet opgeeft, gebruikt het eindpunt standaard een SAI.

Als aan de volgende voorwaarden wordt voldaan, krijgt de eindpuntidentiteit automatisch de Azure Machine Learning Workspace Connection Secrets Reader rol (of hoger) voor het bereik van de werkruimte:

  • De gebruikersidentiteit waarmee het eindpunt wordt gemaakt, heeft de machtiging om geheimen van werkruimteverbindingen (Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action) te lezen.
  • Het eindpunt maakt gebruik van een SAI.
  • Het eindpunt wordt gedefinieerd met een vlag voor het afdwingen van toegang tot standaardgeheimarchieven (werkruimteverbindingen onder de huidige werkruimte) bij het maken van het eindpunt.

De eindpuntidentiteit krijgt niet automatisch een rol om geheimen uit de Key Vault te lezen. Als u key vault wilt gebruiken als een geheim archief, moet u handmatig een juiste rol toewijzen, zoals Key Vault Secrets User de eindpuntidentiteit op het bereik van de Key Vault. Zie ingebouwde Azure-rollen voor Key Vault-gegevensvlakbewerkingen voor meer informatie over rollen.

Een implementatie maken

  1. Ontwerp een scorescript of Dockerfile en de gerelateerde scripts, zodat de implementatie de geheimen kan gebruiken via omgevingsvariabelen.

    • U hoeft de API's voor het ophalen van geheimen niet aan te roepen voor de werkruimteverbindingen of sleutelkluizen. De omgevingsvariabelen worden gevuld met de geheimen wanneer de gebruikerscontainer in de implementatie wordt gestart.

    • De waarde die wordt geïnjecteerd in een omgevingsvariabele kan een van de drie typen zijn:

      • Het volledige antwoord van de List Secrets API (preview). U moet de API-antwoordstructuur begrijpen, deze parseren en gebruiken in uw gebruikerscontainer.
      • Afzonderlijke geheimen of metagegevens van de werkruimteverbinding. U kunt deze gebruiken zonder inzicht te krijgen in de antwoordstructuur van de api voor de werkruimteverbinding.
      • Afzonderlijke geheime versie van Key Vault. U kunt deze gebruiken zonder inzicht te krijgen in de antwoordstructuur van de Key Vault-API.

  2. Start het maken van de implementatie met behulp van het scorescript (als u een aangepast model gebruikt) of een Dockerfile (als u de BYOC-benadering voor implementatie gebruikt). Geef omgevingsvariabelen op die de gebruiker verwacht in de gebruikerscontainer.

    Als de waarden die zijn toegewezen aan de omgevingsvariabelen bepaalde patronen volgen, wordt de eindpuntidentiteit gebruikt om geheim ophalen en injectie uit te voeren.

    Patroon Gedrag
    ${{azureml://connections/<connection_name>}} Het volledige antwoord list secrets-API (preview) wordt opgenomen in de omgevingsvariabele.
    ${{azureml://connections/<connection_name>/credentials/<credential_name>}} De waarde van de referentie wordt geïnjecteerd in de omgevingsvariabele.
    ${{azureml://connections/<connection_name>/metadata/<metadata_name>}} De waarde van de metagegevens wordt geïnjecteerd in de omgevingsvariabele.
    ${{azureml://connections/<connection_name>/target}} De waarde van het doel (indien van toepassing) wordt geïnjecteerd in de omgevingsvariabele.
    ${{keyvault:https://<keyvault_name>.vault.azure.net/secrets/<secret_name>/<secret_version>}} De waarde van de geheime versie wordt geïnjecteerd in de omgevingsvariabele.

    Voorbeeld:

    1. Maken 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. De implementatie maken:

      az ml online-deployment create -f deployment.yaml

Als de enforce_access_to_default_secret_stores vlag is ingesteld voor het eindpunt, wordt de machtiging van de gebruikersidentiteit voor het lezen van geheimen van werkruimteverbindingen gecontroleerd tijdens het maken van eindpunten en het maken van de implementatie. Als de gebruikersidentiteit niet over de machtiging beschikt, mislukt het maken.

Als tijdens het maken van de implementatie een omgevingsvariabele is toegewezen aan een waarde die de patronen in de vorige tabel volgt, worden geheime ophaal- en injecties uitgevoerd met de eindpuntidentiteit (een SAI of een UAI). Als de eindpuntidentiteit niet gemachtigd is om geheimen te lezen uit aangewezen geheime archieven (werkruimteverbindingen of sleutelkluizen), mislukt het maken van de implementatie. Als de opgegeven geheime verwijzing niet bestaat in de geheime archieven, mislukt het maken van de implementatie.

Zie Fouten bij geheiminjectie voor meer informatie over fouten die kunnen optreden tijdens de implementatie van Online-eindpunten van Azure Machine Learning.

De geheimen gebruiken

U kunt de geheimen gebruiken door ze op te halen uit de omgevingsvariabelen in de gebruikerscontainer die wordt uitgevoerd in uw implementaties.

Gerelateerde inhoud