Share via

Authenticating the Defender EASM REST API

Every REST API call that is made against a Microsoft Defender External Attack Surface Management (Defender EASM) resource must include an Authorization header containing a valid Azure AD Bearer Token. This token is used to determine who the caller is and what they have access to within the resource. The token may be generated via an interactive user authentication flow or a client service principal.

User authentication flow

The User Authentication scenario is useful for testing and development purposes but may not be feasible for certain scripting scenarios. Generating a token via user authentication requires an interactive flow involving logging in via a browser. All actions assume the use of the Azure Command-Line Interface (CLI).

  1. Log in to your tenant. This step will launch a web browser to perform the proper login steps.

    az login --tenant <tenant id>

  2. Generate an associated token for the proper resource scope. This token is used within the Authentication header.

    Control Plane

    az account get-access-token

    Data Plane

    az account get-access-token --scope 'https://easm.defender.microsoft.com/.default'

Client service principal

The Client Service Principal scenario is useful for background processes (such as scripts) that require "on demand" token generation. Generating a token via a client service principal requires that an application be registered with an associated client secret and the proper subscription access controls:

  1. Create an application via the App registrations section of the portal.
  2. In the Certificates and secrets section, click New client secret, enter the required information, and generate the secret. Make sure to copy the generated value as it will become unavailable once you leave the section.
  3. Open the subscription in which the principal will be used.
  4. In the Access Control (IAM) section, click Add -> Add Role Assignment.
  5. Select the Contributor role and then click Next.
  6. Click Select members, search for the app registered in step 1, select the app, and then click Select.
  7. Click Next, review the information to make sure it is correct, and then click Review + assign.

Once the application is set up, an associated token may be generated using the client (application) id and secret. All actions assume the use of the Azure Command-Line Interface (CLI).

  1. Log in to your service principal.

    az login --service-principal -u <client id> -p <client secret> --tenant <tenant id>

  2. Generate an associated token for the proper resource scope. This token is used within the Authentication header.

    Control Plane

    az account get-access-token

    Data Plane

    az account get-access-token --scope 'https://easm.defender.microsoft.com/.default'