Azure Authentication in MSTICPy

There are several components in MSTICPy that use Azure Services and require authentication to use them. Some examples are:

Microsoft Sentinel, Microsoft Graph, Microsoft Defender and Azure Resource Graph data providers
Microsoft Sentinel APIs
Azure Data APIs
Microsoft Sentinel TI provider

MSTICPy uses Azure SDKs and standard Azure credentials to authenticate to these services.

Azure supports many different types of credential - the different credential types are a function of the way that you authenticate to Azure Active Directory (AAD).

Some credential types are distinguished based on what you use to authenticate your identity to AAD. For example:

UsernamePasswordCredential - simple username and password
CertificateCredential - certificate private key
ClientSecretCredential - AppID and App secret
ManagedIdentityCredential - Uses the AAD assigned identity for something like a domain-joined Virtual machine.

Other types have helper functionality that allow you to authenticate in specific circumstances:

InteractiveBrowserCredential - invokes a browser to initiate the authentication flow.
EnvironmentCredential - looks for specific environment variables that contain credential details such as a password or App secret.
DeviceCodeCredential - creates a one-time device code and returns login URL to initiate the authentication flow.

Some types of credential can be obtained from applications or system components in which you have previously authenticated such as:

AzureCliCredential
VisualStudioCodeCredential
AzurePowerShellCredential

A relatively complete list can be found here Azure Identity Python SDK Credential classes

Note

In MSTICPy we refer to the different “credential types” as “authentication methods”. The function parameter used to specify the method(s) that you want to use is auth_methods. The configuration item in msticpyconfig.yaml is also named auth_methods and is in the Azure section of the settings.

How to choose a credential type

Since there are so many credential types, working out which one to use can be confusing.

MSTICPy, by default, will try to use the following credential types (and in this order):

Managed Identity
Azure CLI
Device Code

This means that MSTICPy will try to obtain credentials of each these types in turn. If it finds a matching credential type it will try to use that to authenticate you to the Azure service that you are trying to access. In the default case it will do the following:

Check to see if you are running on a system (a host/virtual machine) that has a system-assigned identity OR (as in the case of Azure Machine Learning) has support for user-assigned managed identities. See here for detailed information about Managed Identities
Look for an authenticated Azure CLI session and try to obtain the credential from Azure CLI
If both fail, it will prompt with a device code and login URL that you must browse to, paste in the device code and complete the authentication flow.

You can change the default authentication types used by MSTICPy by configuring settings in your msticpyconfig.yaml - see Setting your MSTICPY authentication method defaults

Azure authentication methods supported by MSTICPy

env - Use credentials set in environment variables
cli - Use credentials available in an local AzureCLI logon
msi - Use the Managed Service Identity (MSI) credentials of the machine you are running the notebook kernel on
devicecode - use browser-based device code authentication flow
vscode - Use credentials from your authenticated VS Code session
powershell - Use credentials from an authenticated Azure Powershell session
clientsecret - Use an Azure AppID and client secret
certificate - Use client certificate authentication.
interactive - Interactive browser logon

Common credential flows

Using Azure CLI

auth_method = “cli”

Due to its ability to cache credentials, we recommend using Azure CLI logon. This allows all MSTICPy Azure functions to try to obtain current credentials from Azure CLI rather than initiate an interactive authentication. This is especially helpful when using multiple Azure components or when using multiple notebooks.

If the host running your notebook kernel does not have Azure CLI installed you can install it from the Azure CLI install page.

To log in using Azure CLI enter the following:

From a terminal:

az login

From a notebook

!az login

Using Environment Credentials

auth_method = “env”

You can use environment credentials with either username and password or with an Azure AppID and secret.

For username and password you must set these environment variables prior to attempting to authenticate:

variable name	value
AZURE_TENANT_ID	id of the user’s Azure Active Directory tenant
AZURE_USERNAME	a username (usually an email address)
AZURE_PASSWORD	that user’s password

To use AppID and secret, set these environment variables

variable name	value
AZURE_CLIENT_ID	id of an Azure Active Directory application
AZURE_TENANT_ID	id of the application’s Azure Active Directory tenant
AZURE_CLIENT_SECRET	one of the application’s client secrets

Using Device-code Credentials

auth_method = “devicecode”

Using device code authentication causes a one-time code and login URL to be displayed in the notebook or console.

Select and copy the code to the clipboard.
Open a browser and navigate to the login URL provided.
Paste the code into the dialog box.
Continue with the normal browser-based authentication flow (this may require multi-factor authentication depending on your organization’s access policies)

User Managed Identity Credentials

If you have a usable managed identity on the system you are using (the system where the Jupyter notebook kernel is running) the credentials will be obtained automatically and used for authentication.

Using VSCode and AzurePowerShell Credentials

auth_method = “vscode” auth_method = “powershell”

As long as you have an active authenticated session in VS Code or PowerShell, the credentials should be automatically obtained and used.

Setting your MSTICPY authentication method defaults

You can use the MSTICPy settings editor to specify which authentication methods (credential types) you want to use.

See the section Default Azure authentication methods for more details.

Note

the settings editor does not currently allow you to specify a preference order for this. To do this, open msticpyconfig.yaml in an editor and manually set the order that you want.

Specifying authentication method preferences when authenticating

Several MSTICPy APIs support the auth_methods parameter. These include:

The az_connect function.
The QueryProvider.connect for Azure data services (such as Microsoft Sentinel)

Specify the list of one or more auth_methods that you want to use as a list of strings. The authentication methods will be tried in the order specified in the list.

az_connect(auth_methods=["env", "cli"])

The values for the available authentication methods are list in the table below.

value	Credential type
env	EnvironmentCredential	Use credentials set in environment variables
cli	AzureCliCredential	Use credentials available in an local AzureCLI logon
msi	ManagedIdentityCredential	Use the Managed Service Identity (MSI) credentials of the machine you are running the notebook kernel on
devicecode	DeviceCodeCredential	Use browser-based device code authentication flow
vscode	VisualStudioCodeCredential	Use credentials from your authenticated VS Code session
powershell	AzurePowerShellCredentialUse	Use credentials from an authenticated Azure Powershell session
clientsecret	ClientSecretCredential	Use an Azure AppID and client secret
certificate	CertificateCredential	Use client certificate authentication.
interactive	InteractiveBrowserCredential	Use Interactive browser logon flow