FastTrack for Azure

7 MIN READ

Define and implement permissions, roles and scopes with Azure Active Directory in SaaS solution

Microsoft

May 09, 2023

This article covers 3 main concepts related to authentification & authorization, which can be used by SaaS providers. It will cover Application Roles functionality, Delegated & Application permissions, and Scopes functionality.

But before we dive into the permissions and roles, it is important to understand the difference between 2 different versions of AAD, both of which can be used by software providers, depending on the scenario.

Difference between AAD and AAD B2C

AAD (AAD B2B) enables SaaS providers to extend their software to external users without the need to manage separate identity stores for their customers. By using AAD SaaS providers can define roles and scopes for their applications, without having access to AAD instances of the customers where the end users reside. In this scenario role assignment and permission granting is happening on the customer tenant. It is the administrator of the customer’s tenant who is responsible for assigning the correct permissions and keeping the users, groups, and role assignments for SaaS applications up-to-date.

In contrast, AAD B2C is designed for business-to-consumer (B2C) scenarios, where organizations need to authenticate and manage the identities of their customers (end-users), rather than employees or partners.

AAD B2C is particularly useful when building applications that require user authentication and authorization. It allows organizations to create customized flows, such as sign-up, sign-in, and password reset flows, tailored to their specific needs and branding. Additionally, AAD B2C provides features like social identity providers (like Facebook, Google, etc) and federated identity providers, multi-factor authentication, and identity verification to enhance the security of customer identities.

Delegated & Application permissions

Remember that app, which wants access to your profile, email, and bank account? Right, that is delegated permissions in action!

Delegated permissions and application permissions are two types of permissions used in the context of authentication and authorization in software applications.

Delegated permissions are permissions that are granted by a user to an application, which then allows the application to act on behalf of the user. These permissions are typically granted at runtime and are temporary in nature. Delegated permissions are used to allow an application to access resources or perform actions that the user has permission to access or perform. For example, a user may grant an application permission to read their email or calendar events.

It's worth noting, that delegated permissions for Graph API are not supported in AAD B2C for personal accounts (such as outlook.com, Facebook, Twitter and etc). However, if AAD B2C is configured to use "Work and School accounts", delegated permissions for Graph API are allowed.

Application permissions, on the other hand, are permissions that are granted to an application by an administrator. Application permissions are used to allow an application to perform certain operations or access resources that are not tied to a specific user. For example, an application may be granted permission to read all emails and calendar events for all users in the directory.

The most important thing to remember about app-only access is that the calling app acts on its own behalf and as its own identity. There's no user interaction. If the app has been assigned to a given app role for a resource, then the app has fully unconstrained access to all resources and operations governed by that app role. App role functionality provides a possibility to assign roles to individual apps, for example, we can create 'Reader' or 'Writer' roles and assign them to individual apps (backends, APIs, background workers, etc), similar to how roles can be assigned to individual users.

Both AAD and AAD B2C (including personal accounts) support Application Permissions for Graph API.

In the case of using AAD, for application permissions, it is the administrator of the customer AAD tenant who has to grant required permissions to an application.

In the case of AAD B2C, application permissions are granted in the SaaS provider tenant.

Permissions are built on top of the concept called Scope.

Scopes

Another important aspect for SaaS providers is the use of scopes. Scopes are used to restrict access to data and functionality protected by an API. Custom scopes can be created to provide granular control over what users can access within an application or provide granular permissions to different APIs / microservices.

Scopes can be defined as a collection of permissions that are required to access a particular resource. You can define multiple scopes for different levels of access on APIs and services, registered under App Registrations in AAD:

When a user or application attempts to access a protected resource (for example, emails through Graph API), Graph API will verify that the requested scope is associated with the user or application. This association is passed as part of the JWT access token. If the user or application has the appropriate scope, they will be granted access to the resource.

In the scenario, where the user is using delegated permissions and gives consent to the SaaS app to access email records using Graph API, this SaaS app will only be able to retrieve email items for this user.

