andrea-chiarelli

I have over 20 years of experience as a software engineer and technical author. Throughout my career, I've used several programming languages and technologies for the projects I was involved in, ranging from C# to JavaScript, ASP.NET to Node.js, Angular to React, SOAP to REST APIs, etc.

In the last few years, I've been focusing on simplifying the developer experience with Identity and related topics, especially in the .NET ecosystem.

Principal Developer Advocate

Andrea Chiarelli

What is the difference between permissions, privileges, and scopes in the authorization context? Let's find out together.

Access control is a complex thing. It involves users, resources, and applications, and you have to set it up properly to prevent bad surprises. However, setting up access control is not just a matter of writing code or configuring a system. It includes (or better, it relies on) understanding a few basic concepts. Things can get even more complicated when delegated authorization comes into the picture, such as when using OAuth.

In this context, three core concepts are usually misunderstood and confused: **permissions**, **privileges**, and **scopes**. Let's try to go to the basics to better understand these concepts and their relationship.

By the way, here is a video version of this article:

<AmpContent>
<amp-youtube
    data-videoid="z2Ma0ZsEF7Y"
    layout="responsive"
    width="480" height="270">
</amp-youtube>
</AmpContent>

<NonAmpContent>
<div
  class='embed-container'
  style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%;margin-bottom:40px;">
    <iframe
      style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
      src='https://www.youtube.com/embed/z2Ma0ZsEF7Y'
      frameborder='0' allowfullscreen>
    </iframe>
</div>
</NonAmpContent>

## Actors of Access Control

Consider a scenario with the following actors:

- The **user**, the entity that wants to perform an action on an object.
- The **resource**, the object that a user wants to use.
- The **application**, the software that mediates the interaction between the user and the resource.

In this scenario, **access control is the selective restriction of access to a resource**. It determines who can do what on a resource. The relationship between the three actors described above contributes to the complexity of access control, as we will see in a moment.

## What Are Permissions?

Usually, you have a clear understanding of what a permission is. Commonly, you say that you have the permission to drive your car, load stuff in its trunk compartment, inspect its hood, clean it, sell it, and so on.

These common activities make you think that a permission is something related to you, the user. Actually, in the computer security context, a permission is something related to an object, to a resource, not to the user of that resource.

**A permission is a declaration of an action that can be executed on a resource**. It describes intrinsic properties of resources, which exist independently of the user. In the scenarios depicted above, driving and filling the trunk are actions you can do with your car: they are permissions attached to your car. The same happens with the action of accessing your computer, reading your emails, and so on. They all are permissions on those resources.

I know, that looks weird and a bit pedantic, even philosophical in some ways. But it is fundamental to accurately define this concept to understand the rest.

## What Are Privileges?

If permissions are bound to the resource, how can you express the ability to perform an action on that resource? How can you express the fact that someone is authorized to drive their car? What you need are privileges.

Simply put, **privileges are assigned permissions**. When you assign a permission to a user, you are granting them a privilege. If you assign a user the permission to read a document, you are granting them the privilege to read that document. Do you see the subtle difference?

I know. Usually, permissions and privileges are used interchangeably, but technically they have precise and different meanings in the context of computer security.

So, resources expose permissions. Users have privileges.

> For simplicity, we'll talk about privileges assigned to users, but keep in mind that privileges can also be assigned to applications. Consider, for example, an application running without user involvement that needs to access a resource.

## Authorization Scenarios

Once you understand the exact definition of permissions and privileges, we can easily talk about authorization scenarios. I mean, you can easily imagine a scenario where an entity protects a resource, and a user wants to exercise their privilege to use that resource. **The entity that protects the resource is responsible for restricting access to it, i.e., it is doing access control**.

Consider the following example. The concierge of a hotel is the entity that supervises the hotel's rooms (the resources) from unauthorized access. Each room has the ability to accommodate one guest (permission). A customer is assigned one room, so they have the privilege of being accommodated in that room. When the customer goes for a walk and then comes back to the hotel, the concierge checks if actually the customer has been assigned the permission to be accommodated in that room by consulting the booking list. If everything fits, the customer can come in, and we're all happy.

Imagine that one day, while the customer is out, a person shows up at the concierge desk. That person says they were requested by the customer to come into the room to get their briefcase. The concierge doesn't allow them to come in, of course. They need to do their own verifications to confirms what that person is asserting, such as calling the customer on the phone, for example.

