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 |