Quickstart: Configure an application to expose a web API
In this quickstart, you register a web API with the Microsoft identity platform and expose it to client apps by adding an example scope. By registering your web API and exposing it through scopes, you can provide permissions-based access to its resources to authorized users and client apps that access your API.
- An Azure account with an active subscription - create an account for free
- Completion of Quickstart: Set up a tenant
Register the web API
To provide scoped access to the resources in your web API, you first need to register the API with the Microsoft identity platform.
- Perform the steps in the Register an application section of Quickstart: Register an app with the Microsoft identity platform.
- Skip the Add a redirect URI and Configure platform settings sections. You don't need to configure a redirect URI for a web API since no user is logged in interactively.
- Skip the Add credentials section for now. Only if your API accesses a downstream API would it need its own credentials, a scenario not covered in this article.
With your web API registered, you're ready to add the scopes that your API's code can use to provide granular permission to consumers of your API.
Add a scope
The code in a client application requests permission to perform operations defined by your web API by passing an access token along with its requests to the protected resource (the web API). Your web API then performs the requested operation only if the access token it receives contains the scopes required for the operation.
First, follow these steps to create an example scope named
Sign in to the Azure portal.
If you have access to multiple tenants, use the Directories + subscriptions filter in the top menu to select the tenant containing your client app's registration.
Select Azure Active Directory > App registrations, and then select your API's app registration.
Select Expose an API
Select Set next to Application ID URI if you haven't yet configured one.
You can use the default value of
api://<application-client-id>or another supported App ID URI pattern. The App ID URI acts as the prefix for the scopes you'll reference in your API's code, and it must be globally unique.
Select Add a scope:
Next, specify the scope's attributes in the Add a scope pane. For this walk-through, you can use the example values or specify your own.
Field Description Example Scope name The name of your scope. A common scope naming convention is
Who can consent Whether this scope can be consented to by users or if admin consent is required. Select Admins only for higher-privileged permissions. Admins and users Admin consent display name A short description of the scope's purpose that only admins will see.
Read-only access to Employee records
Admin consent description A more detailed description of the permission granted by the scope that only admins will see.
Allow the application to have read-only access to all Employee data.
User consent display name A short description of the scope's purpose. Shown to users only if you set Who can consent to Admins and users.
Read-only access to your Employee records
User consent description A more detailed description of the permission granted by the scope. Shown to users only if you set Who can consent to Admins and users.
Allow the application to have read-only access to your Employee data.
Set the State to Enabled, and then select Add scope.
(Optional) To suppress prompting for consent by users of your app to the scopes you've defined, you can pre-authorize the client application to access your web API. Pre-authorize only those client applications you trust since your users won't have the opportunity to decline consent.
- Under Authorized client applications, select Add a client application
- Enter the Application (client) ID of the client application you want to pre-authorize. For example, that of a web application you've previously registered.
- Under Authorized scopes, select the scopes for which you want to suppress consent prompting, then select Add application.
If you followed this optional step, the client app is now a pre-authorized client app (PCA), and users won't be prompted for their consent when signing in to it.
Add a scope requiring admin consent
Next, add another example scope named
Employees.Write.All that only admins can consent to. Scopes that require admin consent are typically used for providing access to higher-privileged operations, and often by client applications that run as backend services or daemons that don't sign in a user interactively.
To add the
Employees.Write.All example scope, follow the steps in the Add a scope section and specify these values in the Add a scope pane:
|Who can consent||Admins only|
|Admin consent display name||
|Admin consent description||
|User consent display name||None (leave empty)|
|User consent description||None (leave empty)|
Verify the exposed scopes
If you successfully added both example scopes described in the previous sections, they'll appear in the Expose an API pane of your web API's app registration, similar to this image:
As shown in the image, a scope's full string is the concatenation of your web API's Application ID URI and the scope's Scope name.
For example, if your web API's application ID URI is
https://contoso.com/api and the scope name is
Employees.Read.All, the full scope is:
Using the exposed scopes
In the next article in the series, you configure a client app's registration with access to your web API and the scopes you defined by following the steps in this article.
Once a client app registration is granted permission to access your web API, the client can be issued an OAuth 2.0 access token by the Microsoft identity platform. When the client calls the web API, it presents an access token whose scope (
scp) claim is set to the permissions you've specified in the client's app registration.
You can expose additional scopes later as necessary. Consider that your web API can expose multiple scopes associated with several operations. Your resource can control access to the web API at runtime by evaluating the scope (
scp) claim(s) in the OAuth 2.0 access token it receives.
Now that you've exposed your web API by configuring its scopes, configure your client app's registration with permission to access the scopes.