In this post, I explain how to use App Role for Azure AD App Role to secure your C# Web API.
This is an official document which explains app role in general.
If you already have Azure AD to register your app, you can use it, otherwise create new one.
You can add several users for test.
Once you provision Azure AD, register an application for the WebAPI.
1. Go to Azure AD resource and select "App registrations". Click "New registration".
2. Enter any Name click "Register" with default settings.
3. Take a note for "Application (client) ID" and "Directory (tenant) ID"
Let's create web api project by using registered application information. I use .NET 5 in this example.
1. Create web api project. Replace name, client/tenant Ids and domain name to your own.
dotnet new webapi --name mywebapi --auth SingleOrg --client-id 957d4202-5e73-47d9-9fcf-554112c3746c --tenant-id 92b10440-c6cc-4cb3-97e1-7ff05bc6bc8e --domain kenakamutestad.onmicrosoft.com
2. Open created project via any IDE. I use Visual Studio 2019. Confirm appsettings.json has correct information about the registered application.
3. Also open Startup.cs to confirm Azure AD auth is setup.
4. Hit F5 to make sure it runs as expected.
5. Check the URI. In my case, I use port 44384 for my localhost.
Now it's time to update registered application.
1. Go back to the registered application and select "Authentication". Click "Add a platform" to configure web authentication.
2. Select "Web".
3. Enter Redirect Uri by using localhost address followed by "/signin-oidc". Click "Configure".
4. Next, go to "Expose an API" and click "Add a scope".
5. Click "Save and continue" without changing Application ID URI.
6. Create scope like below. "access_as_user" is expected default scope name. Click "Add scope". You can check it by running
dotnet new webapi -h and check --default-scope parameter.
This scope is also hard-coded in "WeatherForecastController.cs" and use
You just updated authentication method as well as a scope for the application.
You need endpoints information later on.
1. Select overview and click "Endpoints".
2. Take a note for "OAuth 2.0 authorization endpoint (V2)" and "OAuth 2.0 token endpoint (V2)".
1. Select "Certificates & secrets". Click "New client secret".
2. Create a secret and take a note for Value.
In this application, I use two application roles, "Admin" and "User".
1. Click "App roles" and click "Create app role".
2. Enter "Admin" as display name and value. Click "Apply".
3. Repeat the steps to create User role as well.
Although it's not mandatory, it's recommended to use Azure AD security group to manage users. So, let's create corresponding groups.
1. Go back to Azure AD portal and select "Groups". Click "New group".
2. Enter any name to the group and make yourself as owners. You can add members now or later.
3. Repeat the steps to create user groups.
There is no mappings between App role and security group yet, so let's configure it. We can do so via "Enterprise application" menu.
1. Go back to Azure AD portal and select "Enterprise applications". Search for the registered application and select it.
2. Go to "Users and groups". Click "Add user/group". This menu let us create a mapping between app role and user/group.
If you see warning like below, you can upgrade your Azure AD plan to Azure AD P2, or you can simply assign each user to role.
I upgraded my Azure AD plan from free to P2 free trial.
3. Select created security group and role for Admin. Click "Assign".
4. Repeat the steps for User role.
Finally, we can use the role in Web API.
1. Go back to web api solution and open "WeatherForecastController". Update "Authorize" attribute to include role name.
Time to test the configuration.
1. Run the web api by hitting F5.
2. Open Postman and select "Authorization" tab. Select "OAuth 2.0" from drop down.
3. Enter following information.
- Callback URL: https://localhost:44384//signin-oidc (change port to match your configuration)
- Auth URL: The one you confirm in the endpoint for authorization.
- Access Token URL: The one you confirm in the endpoint for token.
- Client ID: The client Id of the registered application.
- Client secret: The one you created for the registered application.
- Scope: The one you created for the registered application in Exposer API section. It should looks like "api://957d4202-5e73-47d9-9fcf-554112c3746c/access_as_user"
4. Click "Get new access token" and complete the sign-in process. Use a user who belongs to Admin role.
5. Once you obtain the token, click "Use Token".
6. Enter the WeatherForcast api address and hit "Send". You should see the result. If you use different user who doesn't belong to "Admin" role, then you will get an error.
You can also parse JWT in the web service like https://jwt.io/. Do so with your own risk please. I can see that my token contains "Admin" role and "access_as_user" as expected.
It's a bit tricky that you need to use both "app registration" as well as "Enterprise application" menus to configure App role, but I hope you get some idea.