Get an Azure Active Directory token using Azure Active Directory Authentication Library

You can use the Azure Active Directory Authentication Library (ADAL) to acquire Azure Active Directory (Azure AD) access tokens programatically. This article describes basic usage of the ADAL library and required user inputs, with Python examples.

You can also define a service principal in Azure Active Directory and get an Azure AD access token for the service principal rather than a user. See Get an Azure Active Directory token using a service principal.

Configure an app in Azure portal

Register an application with the Azure AD endpoint in Azure portal. Follow the instructions in Quickstart: Register an app with the Azure Active Directory v1.0 endpoint. Alternatively, you can use an app that is already registered.

In the Redirect URI field, select Public client/native (mobile & desktop) and enter a redirect URI. In the following example, the redirect URI value is http://localhost .

Click Register.

Go to App registrations > View all applications and select the app. Copy the Application (client) ID.

Add AzureDatabricks to the Required permissions of the registered application. You must be an admin user to perform this step. If you encounter a “permission” problem performing this step, contact your administrator for help.

On the application page, click View API Permissions.

Click Add a Permission.

Select the tab APIs my organization uses, search for AzureDatabricks and select it.

Select user_impersonation, then click Add permissions.

Click Grant admin consent for ### and then Yes. To perform this step you must be an admin user or have the privilege to grant consent to the application. If you skip this step, you must use the Authorization code flow (interactive) the first time you use the application to provide consent. After that, you can use the Username-password flow (programmatic) method.

You can add additional users to the application. For more information, see Assign users and groups to an application in Azure Active Directory. A user will not be able to obtain a token without required permissions.

Get an Azure Active Directory access token

To get an access token, you can use either:

You must use the authorization code flow to get the Azure AD access token if:

• Two factor authentication is enabled in Azure AD.
• Federated authentication is enabled in Azure AD.
• You are not granted consent to the registered application during application registration.

If you have the authority to sign in with a username and password, you can use the username-password flow to obtain an Azure AD access token.

Authorization code flow (interactive)

There are two steps to acquire an Azure AD access token using the authorization code flow.

1. Obtain the authorization code, which launches a browser window and ask for user login. The authorization code is returned after the user successfully logs in.
2. Use the authorization code to acquire the access token. A refresh token will be returned at the same time and can be used to refresh the access token.

Get the authorization code

You must successfully pass this step before moving forward. If you encounter a “permission” problem, contact your administrator for help.

