Use Azure AD authentication to access the Media Services API with REST
When you're using Azure AD authentication with Azure Media Services, you can authenticate in one of two ways:
- User authentication authenticates a person who is using the app to interact with Azure Media Services resources. The interactive application should first prompt the user for credentials. An example is a management console app that's used by authorized users to monitor encoding jobs or live streaming.
- Service principal authentication authenticates a service. Applications that commonly use this authentication method are apps that run daemon services, middle-tier services, or scheduled jobs, such as web apps, function apps, logic apps, APIs, or microservices.
This tutorial shows you how to use Azure AD service principal authentication to access AMS API with REST.
In this tutorial, you learn how to:
- Get the authentication information from the Azure portal
- Get the access token using Postman
- Test the Assets API using the access token
Important
Currently, Media Services supports the Azure Access Control services authentication model. However, Access Control authentication will be deprecated June 1, 2018. We recommend that you migrate to the Azure AD authentication model as soon as possible.
Prerequisites
If you don't have an Azure subscription, create a free account before you begin.
Create an Azure Media Services account using the Azure portal.
Review the Accessing Azure Media Services API with Azure AD authentication overview article.
Install the Postman REST client to execute the REST APIs shown in this article.
In this tutorial, we are using Postman but any REST tool would be suitable. Other alternatives are: Visual Studio Code with the REST plugin or Telerik Fiddler.
Get the authentication information from the Azure portal
Overview
To access Media Services API, you need to collect the following data points.
Setting | Example | Description |
---|---|---|
Azure Active Directory tenant domain | microsoft.onmicrosoft.com | Azure AD as a Secure Token Service (STS) endpoint is created using the following format: https://login.microsoftonline.com/{your-ad-tenant-name.onmicrosoft.com}/oauth2/token. Azure AD issues a JWT in order to access resources (an access token). |
REST API endpoint | https://amshelloworld.restv2.westus.media.azure.net/api/ | This is the endpoint against which all Media Services REST API calls in your application are made. |
Client ID (Application ID) | f7fbbb29-a02d-4d91-bbc6-59a2579259d2 | Azure AD application (client) ID. The client ID is required to get the access token. |
Client Secret | +mUERiNzVMoJGggD6aV1etzFGa1n6KeSlLjIq+Dbim0= | Azure AD application keys (client secret). The client secret is required to get the access token. |
Get Azure Active Directory auth info from the Azure portal
To get the information, follow these steps:
Log in to the Azure portal.
Navigate to your AMS instance.
Select API access.
Click on Connect to Azure Media Services API with service principal.
Select an existing Azure AD application or create a new one (shown below).
Note
For the Azure Media REST request to succeed, the calling user must have a Contributor or Owner role for the Media Services account it is trying to access. If you get an exception that says "The remote server returned an error: (401) Unauthorized," see Access control.
If you need to create a new AD app, follow these steps:
Press Create New.
Enter a name.
Press Create New again.
Press Save.
The new app shows up on the page.
Get the Client ID (Application ID).
Select the application.
Get the Client ID from the window on the right.
Get the application's Key (client secret).
Click the Manage application button (notice that the Client ID info is under Application ID).
Press Keys.
Generate the app key (client secret) by filling in DESCRIPTION and EXPIRES and pressing Save.
Once the Save button is pressed, the key value appears. Copy the key value before leaving the blade.
You can add values for AD connection parameters to your web.config or app.config file, to later use in your code.
Important
The Client key is an important secret and should be properly secured in a key vault or encrypted in production.
Get the access token using Postman
This section shows how to use Postman to execute a REST API that returns a JWT Bearer Token (access token). To call any Media Services REST API, you need to add the "Authorization" header to the calls, and add the value of "Bearer your_access_token" to each call (as shown in the next section of this tutorial).
Open Postman.
Select POST.
Enter the URL that includes your tenant name using the following format: the tenant name should end with .onmicrosoft.com and the URL should end with oauth2/token:
https://login.microsoftonline.com/{your-aad-tenant-name.onmicrosoft.com}/oauth2/token
Select the Headers tab.
Enter the Headers information using the "Key/Value" data grid.
Alternatively, click Bulk Edit link on the right of the Postman window and paste the following code.
Content-Type:application/x-www-form-urlencoded Keep-Alive:true
Press the Body tab.
Enter the body information using the "Key/Value" data grid (replace the client ID and secret values).
Alternatively, click Bulk Edit on the right of the Postman window and paste the following body (replace the client ID and secret values):
grant_type:client_credentials client_id:{Your Client ID that you got from your Azure AD Application} client_secret:{Your client secret that you got from your Azure AD Application's Keys} resource:https://rest.media.azure.net
Press Send.
The returned response contains the access token that you need to use to access any AMS APIs.
Test the Assets API using the access token
This section shows how to access the Assets API using Postman.
Open Postman.
Select GET.
Paste the REST API endpoint (for example, https://amshelloworld.restv2.westus.media.azure.net/api/Assets)
Select the Authorization tab.
Select Bearer Token.
Paste the token that was created in the previous section.
Note
The Postman UX could be different between a Mac and PC. If the Mac version does not have the "Bearer Token" option in the Authentication section dropdown, you should add the Authorization header manually on the Mac client.
Select Headers.
Click Bulk Edit link on the right the Postman window.
Paste the following headers:
x-ms-version:2.19 Accept:application/json Content-Type:application/json DataServiceVersion:3.0 MaxDataServiceVersion:3.0
Press Send.
The returned response contains the assets that are in your account.