If you are granting permission to one of the APIs which are part of the SaaS application, and this API is protected by AAD, you will have to implement similar logic.

Let’s assume that you provide a custom API that allows digital contract signing. In the case of users allowing delegated permissions for the SaaS app to access digital contacts through your API, it should only return contracts for this particular user, and it should also take into consideration the scope – is it only Contract.Read, or also Contract.Sign, which should give users the possibility to sign the contract. It is your responsibility as a SaaS provider to implement the authorization logic in your application.

Tip for naming conventions

You can get inspiration from the naming conventions for scopes and permissions based on the Microsoft Graph API naming convention.

Once the scopes are defined for backed/APIs, the client application can request access to specific scopes when it is calling an API. This is typically done using OAuth2.0, where the application includes the scopes which it needs in the authentication request.

Tip for coding

If you are using .NET for your API development, you can take advantage of the Microsoft.Identity.Web and Microsoft Authentication Library MSAL.NET to sign-in users and obtain a JWT access token through the OAuth 2.0 protocol, make sure that users have appropriate scopes or application roles when calling protected APIs.

This sample can serve as an example of how to implement custom scopes and permissions for an API protected with AAD.

Tip for security

A Privileged Administrator can configure whether non-administrator users are allowed to grant user consent to an application. This setting can take into account aspects of the application and the application's publisher, and the permissions being requested.

As an administrator, you can choose whether user consent is allowed. If you choose to allow user consent, you can also choose what conditions must be met before an application can be consented to by a user, in order to prevent users from giving access to, let’s say, their emails to malicious client applications.

Concluding on the scope topic, it is possible in both AAD and AAD B2C to create custom scopes for protected API, for Delegated and Application permissions.

App Roles

One of the key features of AAD for SaaS providers is the ability to define app roles, and later assign app roles to individual users and groups. App roles are used to control access to various resources and actions within an application. For example, an application may have the role of "admin" which allows users with that role to access certain features and functionality that regular users cannot. You can create any kind of role and name it based on business needs.

How to start using roles?

In AAD, app roles can be created via the Azure portal under “Application Registrations” in the tenant of the SaaS developer.

Administrators of customer tenants can assign these roles to users or groups. That is done under “Enterprise Applications”:

After that, App roles will be included in the access token (JSON Web Tokens (JWTs)) issued by AAD, so applications can easily read and use them to control access to resources. If you decode the access token, you will be able to see that it contains 'Roles' claim.

In AAD, app roles are supported through the permissions Directory.ReadWrite.All, which in AAD B2B are available as delegated permissions, but in AAD B2C are not available as delegated permissions for personal Microsoft accounts, and are only available through Application Permissions.

In AAD B2C, app roles must be enabled through the application's manifest. App roles cannot be enabled through Azure Portal like in AAD B2B:

In AAD B2C it is not possible to receive 'Roles' claim as part of the access token like it is received in AAD.

Once enabled in AAD B2C, the backend of the SaaS application can use the dedicated Graph API call (with Application Permissions) to retrieve role information for a specific user.

https://graph.microsoft.com/v1.0/users/<userID>/appRoleAssignments

App roles can be assigned to users programmatically using the Microsoft Graph API in both AAD and AAD B2C.

To do this, you can use the Microsoft Graph API endpoint:

POST /users/{id}/appRoleAssignments

Where {id} is the ID of the user you want to assign the app role to.

The request body should include the appRoleId and the resourceId. The appRoleId specifies the ID of the app role that you want to assign, and the resourceId specifies the ID of the resource that the user is being assigned the role.

Conclusion

It is worth noting that while AAD and AAD B2C have some differences in how they handle app roles and scopes, both versions of AAD provide robust identity and access management capabilities. Organizations can choose the version that best meets their needs based on factors such as the types of resources they need to manage and the level of control they require over user access.

In conclusion, app roles and scopes are important features of AAD that help organizations control user access to resources within applications.