Tutorial: Register a web API with the Microsoft identity platform

  • Article

In this tutorial, you learn how to register a web API in a Microsoft Entra ID tenant. You must register an application in the Microsoft Entra admin center to enable your application to interact with the Microsoft identity platform. In this article, you;

  • Register a web API in a tenant
  • Record the web API's unique identifiers
  • Expose an API by adding a scope

Prerequisites

  • An Azure account with an active subscription. Create an account.
  • This Azure account must have permissions to manage applications. Use any of the following roles needed to register the application:
    • Application Administrator
    • Application developer
    • Cloud Application Administrator

Register the application and record identifiers

Tip

Steps in this article might vary slightly based on the portal you start from.

To complete registration, provide the application a name and specify the supported account types. Once registered, the application Overview page will display the identifiers needed in the application source code.

  1. Sign in to the Microsoft Entra admin center as at least an Application Developer.

  2. If you have access to multiple tenants, use the Settings icon in the top menu to switch to the tenant in which you want to register the application from the Directories + subscriptions menu.

  3. Browse to Identity > Applications > App registrations.

  4. Select New registration.

  5. Enter a Name for the application, such as NewWebAPI1.

  6. For Supported account types, select Accounts in this organizational directory only. For information on different account types, select Help me choose option.

  7. Select Register.

    Screenshot that shows how to enter a name and select the account type.

  8. The application's Overview pane is displayed when registration is complete. Record the Directory (tenant) ID and the Application (client) ID to be used in your application source code.

    Screenshot that shows the identifier values on the overview page.

Note

The Supported account types can be changed by referring to Modify the accounts supported by an application.

Expose an API

Once the API is registered, you can configure its permission by defining the scopes that the API exposes to client applications. Client applications request permission to perform operations by passing an access token along with its requests to the protected web API. The web API then performs the requested operation only if the access token it receives contains the required scopes.

  1. Under Manage, select Expose an API > Add a scope. Accept the proposed Application ID URI (api://{clientId}) by selecting Save and continue. The {clientId} will be the value recorded from the Overview page. Then enter the following information:

    1. For Scope name, enter Forecast.Read.
    2. For Who can consent, ensure that the Admins and users option is selected.
    3. In the Admin consent display name box, enter Read forecast data.
    4. In the Admin consent description box, enter Allows the application to read weather forecast data.
    5. In the User consent display name box, enter Read forecast data.
    6. In the User consent description box, enter Allows the application to read weather forecast data.
    7. Ensure that the State is set to Enabled.

  2. Select Add scope. If the scope has been entered correctly, it'll be listed in the Expose an API pane.

    Screenshot that shows the field values when adding the scope to an API.

Next steps

Tutorial: Create an ASP.NET Core project and configure the API