The following posts are part of this series:

Let’s begin

I’m not going to cover the steps involved in creating an app registration. This is covered, in detail, in the Microsoft documentation. In this article though, I want to point out some important things.

Token versions

The platform enables the generation of two token verions, v1.0 and v2.0. The tokens generated by the platform look very similar but the difference in versions determines what claims are included.

At a high level, v1.0 tokens are for Azure AD only applications, while v2.0 tokens can be used to support both Azure AD and consumer accounts such as Facebook and Twitter.

Configuring the type of tokens accepted can be configured using the app manifest and by setting the accessTokenAcceptedVersion setting. Values of null and 1 result in v1.0 tokens, and 2 results in v2.0 tokens.

You can use JWT.ms to view both v1.0 and v2.0 tokens as examples. If you change the token version in the app manifest, don’t forget to click Save.

Additional configuration

When you create app registrations for client applications, you will use a different set of configuration values, than when creating for a Web API. Here is a summary of those.

  • Web APIs do not need a redirect URI as no user is signed in interactively.
  • Exposed API is not required as other settings determine the app scopes and app roles.

App ID URI and scopes

Scopes are defined in the format of resource/scope. Scopes have shortcuts as well, such as in the Microsoft Graph, where User.Read is the same as https://graph.microsoft.com/user.read.

In order to add scopes to your own Web API app registration. Select Expose an API in the application registration.

  1. Select Add a scope.
  2. If prompted, accept the proposed application ID URI (api://{clientId}) by selecting Save and Continue.
  3. Specify these values:
    * Select Scope name and enter access_as_user.
    * Select Who can consent and make sure Admins and users is selected.
    * Select Admin consent display name and enter Access TodoListService as a user.
    * Select Admin consent description and enter Accesses the TodoListService web API as a user.
    * Select User consent display name and enter Access TodoListService as a user.
    * Select User consent description and enter Accesses the TodoListService web API as a user.
    * Keep the State value set to Enabled.
  4. Select Add scope.

Scopes also appear on the consent window that’s presented to users of your app. Therefore, provide the corresponding strings that describe the scope:

  • As seen by a user.
  • As seen by a tenant admin, who can grant admin consent.

Summary

So far, we have learned the basics of app registrations for Web API apps and looked at scopes and how to create them. In the next post, we look at how to configure your code to use the Microsoft Identity Platform, as well as protect your API endpoints and validate scopes.