Batch endpoints support Azure Active Directory authentication, or aad_token. That means that in order to invoke a batch endpoint, the user must present a valid Azure Active Directory authentication token to the batch endpoint URI. Authorization is enforced at the endpoint level. The following article explains how to correctly interact with batch endpoints and the security requirements for it.
- This example assumes that you have a model correctly deployed as a batch endpoint. Particularly, we are using the heart condition classifier created in the tutorial Using MLflow models in batch deployments.
To invoke a batch endpoint, the user must present a valid Azure Active Directory token representing a security principal. This principal can be a user principal or a service principal. In any case, once an endpoint is invoked, a batch deployment job is created under the identity associated with the token. The identity needs the following permissions in order to successfully create a job:
[!div class="checklist"]
- Read batch endpoints/deployments.
- Create jobs in batch inference endpoints/deployment.
- Create experiments/runs.
- Read and write from/to data stores.
- Lists datastore secrets.
You can either use one of the built-in security roles or create a new one. In any case, the identity used to invoke the endpoints requires to be granted the permissions explicitly. See Steps to assign an Azure role for instructions to assign them.
Important
The identity used for invoking a batch endpoint may not be used to read the underlying data depending on how the data store is configured. Please see Security considerations when reading data for more details.
The following examples show different ways to start batch deployment jobs using different types of credentials:
Important
When working on a private link-enabled workspaces, batch endpoints can't be invoked from the UI in Azure ML studio. Please use the Azure ML CLI v2 instead for job creation.
In this case, we want to execute a batch endpoint using the identity of the user currently logged in. Follow these steps:
Note
When working on Azure ML studio, batch endpoints/deployments are always executed using the identity of the current user logged in.
-
Use the Azure CLI to log in using either interactive or device code authentication:
az login -
Once authenticated, use the following command to run a batch deployment job:
az ml batch-endpoint invoke --name $ENDPOINT_NAME --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci
-
Use the Azure ML SDK for Python to log in using either interactive or device authentication:
from azure.ai.ml import MLClient from azure.identity import InteractiveAzureCredentials subscription_id = "<subscription>" resource_group = "<resource-group>" workspace = "<workspace>" ml_client = MLClient(InteractiveAzureCredentials(), subscription_id, resource_group, workspace)
-
Once authenticated, use the following command to run a batch deployment job:
job = ml_client.batch_endpoints.invoke( endpoint_name, input=Input(path="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci") )
When working with REST APIs, we recommend to using either a service principal or a managed identity to interact with the API.
In this case, we want to execute a batch endpoint using a service principal already created in Azure Active Directory. To complete the authentication, you will have to create a secret to perform the authentication. Follow these steps:
-
Create a secret to use for authentication as explained at Option 2: Create a new application secret.
-
To authenticate using a service principal, use the following command. For more details see Sign in with Azure CLI.
az login --service-principal -u <app-id> -p <password-or-cert> --tenant <tenant> -
Once authenticated, use the following command to run a batch deployment job:
az ml batch-endpoint invoke --name $ENDPOINT_NAME --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/
-
Create a secret to use for authentication as explained at Option 2: Create a new application secret.
-
To authenticate using a service principal, indicate the tenant ID, client ID and client secret of the service principal using environment variables as demonstrated:
from azure.ai.ml import MLClient from azure.identity import EnvironmentCredential os.environ["AZURE_TENANT_ID"] = "<TENANT_ID>" os.environ["AZURE_CLIENT_ID"] = "<CLIENT_ID>" os.environ["AZURE_CLIENT_SECRET"] = "<CLIENT_SECRET>" subscription_id = "<subscription>" resource_group = "<resource-group>" workspace = "<workspace>" ml_client = MLClient(EnvironmentCredential(), subscription_id, resource_group, workspace)
-
Once authenticated, use the following command to run a batch deployment job:
job = ml_client.batch_endpoints.invoke( endpoint_name, input=Input(path="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci") )
-
Create a secret to use for authentication as explained at Option 2: Create a new application secret.
-
Use the login service from Azure to get an authorization token. Authorization tokens are issued to a particular scope. The resource type for Azure Machine learning is
https://ml.azure.com. The request would look as follows:Request:
POST /{TENANT_ID}/oauth2/token HTTP/1.1 Host: login.microsoftonline.com
Body:
grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&resource=https://ml.azure.com[!IMPORTANT] Notice that the resource scope for invoking a batch endpoints (
https://ml.azure.com1) is different from the resource scope used to manage them. All management APIs in Azure use the resource scopehttps://management.azure.com`, including Azure Machine Learning. -
Once authenticated, use the query to run a batch deployment job:
Request:
POST jobs HTTP/1.1 Host: <ENDPOINT_URI> Authorization: Bearer <TOKEN> Content-Type: application/json
Body:
{ "properties": { "InputData": { "mnistinput": { "JobInputType" : "UriFolder", "Uri": "https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci" } } } }
You can use managed identities to invoke batch endpoint and deployments. Please notice that this manage identity doesn't belong to the batch endpoint, but it is the identity used to execute the endpoint and hence create a batch job. Both user assigned and system assigned identities can be use in this scenario.
On resources configured for managed identities for Azure resources, you can sign in using the managed identity. Signing in with the resource's identity is done through the --identity flag. For more details see Sign in with Azure CLI.
az login --identity
Once authenticated, use the following command to run a batch deployment job:
az ml batch-endpoint invoke --name $ENDPOINT_NAME --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci
On resources configured for managed identities for Azure resources, you can sign in using the managed identity. Use the resource ID along with the ManagedIdentityCredential object as demonstrated in the following example:
from azure.ai.ml import MLClient
from azure.identity import ManagedIdentityCredential
subscription_id = "<subscription>"
resource_group = "<resource-group>"
workspace = "<workspace>"
resource_id = "<resource-id>"
ml_client = MLClient(ManagedIdentityCredential(resource_id), subscription_id, resource_group, workspace)Once authenticated, use the following command to run a batch deployment job:
job = ml_client.batch_endpoints.invoke(
endpoint_name,
input=Input(path="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci")
)You can use the REST API of Azure Machine Learning to start a batch endpoints job using a managed identity. The steps vary depending on the underlying service being used. Some examples include (but are not limited to):
- Managed identity for Azure Data Factory
- How to use managed identities for App Service and Azure Functions.
- How to use managed identities for Azure resources on an Azure VM to acquire an access token.
You can also use the Azure CLI to get an authentication token for the managed identity and the pass it to the batch endpoints URI.