Parameter	Description
Tenant ID	Tenant ID in Azure AD.
Client ID	The ID of the application registered in Configure an app in Azure portal.
Redirect URI	One of the redirect URIs in your registered application (for example, http://localhost ). The authentication responses are sent to this URI with the authorization code piggybacked.

Get the authorization code using a browser

This is the interactive method to obtain an Azure AD access token.

You can request the authorization code by sending an HTTP request in the browser. Reference Request an authorization code for more information. Replace the fields in the following URL example accordingly:

Paste the URL into your browser and sign in to Azure when you are prompted.

After successful login, the authorization code is attached to the code field in the returned URL. Save the code for later use.

Get the authorization code programmatically

You can alternatively use the semi-programmatic way to obtain the authorization code. The following code snippet will open a browser for user login. After successful login, the code will be returned.

Install the ADAL Python SDK using pip install adal .

Use the Selenium library to open the browser:

Download the browser driver and extract the executable file into your PATH . In this example, the Chrome driver is used. Download the Chrome driver.

Run the following code snippet to obtain the authorization code:

Use the authorization code to obtain the access and refresh tokens

Username-password flow (programmatic)

If you have the authority to sign in with a username and password you can use this programmatic method to obtain an Azure AD access token.

Parameter	Description
Tenant ID	Tenant ID in Azure AD.
Client ID	The application ID of the application registered in Configure an app in Azure portal.
Username and Password	The username (that is, the email address when logging into Azure portal) and password of the user in the tenant.

You can use the following example code to acquire an Azure AD access token with a username and password. Error handling is omitted. For a list of possible errors when getting the token, see the get_token function definition in the ADAL GitHub repository.

Use an Azure AD access token to access the Databricks REST API

This section describes how to use an Azure AD token to call the Databricks REST API. In the following examples, replace with the per-workspace URL of your Azure Databricks deployment.

Python example

This example shows how to list the clusters in an Azure Databricks workspace. It gets the tokens using the get_refresh_and_access_token method defined in Use the authorization code to obtain the access and refresh tokens.

If you are a non-admin user and want to log in as an admin user, you must provide the X-Databricks-Azure-Workspace-Resource-Id header in addition to the ‘Authorization’ : ‘Bearer ‘ header and you must be in a Contributor or Owner role on the workspace resource in Azure. You construct the X-Databricks-Azure-Workspace-Resource-Id value as follows:

curl example

Refresh an access token

If you get a refresh token along with your access token, you can use the refresh token to obtain a new token. By default, the lifetime of access tokens is one hour. You can configure the lifetime of access tokens using the methods in Configurable token lifetimes in Azure Active Directory.

Use Azure Active Directory authentication

APPLIES TO: Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics

Azure Active Directory (Azure AD) authentication is a mechanism for connecting to Azure SQL Database, Azure SQL Managed Instance, and Synapse SQL in Azure Synapse Analytics by using identities in Azure AD.

This article applies to Azure SQL Database, SQL Managed Instance, and Azure Synapse Analytics.

With Azure AD authentication, you can centrally manage the identities of database users and other Microsoft services in one central location. Central ID management provides a single place to manage database users and simplifies permission management. Benefits include the following:

It provides an alternative to SQL Server authentication.

It helps stop the proliferation of user identities across servers.

It allows password rotation in a single place.

Customers can manage database permissions using external (Azure AD) groups.

It can eliminate storing passwords by enabling integrated Windows authentication and other forms of authentication supported by Azure Active Directory.

Azure AD authentication uses contained database users to authenticate identities at the database level.

Azure AD supports token-based authentication for applications connecting to SQL Database and SQL Managed Instance.

Azure AD authentication supports:

• Azure AD cloud-only identities.
• Azure AD hybrid identities that support:
  • Cloud authentication with two options coupled with seamless single sign-on (SSO) Pass-through authentication and password hash authentication.
  • Federated authentication.
• For more information on Azure AD authentication methods and which one to choose, see the following article:
  • Choose the right authentication method for your Azure Active Directory hybrid identity solution

Azure AD supports connections from SQL Server Management Studio that use Active Directory Universal Authentication, which includes Multi-Factor Authentication. Multi-Factor Authentication includes strong authentication with a range of easy verification options — phone call, text message, smart cards with pin, or mobile app notification. For more information, see SSMS support for Azure AD Multi-Factor Authentication with Azure SQL Database, SQL Managed Instance, and Azure Synapse

Azure AD supports similar connections from SQL Server Data Tools (SSDT) that use Active Directory Interactive Authentication. For more information, see Azure Active Directory support in SQL Server Data Tools (SSDT)

Connecting to a SQL Server instance that’s running on an Azure virtual machine (VM) is not supported using an Azure Active Directory account. Use a domain Active Directory account instead.

The configuration steps include the following procedures to configure and use Azure Active Directory authentication.

1. Create and populate Azure AD.
2. Optional: Associate or change the active directory that is currently associated with your Azure Subscription.
3. Create an Azure Active Directory administrator.
4. Configure your client computers.
5. Create contained database users in your database mapped to Azure AD identities.
6. Connect to your database by using Azure AD identities.

To learn how to create and populate Azure AD, and then configure Azure AD with Azure SQL Database, SQL Managed Instance, and Synapse SQL in Azure Synapse Analytics, see Configure Azure AD with Azure SQL Database.

Trust architecture

• Only the cloud portion of Azure AD, SQL Database, SQL Managed Instance, and Azure Synapse is considered to support Azure AD native user passwords.
• To support Windows single sign-on credentials (or user/password for Windows credential), use Azure Active Directory credentials from a federated or managed domain that is configured for seamless single sign-on for pass-through and password hash authentication. For more information, see Azure Active Directory Seamless Single Sign-On.
• To support Federated authentication (or user/password for Windows credentials), the communication with ADFS block is required.

For more information on Azure AD hybrid identities, the setup, and synchronization, see the following articles:

For a sample federated authentication with ADFS infrastructure (or user/password for Windows credentials), see the diagram below. The arrows indicate communication pathways.

The following diagram indicates the federation, trust, and hosting relationships that allow a client to connect to a database by submitting a token. The token is authenticated by an Azure AD, and is trusted by the database. Customer 1 can represent an Azure Active Directory with native users or an Azure AD with federated users. Customer 2 represents a possible solution including imported users, in this example coming from a federated Azure Active Directory with ADFS being synchronized with Azure Active Directory. It’s important to understand that access to a database using Azure AD authentication requires that the hosting subscription is associated to the Azure AD. The same subscription must be used to create the Azure SQL Database, SQL Managed Instance, or Azure Synapse resources.

Administrator structure

When using Azure AD authentication, there are two Administrator accounts: the original Azure SQL Database administrator and the Azure AD administrator. The same concepts apply to Azure Synapse. Only the administrator based on an Azure AD account can create the first Azure AD contained database user in a user database. The Azure AD administrator login can be an Azure AD user or an Azure AD group. When the administrator is a group account, it can be used by any group member, enabling multiple Azure AD administrators for the server. Using group account as an administrator enhances manageability by allowing you to centrally add and remove group members in Azure AD without changing the users or permissions in SQL Database or Azure Synapse. Only one Azure AD administrator (a user or group) can be configured at any time.

Permissions

To create new users, you must have the ALTER ANY USER permission in the database. The ALTER ANY USER permission can be granted to any database user. The ALTER ANY USER permission is also held by the server administrator accounts, and database users with the CONTROL ON DATABASE or ALTER ON DATABASE permission for that database, and by members of the db_owner database role.

To create a contained database user in Azure SQL Database, SQL Managed Instance, or Azure Synapse, you must connect to the database or instance using an Azure AD identity. To create the first contained database user, you must connect to the database by using an Azure AD administrator (who is the owner of the database). This is demonstrated in Configure and manage Azure Active Directory authentication with SQL Database or Azure Synapse. Azure AD authentication is only possible if the Azure AD admin was created for Azure SQL Database, SQL Managed Instance, or Azure Synapse. If the Azure Active Directory admin was removed from the server, existing Azure Active Directory users created previously inside SQL Server can no longer connect to the database using their Azure Active Directory credentials.

Azure AD features and limitations

The following members of Azure AD can be provisioned for Azure SQL Database:

• Native members: A member created in Azure AD in the managed domain or in a customer domain. For more information, see Add your own domain name to Azure AD.
• Members of an Active Directory domain federated with Azure Active Directory on a managed domain configured for seamless single sign-on with pass-through or password hash authentication. For more information, see Microsoft Azure now supports federation with Windows Server Active Directory and Azure Active Directory Seamless Single Sign-On.
• Imported members from other Azure AD’s who are native or federated domain members.
• Active Directory groups created as security groups.

Azure AD users that are part of a group that has db_owner server role cannot use the CREATE DATABASE SCOPED CREDENTIAL syntax against Azure SQL Database and Azure Synapse. You will see the following error:

SQL Error [2760] [S0001]: The specified schema name ‘user@mydomain.com’ either does not exist or you do not have permission to use it.

Grant the db_owner role directly to the individual Azure AD user to mitigate the CREATE DATABASE SCOPED CREDENTIAL issue.

These system functions return NULL values when executed under Azure AD principals:

SQL Managed Instance

• Azure AD server principals (logins) and users are supported for SQL Managed Instance.
• Setting Azure AD server principals (logins) mapped to an Azure AD group as database owner is not supported in SQL Managed Instance.
  • An extension of this is that when a group is added as part of the dbcreator server role, users from this group can connect to the SQL Managed Instance and create new databases, but will not be able to access the database. This is because the new database owner is SA, and not the Azure AD user. This issue does not manifest if the individual user is added to the dbcreator server role.
• SQL Agent management and jobs execution are supported for Azure AD server principals (logins).
• Database backup and restore operations can be executed by Azure AD server principals (logins).
• Auditing of all statements related to Azure AD server principals (logins) and authentication events is supported.
• Dedicated administrator connection for Azure AD server principals (logins) which are members of sysadmin server role is supported.
  • Supported through SQLCMD Utility and SQL Server Management Studio.
• Logon triggers are supported for logon events coming from Azure AD server principals (logins).
• Service Broker and DB mail can be setup using an Azure AD server principal (login).

Connect by using Azure AD identities

Azure Active Directory authentication supports the following methods of connecting to a database using Azure AD identities:

• Azure Active Directory Password
• Azure Active Directory Integrated
• Azure Active Directory Universal with Multi-Factor Authentication
• Using Application token authentication

The following authentication methods are supported for Azure AD server principals (logins):

• Azure Active Directory Password
• Azure Active Directory Integrated
• Azure Active Directory Universal with Multi-Factor Authentication