However, even after everything is clear, the concierge needs to make sure that person will only do what they came to the hotel to do: take the customer's briefcase. Nothing else. The concierge will likely walk the person to the customer's room and make sure nothing else is done other than what was agreed upon.

The first scenario looks quite straightforward: it reduces the access control to comparing the customer booking data with the hotel's booking list. The second scenario is a bit more complex: it requires an additional check on what the person declares and control on what they are allowed to do.

These two scenarios may seem fictitious, but they have equivalent scenarios in authorization systems. The first scenario corresponds to the situation where a user attempts to access a protected resource for which they have privileges. This is the typical and most known authorization scenario.

The second scenario represents the case in which a third-party application wants to access a protected resource on behalf of a user. This case is known as a delegated authorization scenario.

The delegated authorization scenario is the typical scenario introduced by the [OAuth 2 Authorization Framework](https://auth0.com/docs/protocols/protocol-oauth2). This framework allows a third-party application to operate on a resource on behalf of a user. In other words, the application exercises the user's privilege to use a resource. But how does it happen? How can the application be delegated to access the user’s resource? Here, scopes come into the scene.

## What Are Scopes?

**Scopes enable a mechanism to define what an application can do on behalf of the user**. Recalling the hotel example, taking the customer's briefcase is the scope of the person who introduced themselves to the concierge.

The application requests these scopes to the authorization server, i.e., the server responsible for authorizing the third-party application in the delegated scenario. [Scopes were introduced in OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) and are specific to that authorization framework.

In practical terms, **scopes are strings that represent what the application wants to do on behalf of the user**, as shown in the following authorization request example:

```bash
https://YOUR_DOMAIN/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://YOUR_APP/callback& 
  scope=read:email&   #👈 here is the requested scope
  audience=YOUR_API_AUDIENCE&
  state=YOUR_STATE_VALUE
```

Typically, scopes are permissions of a resource that the application wants to exercise on behalf of the user. In other words, the application wants to exercise user's privileges on a resource such as reading their emails.

Actually, it is not the authorization server that allows the application to exercise the user's privileges. The final word on granting delegated access to the application is the user's own. The user can approve or reject delegated access to their resource with specific scopes by using a consent screen similar to the following:

![Consent screen](https://images.ctfassets.net/23aumh6u8s0i/1TrkMwEcKSR149zd878WEJ/8ae011dc08b89698c0dce24e8ce01e43/consent-screen.png)

You can experience it firsthand by <a href="https://a0.to/blog_signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">signing up for Auth0</a> and securing an application built with [several supported technologies](https://auth0.com/docs/libraries).

The granted scopes allow the application to access only the user's resources, say the user's emails. Just as the user cannot access other users' emails, the application cannot access other users' emails either. Usually, **the scopes granted to a third-party application are a subset of the permissions granted to the user**.

Keep in mind, however, that an application can request scopes corresponding to privileges that the user doesn't have. And the user can grant them. This may look tricky, but it covers situations where the user doesn't have a given privilege in the moment they grant the scopes to the application, but they will have that privilege when the application exercises that scope. The vice versa can happen too: a user has a given privilege and grants a delegated access for the corresponding scope, but the user loses the privilege when the application tries to exercise its scope. At the end of the day, what is relevant when the application exercises its scopes is the possession of the corresponding privileges by the user at that time. This means that **the application can't do more than the user can do**.

Once the user approves the application's request, the authorization server communicates the granted scopes to the application so that it can access the resource with the limited granted privileges.

## A Complicated Relationship

Now you have a clearer picture of what permissions, privileges, and scopes are. Unfortunately, this may not be enough. In fact, these items are strictly related, and often this relationship gets confusing. Let's try to clarify the most common misunderstandings.

### Scopes and privileges

Often, developers think that scopes are application's privileges. After all, the user granted their consent to use them. However, they usually miss a little detail: applications are authorized to exercise those privileges **on behalf of the user**. If the user doesn't have a privilege, the application cannot exercise it.

This means that, on the resource side, **users' privileges must be checked even in the presence of granted scopes**. Remember that, in a delegated authorization scenario, the application may act on behalf of the user even when the user is not logged in. If the user no longer has those privileges between their consent and the exercise by the application, the application must be prevented from exercising its delegated access. This should clarify why **scopes should not be considered application's privileges**.

These may look like philosophical issues, but they have practical implications. Check out [this article on the nature of scopes](https://auth0.com/blog/on-the-nature-of-oauth2-scopes/) to learn more about this.

### Scopes and permissions

Once you know what permissions, privileges, and scopes are, you might assume that there is a natural mapping between permissions and scopes. In other words, if a resource has permissions A and B, the scopes X and Y respectively will exist to allow an application to exercise those permissions on the resource and vice versa. While in most cases permissions are exposed as scopes, this mapping is not strictly correct for a few reasons.

In a delegated scenario, not all the permissions on a resource should necessarily be made available to be requested as scopes. You could reserve some permissions for the user and decide that they are not delegable. For example, you could decide that the permission to delete a document is never delegated to a third-party application.

So you might think that this supposed mapping is not between scopes and permissions but between scopes and privileges. This way, you can't map a scope to a permission not assigned to the user. Actually, this is not accurate either. There are scopes that don't have a match among the resource's permissions or the user's privileges. Consider the `openid` scope defined by [OpenID Connect specifications](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). This scope does not correspond to any permission on a specific user's resource. It is a request for the authorization server to return an ID token as the result of the user's authentication. The same applies to the other [scopes defined by OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims): `profile`, `email`, `address`, and `phone`.

So, you should avoid this unconscious mapping between scopes and permissions.

## Summary

At the end of this journey, you learned the subtle differences between permissions, privileges, and scopes and their mutual relationship. Understanding these concepts and their thin borders will help you build more secure applications. The following picture tries to summarize what you learned in this article:

![Permissions, privileges and scopes](https://images.ctfassets.net/23aumh6u8s0i/2wSDOXUzAKuCAA0rw79Fx8/8f66ad24881e3da2a73249a2a7b05e27/permissions-privileges-scopes.jpg)


Permissions, Privileges, and Scopes

A quick tour about five C# features that even experienced developers might not know: from variable scopes to the top-level statements and others.



Even if you are an experienced C# developer, there are features you might not be aware of. In this article, you will explore five little-known C# features that allow you to accomplish things in a slightly different way than you are used to. These features allow you to declare local variables in an unusual way, create conditions with the `switch` command and the `try/catch` block, reduce the number of lines to set up a console program, define properties that can only be initialized, and access private variables of a class instance.

Let's get started.

## Variable Scope and Braces

In C#, you can declare variables within code blocks surrounded by braces to define methods, conditional statements, loops, among others. For example, the braces define a variable scope within a method:

``` csharp  
static void Main(string[] args)
{
  Console.Write("Enter your name: ");
  var name = Console.ReadLine();

  Console.WriteLine($"Hello, {name}!");
}
```

Also, you can define a variable scope with an `if` statement:

``` csharp  
if (name.Trim() != "")
{
  var dayOfWeek = DateTime.Today.ToString("dddd");
  Console.WriteLine($"Happy {dayOfWeek}, {name}!");
}
```

And with a `while` statement as well:

``` csharp  
while (name.Trim() != "")
{
  var dayOfWeek = DateTime.Today.ToString("dddd");
  Console.WriteLine($"Happy {dayOfWeek}, {name}!");

  Console.Write("Enter your name: ");
  name = Console.ReadLine();
}
```

Regardless of the context, the braces delimit the scope of the variable. Did you know that **you can define a variable scope with braces even without a specific statement**? Consider the following code:

``` csharp 
using System;

namespace variable_scope
{
  class Program  {
    static void Main(string[] args)
    {
      Console.WriteLine("Hello World!");
      {
        var theVariable = "I'm the variable";
        Console.WriteLine(theVariable);
      }
    }
  }
}
```

Here, we have a code block delimited by braces inside the `Main()` method. The code block defines and initializes the variable `theVariable` and writes its value to the console. Notice that no `if`, `while`, `for`, or any other statement stands right before the braces.
This program works as expected: it will write both strings as shown below:

``` bash 
Hello World!
I'm the variable
```

What happens if we add the following statement outside the code block, as in the following example?

``` csharp 
using System;

namespace variable_scope
{
  class Program  {
    static void Main(string[] args)
    {
      Console.WriteLine("Hello World!");
      {
        var theVariable = "I'm the variable";
        Console.WriteLine(theVariable);
      }
      //👇 new statement outside the code block
      Console.WriteLine(theVariable);
    }
  }
}
```

If you attempt to run this program, you will get the following error:

``` bash 
error CS0103: The name 'theVariable' does not exist in the current context
```

As you can see, the variable defined inside the code block is not accessible outside it.

In other words, you can create a variable scope by simply using braces anywhere in your code. This feature may be useful when you have a short sequence of statements that need to share a value through a variable. You create a code block on the fly, declare the variable, and use it.
However, I suggest not to abuse it. Sometimes, it's a better idea to create a method and invoke it. It may be more readable than a code block.

## The *when* keyword

Another little-known C# feature is the `when` keyword. You can use it to apply a filter condition in the context of a `switch` statement or a `try/catch` block.
Let’s start by seeing how to use it in the context of a `switch` statement. Consider the following code:

``` csharp  
private static string evaluateScore(int score)
{
  var result = "";

  switch (score)
  {
    case int n when (n < 6):
      result = "Your score doesn't look good...";
      break;

    case int n when (n >= 6 && n <= 7):
      result = "Your score is not bad!";
      break;
    
    case int n when (n > 7 && n <= 9):
      result = "Your score is pretty good!";
      break;
    
    case int n when (n > 9):
      result = "Your score is awesome!";
      break;
  }

  return result;
}
```

Here we have the `evaluateScore()` method that evaluates an integer value (`score`) and returns a message string. As you can see, its logic is totally based on a `switch` statement. Each `case` declares a variable `n` that takes the current value of the `score` parameter. This variable is inspected in the `when` clause to determine the message to be returned. Of course, you can use any boolean expression with the `when` clause.

You can also use the `when` keyword with `catch`, as shown in this example:

``` csharp  
public static async Task<string> MakeRequest()
{
  var client = new System.Net.Http.HttpClient();
  var streamTask = client.GetStringAsync("https://auth0.com/this-page-doesnt-exist");

  try
  {
    var responseText = await streamTask;
    return responseText;
  }
  catch (HttpRequestException e) when (e.StatusCode == HttpStatusCode.MovedPermanently)
  {
    return "The page moved.";
  }
  catch (HttpRequestException e) when (e.StatusCode == HttpStatusCode.NotFound)
  {
    return "The page was not found";
  }
  catch (HttpRequestException e)
  {
    return e.Message;
  }
}
```

Here, you catch an `HttpRequestException` and analyze its status code through a `when` clause.

In both cases, the `when` keyword is extremely useful when you need to match a complex condition since it allows you to keep your code pretty readable.

## Top-Level Statements

Typically, a minimal console application has at least the following code:

``` csharp  
using System;

namespace standard_console
{
  class Program
  {
    static void Main(string[] args)
    {
      Console.WriteLine("Hello World!");
    }
  }
}
```

This program is composed of eleven lines of code, but only one line is actually operative. All the other lines are needed to set up the program infrastructure: a namespace, a class, and a method.

Do you know that you can get rid of this stuff and focus on just one line? In fact, you can replace the code shown above with just the following:

``` csharp 
System.Console.WriteLine("Hello World!");
```

This is possible thanks to the top-level statement feature introduced by C# 9. You can try it [starting with .NET 5](https://auth0.com/blog/dotnet-5-whats-new/).

Of course, you can use multiple top-level statements to create your console application, as in this example.

``` csharp  
using System;

Console.Write("Enter your name: ");
var userName = Console.ReadLine();

Console.WriteLine($"Hello {userName}!");
```

However, remember that you can have only one file using this feature in your .NET project.

Using the top-level statements feature enables a script-oriented approach for C# programming. This may be a more friendly approach for new C# learners or a handy alternative to quickly set up a small console application. For complex applications, you may feel the top-level statements approach is inappropriate because of the lack of a structure.

## The *init* Setter

Assume you have the following `Person` class:

``` csharp  
public class Person
{
  public string FirstName { get; set; }
  public string LastName { get; set; }
  public string Address { get; set; }
}
```

It's a very simple class with just `FirstName`, `LastName`, and `Address` properties. As it *usually* happens in the real world, once you assign a first name and last name to a person, you do not want anyone to change it anymore. So, you would like to assign the values for the `FirstName` and the `LastName` properties to a `Person` instance at the creation time, and those values should not be changed anymore. How can you accomplish this behavior?
If you define the `Person` class by using the usual `get` and `set` accessors, you will not be able to get the expected result. After creating an instance of the `Person` class, you can change the value of its `FirstName` and `LastName` properties whenever you want, as in the following example:

``` csharp  
var person = new Person
{
  FirstName = "John",
  LastName = "Doe",
  Address = "124 Conch Street, Bikini Bottom, Pacific Ocean"
};

person.Address = "17 Cherry Tree Lane";
person.FirstName = "Jack";

Console.WriteLine($"Hello {person.FirstName} {person.LastName}!");
```

Fortunately, C# 9 provides you with the `init` accessor. If you apply the `init` accessor to the `FirstName` and `LastName` properties in place of `set`, you will achieve your goal:

``` csharp  
public class Person
{
  public string FirstName { get; init; }  //👈 changed code
  public string LastName { get; init; }   //👈 changed code
  public string Address { get; set; }
}
```

This way, after the instance is created, the `FirstName` and `LastName` properties become read-only.
Remember that this feature is supported only starting with C# 9.

## Accessing Private Variables

Of course, you know that a private variable is not accessible from outside a class. In the following example, you have a `Life` class that defines the `birthTime` private variable:

``` csharp  
public class Life
{
  private DateTime birthTime;

  public Life()
  {
    birthTime = DateTime.Now;
  }

  public int GetLength()
  {
    return DateTime.Now.Subtract(birthTime).Milliseconds;
  }
}
```

The `birthTime` private variable is assigned in the class constructor and is used within the `GetLength()` method. Normally, the `birthTime` variable is not accessible from outside the `Life` class. However, there is a special case where you can access the `birthTime` private variable. Take a look at this new `YoungerThan()` method:

``` csharp  
public class Life
{
  // ...other code...

  public bool YoungerThan(Life livingBeing)
  {
    return livingBeing.birthTime < birthTime;
  }
}
```

Within this new method, you are actually accessing the `birthTime` private variable of a `Life` instance!

You may be scared by the consequences of accessing a private variable. Don’t panic! Only instances of a class can access private variables of other instances of the same class. In other words, the context of this access possibility is limited to one specific class.

This feature is useful when you need to implement some sort of internal comparison methods like the one shown above. However, you should use this approach **only when you don't want to expose a private value**. Otherwise, you should expose the private variable through a public property or method and use it for any processing. This way, you keep the idiomatic Object-Oriented Programming approach.

## Summary

In this article, you discovered five C# features that maybe you didn't know. The C# language and [the .NET platform](https://auth0.com/blog/what-is-dotnet-platform-overview/) are growing and evolving very quickly to adapt to developers' needs and simplify their work. So there's nothing bad with missing some feature.

If you know other little-known C# features, please share them with us in the comments below.

<include src="asides/DotNetCore" />


Five C# Features You Might Not Know

Vittorio

Vittorio Bertocci is a Principal Architect for Auth0. Before Auth0, he had a lengthy career with Microsoft, where Vittorio worked with Fortune 100 and Global 100 companies, including working on Microsoft’s Azure Active Directory team as principal program manager focusing on the developer experience. He contributed to the inception and launch of Microsoft's claims-based platform components (Windows Identity Foundation and ADFS, ADAL and MSAL SDKs, ASP.NET middleware). Vittorio is a well known speaker, educator and published author.

Principal Architect

Vittorio Bertocci

Stretching OAuth2 scopes beyond intended usage leads to trouble in complex architectures.



**TL;DR:** Scopes only come into play in delegation scenarios, and always limit what an app can do on behalf of a user: a scope cannot allow an application to do more than what the user can do.

Although stretching scopes beyond that usage is possible, it isn’t trivial or natural – contrary to what common naïve narratives would want you to believe.

<include src="TweetQuote" quoteText=".@vibronet on why using OAuth2 scopes in every authorization scenario is not a good idea."/>

## The Problem

OAuth2 scopes are misunderstood. Developers are victim of the “man with a hammer” syndrome here — **scopes are the only primitive defined in OAuth2 that has something to do with authorization, and as a result people use them in every authorization scenario** — even the ones for which they weren’t conceived. Just like Newtonian laws are enough to tackle simple problems, the same can be said for those naïve uses of scopes — but as soon as architectures get more complicated, people discover (often painfully) that they need to rethink things in quantum terms to get out of trouble.

It certainly doesn’t help that protocol specs aren’t too prescriptive on this point — a common ailment in OAuth2 — but a deeper read usually helps to clarify things. Circumstantial evidence/spec intent and context on one side, “laws of physics” on the other leave little room for interpretation.

Let me stress: most misunderstandings I discuss here come from legitimate authorization requirements; scopes just happen to be the wrong artifact to carry them. If anything, this points to the need for more prescriptive guidance on the matter (for a primer, see [Jared Hanson’s session at Identiverse](https://www.youtube.com/watch?v=eEI4ShHPh-8)).

Here’s an extra note to clarify further what I am trying to do here, given that I expect some people will push back hard when their beliefs are challenged.

Like everything that doesn’t really exist in ground reality, **the semantic of scopes is entirely in our head**: a consensual hallucination where we all agree on the meaning of the term — hence formally you are free to refuse the entire premise of this post and use “scope” to mean whatever you like. The main selection criteria I am using here is, what’s the choice of meaning that will be best conducive of us “thinking good thoughts,” as in taking decisions that will make our solutions work reliably? That’s a terribly relative, very arbitrary thing to establish — one that doesn’t scale linearly. Heuristic for prime numbers is super handy and we could embrace it, but if we need to work beyond a certain number it will stop working: our intended range determines whether the heuristic takes care of our needs, or it’s a dangerous oversimplification that will force us to backtrack and rip out a lot of logic in the process. Same with scopes: we can hold on to simplified views and revel in their apparent neatness, and feel the burn when we go beyond trivial cases and start having to architect serious shit.

## Scopes Inception

To all intents and purposes, scopes didn’t really exist before OAuth. The quintessential use case OAuth was devised for is a simple scenario, which has been presented ad nauseam already. LinkedIn asks for your Gmail password so it can use it to log in as you in Gmail, programmatically harvest your contacts (via API/scraping/etc) and spread itself; but knowledge of your Gmail password allows LinkedIn to do far more than that (e.g. sending mails on your behalf, read your messages, etc) and put the secrecy of your credentials at risk.

OAuth shows up, devises a mechanism for LinkedIn to ask Gmail just for the action it requires (access contacts) and nothing else — and makes all this possible without ever sharing with LinkedIn your gmail credentials. Done. Scopes happen to be the primitive that OAuth2 introduced for allowing LinkedIn to request delegated access to your Gmail’s contacts, to the exclusion of everything else. Intent clear and mission accomplished, right?

To me, that would be enough to demonstrate my thesis (scopes only come into play in delegation scenarios, and always limit what an app can do on behalf of a user; they are not meant to grant the application permissions outside of the privileges the delegated user already possesses). However, I know that this scenario alone won’t be enough to convince everyone: a classic objection is “fine, that might have been the original intent, but that doesn’t mean that they can’t be successfully used for more scenarios!.” Fair. Let’s dig deeper and explore more ramifications.

<include src="TweetQuote" quoteText="Scopes only come into play in delegation scenarios, and always limit what an app can do on behalf of a user."/>

## Scopes as Claims

What I described so far is all about using scopes for asking for permissions. **OAuth2 says nothing about scopes being claims in access tokens**, given that access tokens (ATs from now on) don’t need to carry claims at all (ATs are shapeless, per OAuth — and per OpenId Connect as well: only id_tokens are defined as JWTs). Nonetheless, the belief that scopes can be used to express authorization beyond delegated scenarios is deeply entrenched in the assumption that scopes do travel in the access token in form of claims. More precisely, the essence of the problem lies the conviction that **the presence of a scope claim in an access token invests the bearer with its corresponding permission, and that a resource (API, etc) being invoked with such a token can/should grant the corresponding access level without any further check**. It is pretty easy to show that in the general case, that logic wouldn’t work.

To set up our counterfactual, let’s entertain the notion that we are indeed using ATs in a specific format (JWT) carrying scope claims. Here there’s a corollary of the thesis: in the general case, scopes alone in an access token are not enough to carry on authorization decisions. Stealing my own thunder, I’ll tell you the two reasons why that’s the case: 1) the resource visible at the OAuth level isn’t usually the real resource requiring authorization, and 2) the authorization server isn’t omniscient. Let me unpack this through examples: I’ll use Azure AD because the Microsoft Graph is a really good example of this phenomenon.

## The OAuth2 Resource Isn’t The Real Resource

Say that I want my web app to call an API to list all the email messages of the currently signed in user. I request an AT for invoking the Microsoft Graph, and I request the scope **Mail.Read**. Once I get it, I make my web app call **me/messages**, and get a nice list of emails. All is good.
Now, let me make a small change to the call syntax. Instead of me/messages, I’ll call **users/guid/messages**. Still works, awesome! No surprise there.

Here’s the twist. Let me repeat that call, this time asking for the messages for another user. I don’t think anyone would be surprised to see the request result in a 400. And yet, my AT carried the **Mail.Read** scope! The point here is that **the scope is only saying to the authorization server (AS) what the app can do on the user A’s behalf**, which means that the app can list messages just like user A would, but cannot list messages for user B regardless of the presence **Mail.Read** scope. In other words, **Mail** in **Mail.Read** is a resource type, a family of resources — not a specific instance of inbox. But at access time, the specific inbox being requested does matter. Intuitive, right? If the API behavior would be any different we would be in serious trouble. Figure 1 provides a visual summary of the scenario.

![OAuth2 Scopes Mail API exmaple](https://images.ctfassets.net/23aumh6u8s0i/1fcJ0pv60sB1eWrQm9w7KX/8d076bb0f3982735272e00616af27388/oauth2-scopes-mail-api)

_Figure 1: A token carrying the scope Mail.Read indicates that the app can gain delegated access to the user’s mailbox. That scope doesn’t grant to the app privileges that the user doesn’t have: attempts to access another user’s mailbox will fail._

This is an example of 1). The resource we are asking a token for is an API offering a façade for multiple, more granular resources — with their own lifecycle, permissions, privileges and authorization rules. The scope in this scenario is not expressing one of those finer-grained, “ground reality” resources. The true resources in this example are really the inboxes of each user, and that was carried by the REST call rather than the token used to secure it… and the authorization decision emerged from combining the scope **Mail.Read** (without which we wouldn’t have bothered doing anything else), the identifier of the user (carried through a different claim in the token) and the entity requested (in the URL of the entity, hence in the actual call).

But the solution is simple, then! Let’s just describe those sub-level resources at the OAuth2 level, let’s surface the true resource in the protocol — so that scopes can finally express actual privileges. That is sometimes possible, if the resources you are exposing are ultra-simple, which usually means they don’t exist outside of your API. In term of “thinking good thoughts,” I am still somewhat against that. The fact that you might concoct cases where scopes express authorization directives context-free doesn’t make the aforementioned context-dependent scope uses disappear: if your access control logic now assumes scopes to be of the context-free kind (and more importantly, if you/your developers now understand scopes in those terms), your access checks will be too permissive when you do receive classic delegated scopes as you’ll take the permissions in the incoming scopes as directives, without making the further contextual checks they require (“Sure, he got mail.read — but does he own this inbox?”).

However, that’s not the biggest problem with using scopes to represent granted permissions (as opposed to delegated ones). The biggest challenge derives from the fact that permissions are always resource specific, and that transfers a lot of complexity to the AS and the tokens it issues. Resources can be very numerous, leading to A LOT more token requests than in the general case; they can have heavily decentralized life cycles, which makes it hard for the AS to know enough about assigned permissions (or learn about it in timely fashion) to be able to express that as claims; and permissions on an individual resource can be numerous and/or verbose, leading to unmanageably large tokens.

To make things more concrete, think of the case in which the resources being accessed are documents in some repository. According to the naïve view I sketched earlier, we can turn scopes from a delegated hint (which requires the resource to intersect the delegated permission in the scope, with the actual user privileges on lower-level resource being requested to obtain the effective permissions reflected in the access control logic) to an actual assigned privilege (the sheer presence of the scope is all the resource need to grant access, without checking anything elsewhere) just by directly expressing the document itself in our token request, rather than a generic API for accessing documents in the repository. The scenario is on display in Figure 2.

![OAuth2 Scopes assigned privilege example](https://images.ctfassets.net/23aumh6u8s0i/iZG02a9fyVSgvSZF08yFc/fcbcbd01ab22dd2402556d45c43d64fd/oauth2-scopes-doc-api)

_Figure 2: it is possible to surface at the protocol level the actual resources being accessed; it is also possible to relieve the web API from the need to keep track of access policies, relying entirely on the claims included with the incoming token. However the price to pay is an omniscient AS and more tokens than the approach shown in Figure 1 required._

Note: The mechanism we use for expressing that in the request to the AS doesn’t matter for the purpose of this discussion. for example, we can add a prefix to the scope string to point to the exact document we want, followed by the action we request (e.g. <documentID>:read), although in a real system it would make a big difference in term of usability.

The approach hinges on the assumption that the AS knows every resource, and knows all the policies governing who has access to what — and in what terms. This is represented by the access policies store in Figure 2. Armed with that knowledge, the AS can immediately evaluate whether the requestor has indeed the privileges corresponding to the permissions being requested and A) refuse to issue a token if the requirement aren’t met or B) issue a token containing a statement that access policies have been evaluated and the user should be allowed to perform the requested operation. In the case of B), any resource trusting the AS (and any resources whom delegated its full access management policies to the AS, a function NOT enshrined in either OIDC or OAuth) would simply follow the authorization directive contained in the token.

Now, let’s ignore for a moment that there’s no reason for such a statement to travel in a scope claim — one can pick ANY claim type without the need to overload an entity meant for a different scenario and make scopes consuming logic more complicated. Regardless of what claim is used, requesting a different token for each different document would create a very large increase in traffic. It’s not uncommon to see repositories with millions of documents, even in mid-sized businesses. Imagine the traffic generated by a simple thumbnail generator for a folder, multiplied for all the concurrent users across all the apps portfolio of the company, and all the ripples downstream to that (e.g. increase in size for token caches for offline use, increased lookup time to use those caches, etc., etc.).

Then there’s the matter of how many privileges you’d want to transmit in a token. Although having a client request different tokens for read and write operations is possible, that would exacerbate the tokens explosion challenge; but batching all the privileges a user has for a given document would be problematic as well, as the token itself could become very large. Expressing claims by reference is always possible, but having to make an API call for evaluating a claim would somewhat defeat the purpose of having scopes as a simple, immediately consumable source of truth for all things authorization.

## The Authorization Server Isn’t (Usually) Omniscient

But finally, the biggest problem of all is that having to keep the AS in the loop whenever documents are created, destroyed or assigned in different capacity to users is a daunting task — one that isn’t done even in much simpler settings than cloud and distributed systems based on public networks.

Think of how access to files is regulated in Unix or Windows: the domain controller doesn’t keep track of every file’s ACL — every file has a local policy, which is evaluated at access time rather than at ticket generation time. If OSes have to rely on resource side policies, despite all the simplifying conditions they enjoy (homogeneous resource types; constant line of sight with the domain controller; reliable network operations; etc), how could we expect this to be mainstream in the far more challenging public cloud scenario?

Now, technically all of this can be done. But it requires A LOT of work, very precise assumptions about the resources types and lifecycle, a very flexible AS, and so on — far from the naïve assumption that given that the ‘A’ in “AS” stands for “authorization”, all authorization logic can be centralized in the AS and all authorization decisions can be expressed as scopes values.

## In Summary

In the general case, scopes are used to express what an application can do on behalf of a given user — and that is always a subset of what the user can do in the first place. In other words, scopes are used for handling delegation scenarios. Resources are responsible to combine the incoming scopes and the actual user privileges to calculate the call’s effective permissions and make access control decisions accordingly.

Again in the general case, overloading scopes to represent actual privileges assigned to the app (as opposed to the delegated permissions mentioned above) is problematic — as it requires the AS to have specialized authorization knowledge at a granularity that is often not practical to achieve and maintain; even in the case in which that’s viable, the increase in traffic and token size might still render the approach unfeasible.

That is not to say that the AS should not make authorization decisions; if the AS happens to have access to data and logic that make it possible to take authorization evaluations at token issuance time, those can certainly be reflected in the decision of withholding issuance, or in the content of the issued token — but there’s no reason for the latter to be expressed in scopes claims, and doing so can in fact contribute to keep alive the urban legend that made me spend about half of a long flight writing this also long post.


On The Nature of OAuth2’s Scopes

A practical tutorial showing how to setup and develop a modern Web application based on ASP.NET Core 2.0 and React.

Developing Web Apps with ASP.NET Core 2.0 and React - Part 3

eHk3ciM

I am the Group Manager, Developer Content at Okta, and a Google Developer Expert in Web Technologies and Angular. I'm passionate about identity, authentication, constant learning, and developer communities. As a developer advocate, engineer, mentor, and international speaker, I love learning from and sharing with other inhabitants of the tech space.

Group Manager, Developer Content

Kim Maida

Learn about scope, closures, data flow, and concepts commonly utilized in modern JS frameworks & applications.

"scope"