Set up authentication for Azure Machine Learning resources and workflows
APPLIES TO: Azure CLI ml extension v2 (current) Python SDK azure-ai-ml v2 (current)
Learn how to set up authentication to your Azure Machine Learning workspace from the Azure CLI or Azure Machine Learning SDK v2. Authentication to your Azure Machine Learning workspace is based on Microsoft Entra ID for most things. In general, there are four authentication workflows that you can use when connecting to the workspace:
Interactive: You use your account in Microsoft Entra ID to either directly authenticate, or to get a token that is used for authentication. Interactive authentication is used during experimentation and iterative development. Interactive authentication enables you to control access to resources (such as a web service) on a per-user basis.
Service principal: You create a service principal account in Microsoft Entra ID, and use it to authenticate or get a token. A service principal is used to authenticate an automated process to the service without requiring user interaction. For example, a continuous integration and deployment script that trains and tests a model every time the training code changes.
Azure CLI session: You use an active Azure CLI session to authenticate. The Azure CLI extension for Machine Learning (the
ml
extension or CLI v2) is a command line tool for working with Azure Machine Learning. You can sign in to Azure via the Azure CLI on your local workstation, without storing credentials in Python code or prompting the user to authenticate. Similarly, you can reuse the same scripts as part of continuous integration and deployment pipelines, while authenticating the Azure CLI with a service principal identity.Managed identity: When using the Azure Machine Learning SDK v2 on a compute instance or on an Azure Virtual Machine, you can use a managed identity for Azure. This workflow allows the VM to connect to the workspace using the managed identity, without storing credentials in Python code or prompting the user to authenticate. Azure Machine Learning compute clusters can also be configured to use a managed identity to access the workspace when training models.
Regardless of the authentication workflow used, Azure role-based access control (Azure RBAC) is used to scope the level of access (authorization) allowed to the resources. For example, an admin or automation process might have access to create a compute instance, but not use it. While a data scientist could use it, but not delete or create it. For more information, see Manage access to Azure Machine Learning workspace.
Microsoft Entra Conditional Access can be used to further control or restrict access to the workspace for each authentication workflow. For example, an admin can allow workspace access from managed devices only.
Prerequisites
Create an Azure Machine Learning workspace.
Configure your development environment or use an Azure Machine Learning compute instance and install the Azure Machine Learning SDK v2.
Install the Azure CLI.
Microsoft Entra ID
All the authentication workflows for your workspace rely on Microsoft Entra ID. If you want users to authenticate using individual accounts, they must have accounts in your Microsoft Entra ID. If you want to use service principals, they must exist in your Microsoft Entra ID. Managed identities are also a feature of Microsoft Entra ID.
For more on Microsoft Entra ID, see What is Microsoft Entra authentication.
Once you create the Microsoft Entra accounts, see Manage access to Azure Machine Learning workspace for information on granting them access to the workspace and other operations in Azure Machine Learning.
Use interactive authentication
APPLIES TO: Python SDK azure-ai-ml v2 (current)
Interactive authentication uses the Azure Identity package for Python. Most examples use DefaultAzureCredential
to access your credentials. When a token is needed, it requests one using multiple identities (EnvironmentCredential
, ManagedIdentityCredential
, SharedTokenCacheCredential
, VisualStudioCodeCredential
, AzureCliCredential
, AzurePowerShellCredential
) in turn, stopping when one provides a token. For more information, see the DefaultAzureCredential class reference.
The following code is an example of using DefaultAzureCredential
to authenticate. If authentication using DefaultAzureCredential
fails, a fallback of authenticating through your web browser is used instead.
from azure.identity import DefaultAzureCredential, InteractiveBrowserCredential
try:
credential = DefaultAzureCredential()
# Check if given credential can get token successfully.
credential.get_token("https://management.azure.com/.default")
except Exception as ex:
# Fall back to InteractiveBrowserCredential in case DefaultAzureCredential not work
# This will open a browser page for
credential = InteractiveBrowserCredential()
After the credential object is created, the MLClient class is used to connect to the workspace. For example, the following code uses the from_config()
method to load connection information:
from azure.ai.ml import MLClient
try:
ml_client = MLClient.from_config(credential=credential)
except Exception as ex:
# NOTE: Update following workspace information to contain
# your subscription ID, resource group name, and workspace name
client_config = {
"subscription_id": "<SUBSCRIPTION_ID>",
"resource_group": "<RESOURCE_GROUP>",
"workspace_name": "<AZUREML_WORKSPACE_NAME>",
}
# write and reload from config file
import json, os
config_path = "../.azureml/config.json"
os.makedirs(os.path.dirname(config_path), exist_ok=True)
with open(config_path, "w") as fo:
fo.write(json.dumps(client_config))
ml_client = MLClient.from_config(credential=credential, path=config_path)
print(ml_client)
Configure a service principal
To use a service principal (SP), you must first create the SP. Then grant it access to your workspace. As mentioned earlier, Azure role-based access control (Azure RBAC) is used to control access, so you must also decide what access to grant the SP.
Important
When using a service principal, grant it the minimum access required for the task it is used for. For example, you would not grant a service principal owner or contributor access if all it is used for is reading the access token for a web deployment.
The reason for granting the least access is that a service principal uses a password to authenticate, and the password may be stored as part of an automation script. If the password is leaked, having the minimum access required for a specific tasks minimizes the malicious use of the SP.
The easiest way to create an SP and grant access to your workspace is by using the Azure CLI. To create a service principal and grant it access to your workspace, use the following steps:
Note
You must be an admin on the subscription to perform all of these steps.
Authenticate to your Azure subscription:
az login
If the CLI can open your default browser, it does so and loads a sign-in page. Otherwise, you need to open a browser and follow the instructions on the command line. The instructions involve browsing to https://aka.ms/devicelogin and entering an authorization code.
If you have multiple Azure subscriptions, you can use the
az account set -s <subscription name or ID>
command to set the subscription. For more information, see Use multiple Azure subscriptions.For other methods of authenticating, see Sign in with Azure CLI.
Create the service principal. In the following example, an SP named ml-auth is created:
az ad sp create-for-rbac --json-auth --name ml-auth --role Contributor --scopes /subscriptions/<subscription id>
The parameter
--json-auth
is available in Azure CLI versions >= 2.51.0. Versions before this use--sdk-auth
.The output is a JSON document similar to the following. Take note of the
clientId
,clientSecret
, andtenantId
fields, as you need them for other steps in this article.{ "clientId": "your-client-id", "clientSecret": "your-client-secret", "subscriptionId": "your-sub-id", "tenantId": "your-tenant-id", "activeDirectoryEndpointUrl": "https://login.microsoftonline.com", "resourceManagerEndpointUrl": "https://management.azure.com", "activeDirectoryGraphResourceId": "https://graph.windows.net", "sqlManagementEndpointUrl": "https://management.core.windows.net:5555", "galleryEndpointUrl": "https://gallery.azure.com/", "managementEndpointUrl": "https://management.core.windows.net" }
Retrieve the details for the service principal by using the
clientId
value returned in the previous step:az ad sp show --id your-client-id
The following JSON is a simplified example of the output from the command. Take note of the
objectId
field, as you'll need its value for the next step.{ "accountEnabled": "True", "addIns": [], "appDisplayName": "ml-auth", ... ... ... "objectId": "your-sp-object-id", "objectType": "ServicePrincipal" }
To grant access to the workspace and other resources used by Azure Machine Learning, use the information in the following articles:
Important
Owner access allows the service principal to do virtually any operation in your workspace. It is used in this document to demonstrate how to grant access; in a production environment Microsoft recommends granting the service principal the minimum access needed to perform the role you intend it for. For information on creating a custom role with the access needed for your scenario, see Manage access to Azure Machine Learning workspace.
Configure a managed identity
Important
Managed identity is only supported when using the Azure Machine Learning SDK from an Azure Virtual Machine, an Azure Machine Learning compute cluster, or compute instance.
Managed identity with a VM
Enable a system-assigned managed identity for Azure resources on the VM.
From the Azure portal, select your workspace and then select Access Control (IAM).
Select Add, Add Role Assignment to open the Add role assignment page.
Select the role you want to assign the managed identity. For example, Reader. For detailed steps, see Assign Azure roles using the Azure portal.
Managed identity with compute cluster
For more information, see Set up managed identity for compute cluster.
Managed identity with compute instance
For more information, see Set up managed identity for compute instance.
Use service principal authentication
APPLIES TO: Python SDK azure-ai-ml v2 (current)
Authenticating with a service principal uses the Azure Identity package for Python. The DefaultAzureCredential
class looks for the following environment variables and uses the values when authenticating as the service principal:
AZURE_CLIENT_ID
- The client ID returned when you created the service principal.AZURE_TENANT_ID
- The tenant ID returned when you created the service principal.AZURE_CLIENT_SECRET
- The password/credential generated for the service principal.
Tip
During development, consider using the python-dotenv package to set these environment variables. Python-dotenv loads environment variables from .env
files. The standard .gitignore
file for Python automatically excludes .env
files, so they shouldn't be checked into any GitHub repos during development.
The following example demonstrates using python-dotenv to load the environment variables from a .env
file and then using DefaultAzureCredential
to create the credential object:
from dotenv import load_dotenv
if ( os.environ['ENVIRONMENT'] == 'development'):
print("Loading environment variables from .env file")
load_dotenv(".env")
from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()
# Check if given credential can get token successfully.
credential.get_token("https://management.azure.com/.default")
After the credential object is created, the MLClient class is used to connect to the workspace. For example, the following code uses the from_config()
method to load connection information:
try:
ml_client = MLClient.from_config(credential=credential)
except Exception as ex:
# NOTE: Update following workspace information to contain
# your subscription ID, resource group name, and workspace name
client_config = {
"subscription_id": "<SUBSCRIPTION_ID>",
"resource_group": "<RESOURCE_GROUP>",
"workspace_name": "<AZUREML_WORKSPACE_NAME>",
}
# write and reload from config file
import json, os
config_path = "../.azureml/config.json"
os.makedirs(os.path.dirname(config_path), exist_ok=True)
with open(config_path, "w") as fo:
fo.write(json.dumps(client_config))
ml_client = MLClient.from_config(credential=credential, path=config_path)
print(ml_client)
The service principal can also be used to authenticate to the Azure Machine Learning REST API. You use the Microsoft Entra ID client credentials grant flow, which allow service-to-service calls for headless authentication in automated workflows.
Important
If you are currently using Azure Active Directory Authentication Library (ADAL) to get credentials, we recommend that you Migrate to the Microsoft Authentication Library (MSAL). ADAL support ended June 30, 2022.
For information and samples on authenticating with MSAL, see the following articles:
- JavaScript - How to migrate a JavaScript app from ADAL.js to MSAL.js.
- Node.js - How to migrate a Node.js app from Microsoft Authentication Library to MSAL.
- Python - Microsoft Authentication Library to MSAL migration guide for Python.
Use managed identity authentication
APPLIES TO: Python SDK azure-ai-ml v2 (current)
Authenticating with a managed identity uses the Azure Identity package for Python. To authenticate to the workspace from a VM or compute cluster that is configured with a managed identity, use the DefaultAzureCredential
class. This class automatically detects if a managed identity is being used, and uses the managed identity to authenticate to Azure services.
The following example demonstrates using the DefaultAzureCredential
class to create the credential object, then using the MLClient
class to connect to the workspace:
from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()
# Check if given credential can get token successfully.
credential.get_token("https://management.azure.com/.default")
try:
ml_client = MLClient.from_config(credential=credential)
except Exception as ex:
# NOTE: Update following workspace information to contain
# your subscription ID, resource group name, and workspace name
client_config = {
"subscription_id": "<SUBSCRIPTION_ID>",
"resource_group": "<RESOURCE_GROUP>",
"workspace_name": "<AZUREML_WORKSPACE_NAME>",
}
# write and reload from config file
import json, os
config_path = "../.azureml/config.json"
os.makedirs(os.path.dirname(config_path), exist_ok=True)
with open(config_path, "w") as fo:
fo.write(json.dumps(client_config))
ml_client = MLClient.from_config(credential=credential, path=config_path)
print(ml_client)
Use Conditional Access
As an administrator, you can enforce Microsoft Entra Conditional Access policies for users signing in to the workspace. For example, you can require two-factor authentication, or allow sign in only from managed devices. The following are the app IDs to use for conditional access:
Application ID | Name | Note |
---|---|---|
d7304df8-741f-47d3-9bc2-df0e24e2071f | Azure Machine Learning Workbench Web App | Azure Machine Learning studio |
cb2ff863-7f30-4ced-ab89-a00194bcf6d9 | Azure AI Studio App | Azure AI Studio |
Check for service principal
Before adding the conditional access policy, verify that the application ID is listed in the Enterprise applications section of the Azure portal:
Important
To perform the steps in this section, you must have Microsoft Entra ID P2. For more information, see Microsoft Entra licensing.
Search for Enterprise Applications in the search field at the top of the portal and select the enterprise application entry.
From Enterprise Applications, use the Search by application name or object ID field to search for the entry you want to use with conditional access. If an entry appears, a service principal already exists for the application ID. Skip the rest of the steps in this section and go to the Add conditional access section.
Important
The only filter should be Application ID starts with. Remove any other filter that may be present.
If no entry appears, use the following Azure PowerShell cmdlet to create a service principal for the application ID:
New-AzAdServicePrincipal -ApplicationId "application-ID"
For example,
New-AzADServicePrincipal -ApplicationId "d7304df8-741f-47d3-9bc2-df0e24e2071f"
.After you create the service principal, return to Enterprise applications and verify that you can now find the application ID. You can find the list of IDs in the Use Conditional Access section.
Add conditional access
To use Conditional Access, assign the Conditional Access policy to the application ID. If the application doesn't appear in Conditional Access, use the steps in the Check for service principal section.