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

A deep dive into OAuth 2.0 access tokens and the principle of least privilege to enhance your application's security by correctly scoping tokens and implementing robust validation strategies.

In the context of modern application security, access tokens play a prominent role in authorization. They are the digital keys that grant applications access to protected resources on behalf of a user. However, with great power comes great responsibility. A compromised access token can be a significant security liability. This is where the [principle of least privilege](https://csrc.nist.gov/glossary/term/least_privilege) (PoLP) becomes not just a best practice, but a critical defense mechanism.

This article takes a deep dive into the intersection of access tokens and the principle of least privilege, with a focus on leveraging the capabilities of [OAuth 2.0](https://auth0.com/intro-to-iam/what-is-oauth-2) to build more secure and resilient systems. We'll explore the foundational concepts, advanced techniques, and provide a practical checklist for your security reviews.

## What is the Principle of Least Privilege?

The **principle of least privilege** is a core concept in computer security. It states that users, programs, or processes should only be granted the minimum permissions necessary to perform their function. In other words, every component within a system should operate with the lowest possible level of access, or 'privilege', required for its tasks.

Think of it like giving keys to a building. Instead of giving every employee a master key that opens every door (*high privilege*), you give each person only the keys to the specific rooms they actually need to access (*least privilege*). For example, a receptionist gets a key to the front desk area, a developer gets a key to their office, but neither has access to the executive offices unless explicitly required.

This approach enhances security by **limiting the potential damage from an accident, error, or security breach**. If an account with limited privileges is compromised, the attacker's access is confined to a small controlled area, preventing them from gaining control over the entire system. Therefore, applying this principle means ensuring that applications and users can only access the specific data and perform the exact actions they are explicitly authorized to do, and nothing more.

## OAuth 2.0 and its Role in Access Control

At its core, OAuth 2.0 is an authorization framework, not an authentication protocol. This distinction is crucial. While authentication is about verifying identity, authorization is about granting permission to access specific resources. OAuth 2.0 provides a standardized way for a client application to obtain an access token from an authorization server, with the user's consent, to access resources hosted by a resource server.

A solid grasp of the OAuth 2.0 components is essential for implementing the principle of least privilege. Let’s quickly recap them:

* **Roles:**  
  * **Resource Owner:** The user who owns the data and grants permission to the application.  
  * **Client:** The application requesting access to the user's data.  
  * **Authorization Server:** The server that authenticates the resource owner and issues access tokens after obtaining their consent, e.g., Auth0.  
  * **Resource Server:** The server that hosts the protected resources and accepts access tokens for authorization, typically implemented as an API.  
* **Tokens:**  
  * **Access Token:** A credential used by the client to access protected resources. It represents the authorization of a specific client to access specific resources.  
  * **Refresh Token:** A long-lived credential used to obtain a new access token when the current one expires.  
* **Scopes:** The mechanism within OAuth 2.0 that allows us to define the granular permissions a client can request.

With this basic knowledge, let's delve deeper into how to implement the LP principle in a system protected by access tokens.

> For a deeper understanding of OAuth 2.0, consider reading [OAuth 2.0 and OpenID Connect: The Professional Guide](https://auth0.com/resources/ebooks/oauth-openid-connect-professional-guide).

## Scopes: The Heart of Least Privilege in OAuth 2.0

The true power of OAuth 2.0 in enforcing the principle of least privilege lies in the effective use of [scopes](https://auth0.com/blog/permissions-privileges-and-scopes/). Scopes are strings that define the specific permissions a client application is requesting. Unlike [OpenID Connect](https://auth0.com/docs/get-started/apis/scopes/openid-connect-scopes), OAuth 2.0 does not define standard scopes. The scopes used in an application scenario depend on the specific business case. Specifically, they are defined by the resource server (API) implementer and must be known to the client application. When designing the scopes for your API, follow a few best practices.

### No scopes, No party!

While the OAuth 2.0 specification does not explicitly forbid a client from [requesting an access token without a `scope` parameter](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1), doing so represents a significant security anti-pattern and a direct violation of the principle of least privilege.

When a client initiates an authorization request without specifying any scopes, [the authorization server's behavior can be ambiguous](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3). Since the OAuth 2.0 specifications do not define a standard behavior to handle this case, your application can receive an error message or a subset of predefined scopes, possibly empty.

Moreover, if API implementations do not accurately check scopes, you may find yourself in a scenario where the issued access token essentially grants the full permissions of the user.

This practice carries substantial risk. If a scopeless access token is compromised—leaked from a client-side application, intercepted in transit, or exfiltrated from a backend system—the attacker gains broad, unrestricted access to the user's resources. They could potentially read sensitive data, modify information, and perform actions on behalf of the user, all because the token's power was not constrained.

As a result, avoid scopeless access tokens. Always include the `scope` parameter in your application's authorization requests, and make your APIs always check for the expected scopes.

### Designing granular scopes

Vague or overly broad scopes defeat the purpose of least privilege. Consider an e-commerce API. You may think of scopes like `orders` or `profile` to allow access to the user’s orders and profile. However, these scopes are not explicit on the type of access they grant. Probably the `orders` scope says that your application can manage orders, i.e., it can read, create, update, print, for example. A more granular approach would be:

* `orders:read`: Allows the client to read a user's order.  
* `orders:write`: Allows the client to create new orders.  
* `profile:read`: Allows the client to read the user's profile information.  
* `profile:write`: Allows the client to update the user's profile.

This granularity ensures that a third-party analytics dashboard, for example, would only ever request and be granted the `orders:read` scope, mitigating the potential damage if its access token were to be compromised.

The following picture visually summarizes the application of the principle of least privilege using granular scopes:

<picture>
<img src="https://images.ctfassets.net/23aumh6u8s0i/4qzpht7LRcPnUerDwZXs07/6e09324185fd2afd7aa3488d1655b671/access-tokens-with-and-without-least-privilege.png" alt="A diagram comparing API access with and without the principle of least privilege, showing how OAuth 2.0 access tokens can provide granular, limited access for better API security." style="width:75%; margin: 0px auto;">
</picture>

### Leveraging hierarchical scopes

OAuth 2.0 does not strictly specify the format of scopes. They are generic strings whose meaning depends on the API context. As illustrated in the examples above, a common approach is to use the format `resource:action`. Some use the dot (`.`) as a separator instead of the colon (`:`). It really does not matter.

While you are free to use the format you prefer, consider taking advantage of the hierarchical structure of the format suggested above. For example, if you want to grant access only to the status of an order for informational purposes, but not at the details of the order, you can define a scope like `orders:status:read`. This allows you to have more granular control over a protected resource.

For more advanced scenarios, you may consider using [OAuth 2.0 Rich Authorization Requests](https://datatracker.ietf.org/doc/html/rfc9396), which allows you to specify detailed authorization requests.

### Using dynamic scopes

Modern applications often require different levels of access at different times. Instead of requesting all possible permissions upfront, a better user experience and security practice is to request scopes dynamically as needed. For instance, an application could initially request `profile:read` on user sign-up. Later, when the user wants to perform an action that requires more permissions, such as updating their profile, the application can initiate a new OAuth 2.0 flow to request the `profile:write` scope. This adheres to the principle of just-in-time access.

### Ensuring user consent

[User consent](https://auth0.com/docs/get-started/applications/confidential-and-public-applications/user-consent-and-third-party-applications) is a critical component in OAuth 2.0 authorization requests, directly supporting the principle of least privilege.

The authorization server must obtain explicit approval from the user, ensuring they understand and consent to the specific access an application client is requesting on their behalf. This consent should be freely given, with adequate information provided to the user.

In this context, a user-friendly description of the scopes a client application is requesting is key. The user should be aware of the permissions they are delegating to the application.

> A key aspect is that scopes do not create new permissions; they merely represent **a subset of the permissions the user already possesses** and delegated to the client application.

## Beyond Scopes: Advanced Token Security and Validation

While scopes are the primary tool for defining what an application can do on behalf of the user, a comprehensive strategy for least privilege involves more than just well-designed scopes. You must also consider the entire lifecycle of an access token.

### Token validation best practices

At the resource server, every incoming access token must be rigorously validated before granting access. This validation should go beyond simply checking the token's signature and expiration. Here are the fundamental steps to validate an access token before granting the application access to the resource:

1. **Signature Verification:** Always verify the token's signature against the authorization server's public key. This ensures the token was issued by a trusted source and has not been tampered with.  
2. **Expiration Check:** Check the `exp` claim to ensure the token has not expired.  
3. **Issuer and Audience Validation:** Verify the `iss` (issuer) and `aud` (audience) claims. The `iss` should match the expected authorization server, and the `aud` should match your resource server. This prevents tokens issued for one application from being used to access another.  
4. **Scope Enforcement:** This is the critical step for least privilege. The resource server must check the `scope` claim in the access token and ensure that the requested action is permitted by the granted scopes.  
5. **User Permissions Check**: Last but not least, make sure that the resource your application is requesting to access is actually accessible by the user with the permissions matching the scopes. Read [this article](https://auth0.com/blog/on-the-nature-of-oauth2-scopes/) to learn more about this.

### Short-lived access tokens and refresh tokens

In addition to a correct design and use of scopes, the management of access tokens is a critical security component adhering to the principle of least privilege. A key strategy to bolster security is the implementation of short-lived access tokens. The rationale behind this approach is to drastically reduce the "*window of opportunity*" for a potential attacker. If an access token, which grants an application permission to access specific resources, were to be compromised, its utility would be severely limited by its short lifespan.

Typically, these short-lived access tokens are issued with a validity period ranging from a few minutes to a few hours, depending on the business case and the security level required.This brevity is a deliberate security measure connected to the principle of least privilege: not only your application must have the minimum permissions it needs, but it must have them for the minimum amount of time necessary. However, to ensure a seamless user experience without requiring re-authentication every few minutes, a complementary mechanism is employed: [refresh tokens](https://auth0.com/docs/secure/tokens/refresh-tokens).

When an access token expires, the client application can use the refresh token to request a new, valid access token from the authorization server. This process is transparent to the user, maintaining a continuous session.

Given their power to grant new access tokens, refresh tokens themselves must be securely managed to prevent security issues. Learn more [about refresh tokens by reading this article](https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them/).

<include src="ebook-ads/Oauth2OidcGuide" />

## Security Review Checklist for Access Token-Based Systems

To assist in your development and review process, here is a checklist to help ensure you are adhering to the principle of least privilege and other access token security best practices.

**Scope and Permissions**

* Are scopes granular and well-defined, following the principle of least privilege?  
* Does the application request only the necessary scopes at any given time?  
* Is there a process for users to review and consent to the requested scopes?  
* Are there different levels of scopes for read vs. write vs. administrative actions?

**Token Issuance and Lifecycle**

* Are access tokens short-lived?  
* Are refresh tokens used to obtain new access tokens?  
* Are refresh tokens stored securely on the client?  
* Is there a mechanism to revoke refresh tokens and access tokens?

**Token Validation at the Resource Server**

* Is the token's signature verified on every request?  
* Is the token's expiration (`exp` claim) checked?  
* Is the issuer (`iss` claim) validated against a trusted value?  
* Is the audience (`aud` claim) validated to ensure the token is intended for this API?  
* Is the `scope` claim inspected, and are the permissions enforced for the requested operation?

## Conclusion

Building secure applications is not an afterthought but a core responsibility. The principle of least privilege is a powerful paradigm for mitigating the risks associated with access tokens. By meticulously designing granular scopes, implementing robust token validation, and managing the token lifecycle effectively, you can significantly enhance the security posture of your applications.

The OAuth 2.0 framework provides the tools necessary to implement a least privilege model, but it is your responsibility as developers to use them correctly and diligently. By following the best practices and using the checklist provided, you can be more confident in the security and resilience of your access token-based systems.

OAuth 2.0 Access Tokens and the Principle of Least Privilege

I stream, blog, and make youtube videos about tech stuff. I love coding, I love AI, and I love building stuff!

Staff Developer Advocate

Juan Cruz Martinez

Learn how to use the Auth0 Python SDK to query and store user data in this step-by-step tutorial.

The **Auth0 Dashboard** offers a wide range of tools for managing your application's authentication and authorization. You can create and delete users, assign roles, ban IPs, and much more. Although it's convenient to manage users directly from the dashboard, there may be scenarios where you need control from within your application.

Say, for example, that you want to store UI preferences such as dark/light mode settings or the user’s preferred theme directly on the user’s profile so that, independently from which device they connect to your application, they will have their favorite settings ready.

In scenarios like this, where your application directly processes and manages users' information, you can use the [Auth0 Management API](https://auth0.com/docs/api/management/v2), which allows you to work with users' data and programmatically access most features available in the Auth0 Dashboard.

In this article, we’ll explore how to use the Auth0 Management API from Python applications using the Auth0 Python SDK to read and store information about users, and at the end, we’ll build a lottery system to pull a random lucky user from the system.

## Accessing the Auth0 Management API

The Auth0 Management API allows you to programmatically create, access, update, and delete resources from your Auth0 tenant. It is an API built for back-end servers or trusted parties to perform administrative tasks such as user management or DevOps.

You can access the [Auth0 Management API](https://auth0.com/docs/api/management/v2) via HTTP requests directly or use one of the SDKs we provide for such a purpose. In any scenario, you’ll need a few things before starting the management API.

- **Auth0 account.** If you don’t have one already, you can <a href="https://a0.to/blog_signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for a free Auth0 account</a>.
- **A machine-to-machine application**
- **A short-lived token** for production access to the API

### Set up your Auth0 account

Once you have an <a href="https://a0.to/blog_signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">Auth0 account</a> you can navigate the the [Auth0 Dashboard](https://manage.auth0.com/#/applications) and access your applications list.

![Auth0 application's dashboard](https://images.ctfassets.net/23aumh6u8s0i/3QEFGVXK0EW2UlGNfaU8jK/bebbcfa41f716523f000c45b6ba863a0/auth0-ma-create-app.png)

Once on the page, click on the “Create Application” button on the top right and enter the following information:

- **Name**: A descriptive name for your application, e.g., User Management App
- **Application Type:** Because we’ll be connecting to this Auth0 application from another system, e.g., your Python application, you need to select “Machine to Machine Applications.”

Then click on “Create”.

![Creating a machine to machine application](https://images.ctfassets.net/23aumh6u8s0i/6F51sEhfGP6lOGXmldL8s7/c274315a617ae8f42c5278e61e91aa41/auth0-ma-create-app-details.png)

In the following dialog, you’ll select which API you’ll authorize this application to access. In our case, you’ll choose the **Auth0 Management API** already available in your tenant. Before authorizing the API, Auth0 will list all the permissions associated with it. There are many available. For our use case, you'll authorize the following: `read:users`, `update:users`, `read:users_app_metadata`, and `update:users_app_metadata`. Finally, click on “Authorize”.

![Assigning permissions to an API](https://images.ctfassets.net/23aumh6u8s0i/6eWpQ9QUTcOT9gT2gb5Do0/b4605872f7de2186401c747f044cd21e/auth0-ma-authorize-api.png)

> You can update your application’s permissions at any point from the Auth0 dashboard.

### Get a Test Token from the Auth0 Dashboard

Now you are ready to test your Auth0 Management API. Visit the API entry on the [Auth0 Dashboard](https://manage.auth0.com/#/apis).

![Auth0 API dashboard](https://images.ctfassets.net/23aumh6u8s0i/4ap0GxPP1WrjfaueqzfovG/150363bf27096f8bda6997aa5f49ced2/auth0-ma-apis.png)

Once there, click on the Auth0 Management API and head on to the “Test” tab. After a few seconds, you’ll see a screen like the following:

![Getting API Access Token from the Auth0 dashboard](https://images.ctfassets.net/23aumh6u8s0i/5HJDsh75FgjFB5fbfFhSLN/38ed227a790b4be7632ecaaa32c0af9e/auth0-ma-api-test.png)

Before continuing, ensure you have the correct application selected on the drop-down; next, you can copy your `access_token` from the UI. Make sure to copy just the value without the quotes. You’ll need this token next.

You can test your API directly on the [API documentation page](https://auth0.com/docs/api/management/v2). You can explore and test all the API endpoints there, though we’ll focus on the list [user’s endpoint](https://auth0.com/docs/api/management/v2#!/Users/get_users) for now.

![Auth0 Management API docs](https://images.ctfassets.net/23aumh6u8s0i/6tZBiNtrWUf8fmGeji8FUS/112e38d8ae05bf8376b402b9ccc04699/auth0-ma-list-users.png)

On the “List or Search Users” section, you’ll find the different parameters you can use to query users. For now, we’ll leave them all to the default values, and if you look to the right of the screen, you’ll find a button, “Test Endpoint”, at the end of the section.

The button is currently disabled as the documentation page is not authorized to make calls to the management API yet. To test endpoints on the documentation page, you'll need to provide an API Token using the "Set API Token" on the top right of the screen.

![Set API Token to make API calls](https://images.ctfassets.net/23aumh6u8s0i/6UO3HenV2TLVG6xTjVVFsF/24eaa6acff4b6728849588e434f7a202/auth0-ma-set-api-token.png)

Next, paste your access token from the Auth0 dashboard into the modal window and click “Set Token”. If you copied the token value correctly and tried the endpoint again, you should now see your list of users.

![Example response for the list users API endpoint](https://images.ctfassets.net/23aumh6u8s0i/5fse9EYIe0xXci2oPtxDXU/2980f08b1cdca89640fc4a0e6f787fa1/auth0-ma-list-users-list.png)

## How to Consume the Auth0 Management API with Python

To make your life easier when working with the Auth0 Management API, Auth0 offers a set of tools in multiple programming languages. In the case of Python, we have the [Auth0 Python SDK](https://github.com/auth0/auth0-python) that allows for easy and convenient access to all the features in the management API.

To consume the Auth0 Management API with Python, we will use the Auth0 Python SDK. To install it, run the following command:

```bash
pip install auth0-python
```

After installing the library, you must get a short-lived access token and initialize it programmatically. You’ll need information about your Auth0 tenant domain and the machine-to-machine application you created before. You’ll need the “Client Id” and the “Client Secret”, which can be found on the [Auth0 Dashboard](https://manage.auth0.com/#/applications) under your application’s settings.

![Domain, Client Id, and Client Secret are available in the app settings](https://images.ctfassets.net/23aumh6u8s0i/72vTRKfXxiFPXNIxTAGZkb/9be57cda028c928c9091d00c638c2d00/auth0-ma-app-settings.png)

Once you can access these values, you set the Auth0 SDK with the following code:

```python
from auth0.authentication import GetToken
from auth0.management import Auth0

domain = 'mydomain.auth0.com'
client_id = 'myclientid'
client_secret = 'myclientsecret'

get_token = GetToken(domain, client_id, client_secret=client_secret)
token = get_token.client_credentials('https://{}/api/v2/'.format(domain))
mgmt_api_token = token['access_token']
auth0 = Auth0(domain, token['access_token'])

auth0 = Auth0(domain, mgmt_api_token)
```

And finally, if you, for example, want to list your users, you can run:

```python
users = auth0.users.list()
print(users)

# Example Output
{
    "start": 0,
    "limit": 25,
    "length": 25,
    "users": [
        {
            "created_at": "2023-07-14T11: 01: 09.493Z",
            "email": "###.#####@###.com",
            "email_verified": False,
            "identities": [
                {
                    "connection": "Username-Password-Authentication",
                    "provider": "auth0",
                    "user_id": "64b12af5c157759fdf791d4d",
                    "isSocial": False
                }
            ],
            "name": "###.#####@###.com",
            "nickname": "###.#####",
            "picture": "https: //s.gravatar.com/avatar/.........png",
            "updated_at": "2023-07-14T11:01:09.493Z",
            "user_id": "auth0|64b12af5c157759fdf791d4d",
            "last_login": "2023-07-14T11:01:09.491Z",
            "last_ip": "2a01:c23:c480:7900:6c:a31c:9c46:f435",
            "logins_count": 1
        },
        ...
    ],
    "total": 40
}
```

## Updating Users’ Profile Information

Auth0's user profiles store basic information about each user, including a unique identifier, name, contact details, and identifying information such as their profile picture. This information is helpful during the authentication process, but you may also require additional information as the user logs in, such as:

- User preferences, such as the application’s theme or color scheme, etc.
- Flags that the user opt-in in the application, such as notification preferences, getting started tutorial completion, etc.
- Others, such as the last read announcement, subscription status, and more.

Auth0's user profiles can store such information as metadata, which your app can access once the user logs in successfully. Although your app could store this information in its own storage system, utilizing Auth0's user profile metadata offers the advantage of immediate availability during and after the login process.

A significant benefit of using metadata is that it is associated with the user's account rather than tied to a specific device. This ensures that if a user switches between the mobile and web versions of your app, their settings and preferences based on metadata will remain consistent across both versions.

Auth0 supports two types of users’ metadata:

- **User metadata:** refers to information the user can see and update, such as user preferences and settings
- **App metadata:** refers to information about the user that is only accessible by the application, for example, feature flags, last read announcement, and more.

Let’s now write a Python script to update the user’s name and metadata to store their preferred theme and an application flag enabling extra features on the user’s account.

```python
# As we did before, we need to get an instance of the Auth0 client
from auth0.authentication import GetToken
from auth0.management import Auth0

domain = 'mydomain.auth0.com'
client_id = 'myclientid'
client_secret = 'myclientsecret'

get_token = GetToken(domain, client_id, client_secret=client_secret)
token = get_token.client_credentials('https://{}/api/v2/'.format(domain))
mgmt_api_token = token['access_token']
auth0 = Auth0(domain, token['access_token'])

auth0 = Auth0(domain, mgmt_api_token)

# Next, we can proceed to update the user's name using the user's id
user_id = '{YOUR_USER_ID}'
auth0.users.update(user_id, {
    'name': 'My name is...'
})

# We can also update the user's metadata
auth0.users.update(user_id, {
    'user_metadata': {
    'theme': 'light'
  },
  'app_metadata': {
    'experimental_features': True
  }
})

# Let's add some more information to see what the end result is
auth0.users.update(user_id, {
    'user_metadata': {
    'font_size': '16px'
  },
  'app_metadata': {
    'notifications': False
  }
})

# Query the user information
user_info = auth0.users.get(user_id)
print(user_info)

# Output
{
    "created_at": "2023-07-14T09:22:19.151Z",
    "email": "###.#####@###.com",
    "email_verified": False,
    "identities": [
        {
            "connection": "Username-Password-Authentication",
            "user_id": "64b113cb6a989b51063087ce",
            "provider": "auth0",
            "isSocial": False
        }
    ],
    "name": "My name is...",
    "nickname": "###.#####",
    "picture": "https://s.gravatar.com/avatar/...",
    "updated_at": "2023-07-14T11:29:53.139Z",
    "user_id": "auth0|64b113cb6a989b51063087ce",
    "user_metadata": {
        "theme": "light",
        "font_size": "16px"
    },
    "app_metadata": {
        "experimental_features": True,
        "notifications": False
    }
}
```

Note that when calling the `update` method, we don’t need to send all the information about the user, but only those fields we would like to change. This makes working with data really simple, as we don’t need to worry about overriding critical fields. Even on the `user_metadata` and `app_metadata` fields, we don’t need to send the full JSON we want to store but rather the individual key-value pairs, Auth0 will automatically merge the existing values with the new ones.

We can also access the user information from the [user’s entry in the Auth0 Dashboard](https://manage.auth0.com/#/users).

![Viewing user's profile and metadata information in the Auth0 dashboard](https://images.ctfassets.net/23aumh6u8s0i/12wH1mxn2Od5hcOQ7SwOTG/d8f45e0725c7eaeeab916bf94a6b9723/auth0-ma-list-user-data.png)

## Query Users

Whether you are building a user dashboard, gathering some statistics, or needing your users’ information to process in your application, the Auth0 Management API and the Auth0 Python SDK allow you to access the information you need and how you need it.

Previously we used the method `users.list` to retrieve a list of all users in the Auth0 database, which may be all that you need. However, that method offers advanced query functions worth knowing and exploring.

First, let’s start with paginating results. By default, paging is disabled. However, you can quickly specify the page and the number of items per page you want to retrieve with these two parameters:

- **page**: Page index of the results to return. The first page is 0.
- **per_page**: Number of results per page.

Here is an example querying the second page of users, up to ten users per page

```python
users = auth0.users.list(page=1, per_page=10)
```

Another common parameter in usage is sorting operations. For this purpose, the SDK exposes the `sort` parameter to specify the field and direction. For example:

```python
users = auth0.users.list(sort="name:1")
```

Use `field:order` where the order is `1` for ascending and `-1` for descending.

Lastly, one of the most powerful functions is the ability to perform complex queries, for example, getting all the users whose names start with `J` or even filtering by custom metadata, listing all the users that prefer the dark mode theme. Auth0 uses [Lucene query string syntax](http://www.lucenetutorial.com/lucene-query-syntax.html) for those complex queries, though there are some limitations, as some query types cannot be used on metadata fields, for details see [Searchable Fields](https://auth0.com/docs/users/search/v3/query-syntax#searchable-fields).

Example 1: List all users whose name starts with `J`

```python
users = auth0.users.list(search_engine='v3', q='name:j*')
```

Example 2: List all users that prefer dark mode

```python
users = auth0.users.list(search_engine='v3', q='user_metadata.theme:dark')
```

You can also mix multiple search criteria, for example:

```python
users = auth0.users.list(search_engine='v3', q='name=j* AND user_metadata.theme:dark')
```

To learn more about how to form queries, check the [Lucene query string syntax](http://www.lucenetutorial.com/lucene-query-syntax.html).

## Selecting a Random User

For the events we attended this year, we created a fun game using Python, Flask, and Auth0 to give some fabulous prizes away to lucky contestants. The game was pretty simple. It consisted of people signing up for our application at events like PyCon. During the day, users registered to the game using the Auth0 Universal Login page. Then, when it was time to give prizes away, we would use the same Flask application to withdraw a lucky winner. The winner would then get a special award from Auth0.

To select the lucky winner, we built a special page using the `users.list` method. There was a caveat: the same user couldn’t win twice. The way we solved it was by using `app_metadata` to store information about the users who had already won and then using Lucene syntax to filter them out when pulling for a new winner.

Though not critical for our situation, we wanted the script to be efficient and thus not pull the whole user’s database, as it could be quite extensive, so instead, we first pulled the API to know how many users were in total with a minimum query, and then we accessed a random user from the pull and extracted only that user’s information.

```python
import random

# List only 1 user just to retrieve the total number of users that match the given query
user_count = auth0.users.list(per_page=1, include_fields=False, search_engine='v3', q='NOT app_metadata.winner:true')["total"]

# Then, use the same trick of listing one user per page to get a random page between 0 and the total number of users
# That resulting user is our lucky winner
winner_user = auth0.users.list(page=random.randint(0, user_count - 1), per_page=1, include_fields=False, search_engine='v3', q='NOT app_metadata.winner:true')['users'][0]

# Before we do anything else with the results, update the user's metadata to reflect them as winner
auth0.users.update(winner_user.get('user_id'), {
    "app_metadata": {
        "winner": True
    }
})
```

## Summary

Today you learned about the Auth0 Management API and how to work with it from the documentation as well as from any Python application. You also learned how to work with user information, user, and app metadata, and how to query users from the Auth0 database using simple and more complex queries.

Thanks for reading!

Use the Auth0 Python SDK for Querying and Storing Users’ Data

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

5e074956ee8ba1fea26e30d28c190495?s=300 avatar

5e074956ee8ba1fea26e30d28c190495?s=300

Full stack developer creating content at Auth0. I love taking a deep dive into hard-to-understand concepts and creating content that makes them easier to grasp. In my free time you can usually find me reading, hanging out with my dogs, or curling in the squat rack.

Former Developer Content Manager

Holly Guevara

Learn how to use the Auth0 Management API to build an admin dashboard with Express and Vue



<details>
<summary>Starting from this chapter?</summary>

**Setting up**

Clone the application starter repo and check out the `creating-the-backend` branch:

``` bash  
git clone git@github.com:auth0-blog/express-vue-management-api.git --branch creating-the-backend
```

Install the dependencies for both the client and server:

``` bash  
cd server
npm install
cd ../client
npm install
```

**Configure Auth0**

Follow the Auth0 Configuration directions in the [project README of the starter Vue and Express application](https://github.com/auth0-blog/vue-express-auth#configuring-auth0).

**Configure Management API**

In the [Auth0 dashboard](https://manage.auth0.com/dashboard), click on "APIs" in the left menu and then select "Auth0 Management API". From there, select "Machine to Machine Applications" and find the "Vue Express API" you just created. Click the switch next to it so that it says "Authorized".

![Auth0 authorized API](https://images.ctfassets.net/23aumh6u8s0i/3bnn4TcXg4JJ6Ti42f4ymi/1545602b9f43d8c6dcfafda536730d27/auth0-management-api-authorized)

Next, add permissions to the application. Click on the down arrow V next to the authorized switch. Select `read:users`, `delete:users`, and `read:user_idp_tokens` and then click "Update".

Create the `.env` file in the root of the `server` directory:

``` js  
AUTH0_DOMAIN = your-domain.auth0.com
AUTH0_AUDIENCE = https://your-api-audience.com
CLIENT_ID = yourclientid
CLIENT_SECRET = yourclientsecret
```

To find your values, go to the [Auth0 dashboard](https://manage.auth0.com/dashboard) and click:

"APIs" > "Auth0 Management API" > "Test"

Select the Express API from the dropdown then click "Node.JS". You'll find the values for `CLIENT_ID` AND `CLIENT_SECRET` in the resulting code.

`AUTH0_DOMAIN` and `AUTHO_AUDIENCE` can be found by clicking on "APIs" and then selecting the Vue Express API. Then click on "Quick Start" and select "Node.js". You'll see a value for audience, which you can paste directly into AUTH0_AUDIENCE and then another value for issuer. Copy this and paste it into AUTH0_DOMAIN, but leave off the `https://` and the trailing `/` at the end.

**Test it**

Start the Vue app:

``` bash  
cd client
npm run serve
```

Start the Express app:

``` bash  
cd server
npm start
```

Navigate to [http://localhost:8000/users](http://localhost:8000/users) to see an array all of your users from the Express `/users` endpoint.

View the dashboard at: [http://localhost:8080/dashboard](http://localhost:8080/dashboard)

</details>

## Creating the Dashboard with Vue

Here's what needs to be done on the Vue side:

* Create a dashboard route
* Create a new dashboard component
* Create the user service to connect to the Express API
* Make a `GET` request to the Express API's `/users` route
* Loop over and display the users
* Create a delete button and delete method
* Add the delete method to the user service that makes a request to the Express API's `/users/:id/delete` route
* Pass the user's access token along with their Express API requests
* Restrict the route so that unauthenticated users will be kicked to the login screen

I'll go over each step here, but if you'd like a more in-depth explanation about making HTTP requests in Vue, I'd recommend going back and reading through the original article that this application is based on, [Making HTTP Requests with Vue and Express](https://auth0.com/blog/how-to-make-secure-http-requests-with-vue-and-express/). 

If you haven't already, you can start the Vue application by navigating to the `client` directory in the terminal and running:

``` bash  
npm run serve
```

You can view it at [http://localhost:8080](http://localhost:8080)

## Add the Dashboard Route

First, go ahead and create the `/dashboard` route, which is where the user list will be displayed.

Open up `client/src/router/index.js` and paste the following in as the last element in the `routes` array:

``` js  
{
    path: '/dashboard',
    name: 'dashboard',
    component: () => import('../views/Dashboard.vue')
}
```

## Create the Dashboard Component

You'll notice that the `/dashboard` route is using the `Dashboard.vue` component. This doesn't exist yet, so go ahead and create it now.

Under `client/src/views`, create a new file called `Dashboard.vue` and paste in the following:

``` js  

<template>
<div class="container">
  <h2 class="title is-size-3 has-text-centered">Welcome to your dashboard</h2>
  <div class="columns" v-if="message">
    <div class="column is-one-quarter is-offset-8">
      <div class="notification is-success">
        {{ message }}
      </div>
    </div>
  </div>
  <div class="columns is-multiline has-text-centered">
    <div v-for="user in users" :user="user" :key="user.id" class="column is-one-quarter">
      <img :src="user.picture" :alt="user.name" style="width:200px;margin-left:auto;margin-right:auto;"/>
      <h3 class="is-size-6">Name: {{ user.name }}</h3>
      <h3 class="is-size-6">Email: {{ user.email }}</h3>
      <h3 class="is-size-6">Last login: {{ user.last_login }}</h3>
      <h3 class="is-size-6">Login count: {{ user.logins_count }}</h3>
      <button @click="deleteUser(user.user_id)" class="button is-medium is-danger">Delete me 😵</button>
    </div>
  </div>
</div>
</template>
<script>
import UserService from '@/services/UserService.js';
export default {
    name: "Dashboard",
    data() {
    return {
      users: [],
      message: ''
    };
  },
  created() {
    this.getUserData(); // call getEventData() when the instance is created
  },
  methods: {
    async getUserData() {
      // Pass the access token to the getUsers service
      UserService.getUsers()
      .then(
        (users => {
          this.$set(this, "users", users);
        }).bind(this)
      );
    },
    async deleteUser(deleteId) {
      // Pass specified id to the deleteUser service
      UserService.deleteUser(deleteId)
      .then(
        (response => {
          this.message = response; 
          this.getUserData(); // get refreshed users
        })
      );
    }
  }
}
</script>
<style lang="scss" scoped>
  .notification {
    position: fixed;
    top: 800px;
    right: 40px;
  }
  .button {
    margin-top: 15px;
  }
</style>

```

In the script section, you're first importing the `UserService`. This is what your Vue application will use to connect to the Express API defined in the `server` directory. The Express API is responsible for getting the data from the Management API.

> 🧠 Your Vue client cannot reach out to the Management API directly because it would need an access token to do that, and as you saw earlier, that would require the client (Vue) to pass the client secret on the frontend, which isn't secure.

So, instead, the **Express API handles the connection** with the Management API. The Vue application then makes a request to the Express API using the `UserService` and receives the user information that the Express API passes back to it.

Of course, you wouldn't want just *anybody* to be able to access this user information. This is why the **request to the Express API from the Vue client must be authorized**. With the current implementation, anyone will be able to access the Express API endpoints to obtain the list of users and delete a user. Sit tight for now, and you'll be addressing that in an upcoming section.

The next important thing to note here are the 2 methods: `getUserData()` and `deleteUser(deleteId)`. The first method is called when the Dashboard instance is created. It's going to call the `getUsers()` method on the `UserService` and then set the result to the `users` array (defined under `data`). The next method will be called when the user clicks on a "Delete me" button underneath a user. It will send the selected user's `user_id` through to the `UserService.deleteUser()` method as a parameter.

If you glance back up now at the template section, you'll see where that `users` array comes into play. You're looping over it to display each individual user's avatar, name, email, last login date, and login count.

Finally, there's a `message` variable that will let us know that a user has been deleted.

Now, the `UserService` doesn't exist, so none of this is going to work yet. Go ahead and create it now.

## Create the User Service

Create a new file called `UserService.js` under `client/src/services` and paste in the following:

``` js  

import axios from "axios"
export default {
  async getUsers() {
    let res = await axios.get("http://localhost:8000/users");
    console.log(res.data);
    return res.data;
  },
  async deleteUser(id) {
    let res = await axios.get(`http://localhost:8000/users/${id}/delete`);
    return res.data;
  }
}

```

This allows the Vue application to make a `GET` request to the Express API using [axios, a promise-based HTTP client](https://github.com/axios/axios).

You're calling the `/users` and `users/${id}/delete` routes that you built earlier in Express. The `/users` route is the one that returns the user information from the Management API.

So when the Vue application makes a `GET` request to the Express `/users` route, Express reaches out to the Management API and makes a request for the list of users. If the access token that the Express API presents is valid, then the Management API returns the users. Consequently, the Express API will then return that data to the requesting Vue application.

Again, it's important to verify that the Vue application is allowed to access this information. **Whether or not it's allowed to access it is between the Express API and the Vue application, not the Management API**. Currently, there's nothing in place to check that the Vue application is allowed to make this request to the Express API. You'll see how to implement this in the next section.

For now, make sure your Vue application and Express app are both still running in the terminal:

**Vue application:**

``` bash  
npm run serve
```

**Express application:**

``` bash  
npm start
```

Head to [`http://localhost:8080/dashboard`](http://localhost:8080/dashboard), and you should now see your shiny new dashboard with all of your user's avatars and information displayed.

> 🚨 Resist the urge to click the "Delete" button on the accounts you want to keep! I recommend creating test user accounts through the Auth0 dashboard when you want to try out the delete button.

![Vue Express Auth0 management API user dashboard](https://images.ctfassets.net/23aumh6u8s0i/6tjQ9rvSCgOcZ9MIrd9dCx/61d999a28e841ab4aac8a07c547226d0/auth0-user-management-api-dashboard)

<include src="tutorial/NextButton" nextPart="build-an-admin-dashboard-with-express-and-vue-adding-user-authorization/" completedMessage="I've created the Vue dashboard"/>

<include src="tutorial/IssueButton" communityTopic="53302"/>


Build an Admin Dashboard with Express and Vue: Creating the Frontend



<details>
<summary>Starting from this chapter?</summary>

Clone the application starter repo:

``` bash  
git clone git@github.com:auth0-blog/vue-express-auth.git
```

Follow the directions in the [project README](https://github.com/auth0-blog/vue-express-auth#set-up-the-express-server).

In the [Auth0 dashboard](https://manage.auth0.com/dashboard), click on "APIs" in the left menu and then select "Auth0 Management API". From there, select "Machine to Machine Applications" and find the "Vue Express API" you just created. Click the switch next to it so that it says "Authorized".

![Auth0 authorized API](https://images.ctfassets.net/23aumh6u8s0i/3bnn4TcXg4JJ6Ti42f4ymi/1545602b9f43d8c6dcfafda536730d27/auth0-management-api-authorized)

Next, add permissions to the application. Click on the down arrow V next to the authorized switch. Select `read:users`, `delete:users`, and `read:user_idp_tokens` and then click "Update".

</details>


## Calling the Management API with Express

The Express API is now registered in the dashboard, and the Auth0 Management API is set up and ready to issue an access token to the Express API. So what's next? Now, you have to do the [**client credentials**](https://auth0.com/docs/flows/concepts/client-credentials) dance to get an access token.

## Client Credentials Flow

The [OAuth 2.0 RFC 6794](https://tools.ietf.org/html/rfc6749#section-4.4) defines how trusted clients (your Express API) can use the client credentials to request an access token from a resource owner (the Auth0 Management API):

> ❗ The client can request an access token using only its client credentials (or other supported means of authentication) when the client is requesting access to the protected resources under its control, or those of another resource owner that have been previously arranged with the authorization server (the method of which is beyond the scope of this specification).

Because the Management API access token is requested on behalf of the Express application, not a user, it doesn't make sense to ask for a username and password to verify who the requester is. Instead, you can use the Express application's client credentials (`client_id` and `client_secret`) to authenticate the application.

![Machine to machine client credentials grant](https://images.ctfassets.net/23aumh6u8s0i/3nVhN6jBKCjJxpO2BhcxOW/af8eaeabf5529b52e5e5ce865d045045/auth-sequence-client-credentials)
> This diagram depicts the client credentials grant flow described below

* The Express application authenticates with the Auth0 Authorization Server using its `client_id` and `client_secret`
* The Auth0 Authorization Server validates the  `client_id` and `client_secret`
* The Auth0 Authorization Server issues an access token and passes it back to your application
* The Express application passes this token when it makes a request to the Management API
* The Management API responds with the requested data

## Requesting an Access Token  

The Express application needs to request an access token for the Management API from the Auth0 server. There are **three ways** to do this.

1) Make a `POST` request to the token endpoint using your Express API client ID and client secret, as shown below:

<include src="AmpWarning" fullUrl="https://auth0.com/blog/build-an-admin-dashboard-with-express-and-vue-creating-the-backend"/>

``` js  
let request = require("request");

let options = {
    method: 'POST',
    url: 'https://YOUR-DOMAIN.auth0.com/oauth/token',
    headers: { 'content-type': 'application/json' },
    body: '{
        "client_id": "yourclientid",
        "client_secret": "yourclientsecret",
        "audience": "https://YOUR-DOMAIN.auth0.com/api/v2",
        "grant_type": "client_credentials"
    }'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
});
```

This will return the **access token** (with a 24-hour expiration) and **token type**:

``` js  
{
  "access_token": "somelongstring",
  "token_type": "Bearer"
}
```

2) Use the [Auth0 Node Authentication API Client](https://www.npmjs.com/package/auth0#authentication-api-client)

``` js  
let AuthenticationClient = require('auth0').AuthenticationClient;
 
let auth0 = new AuthenticationClient({
  domain: '{YOUR_ACCOUNT}.auth0.com',
  clientId: '{CLIENT_ID}',
  clientSecret: '{CLIENT_SECRET}'
});
 
auth0.clientCredentialsGrant(
  {
    audience: 'https://{YOUR_ACCOUNT}.auth0.com/api/v2/',
    scope: '{MANAGEMENT_API_SCOPES}'
  },
  function(err, response) {
    if (err) {
      // Handle error.
    }
    console.log(response.access_token);
  }
);
```

This performs a Client Credentials Grant using the `clientId` and `clientSecret` of the client that was registered in the Auth0 dashboard, in this case, the Express API. This will return the **access token**, **scopes**, **expiration**, and **token type**. You'll then send this access token along with every request you make to the Management API.

3) Use the [Auth0 Node Management API Client](https://www.npmjs.com/package/auth0#management-api-client)

``` js  
let ManagementClient = require('auth0').ManagementClient;

let auth0 = new ManagementClient({
  domain: '{YOUR_ACCOUNT}.auth0.com',
  clientId: '{YOUR_CLIENT_ID}',
  clientSecret: '{YOUR_CLIENT_SECRET}',
  scope: 'read:users delete:users'
});
```

Finally, there also exists an option to **automatically receive an access token in the background** using the [Auth0 Node Management API Client](https://www.npmjs.com/package/auth0#management-api-client). This is similar to option 2. The Client Credentials Grant still takes place behind the scenes and will retrieve a Management API access token along with its expiration. It then automatically caches this access token for the time specified in the expiration.

For this tutorial, you'll be using the third option. This option allows you to use the [Management Client to easily make requests to the Management API](https://auth0.github.io/node-auth0/module-management.ManagementClient.html).

## Getting your Access Token in Express

Now that you know how the client credentials flow works and how you're going to implement it in your application, it's finally time to write some code!

Head back to your code editor and open `server/server.js` from the [Vue Express application you cloned earlier](https://github.com/auth0-blog/vue-express-auth).

📝 Here's an overview of what you're going to do:

- Install and import the Auth0 `ManagementClient`
- Create a `.env` file for your confidential values
- Add `clientId` and `clientSecret` to your `authConfig` object
- Create a new instance of the `ManagementClient` with your `domain`, `clientId`, and `clientSecret`

Make sure you're in the `server` directory in your terminal and install the [`node-auth0`](https://www.npmjs.com/package/auth0) package by running:

``` bash  
npm install auth0
```

Find the `require` functions at the top of your `server/server.js` file and add the following line to import `ManagementClient`.

``` js  
// ...
// import statements
const ManagementClient = require('auth0').ManagementClient;
// app.use 
```

Next, toward the top of the file, you should see an `authConfig` object directly underneath the `require` and `use` methods. This needs to be modified to include your client secret and client ID from the Express API.

Because these are sensitive values, you should not save them directly in the code. If you ever share this code or upload it to GitHub, you [risk leaking your client secret](https://auth0.com/blog/developers-guide-to-common-vulnerabilities-and-how-to-prevent-them/#Mishandling-Sensitive-Data). Instead, it's best to create a `.env` file and add this file to your `.gitignore`. To do this, navigate to the `server` directory and run the following command in your terminal: 

``` bash  
npm install dotenv
```

At the top of your `server/server.js` file add this line:

``` js  
require('dotenv').config();
```

Now create a file in the root of the `server` directory called `.env` and add the following to it:

``` js  
AUTH0_DOMAIN = your-domain.auth0.com
AUTH0_AUDIENCE = https://your-api-audience.com
CLIENT_ID = yourclientid
CLIENT_SECRET = yourclientsecret
```

The values for `CLIENT_ID` and `CLIENT_SECRET` can be found back in the [Auth0 dashboard](https://manage.auth0.com/dashboard) on the Auth0 Management API page that you set up earlier.

If you already closed this tab, just click on "**APIs**" > "**Auth0 Management API**" > "**Test**" and then select the Express API from the dropdown. Next, click on "**Node.JS**", and you can copy the `client_id` and `client_secret` from the resulting code below.

If you followed the setup instructions from the README, you should already have an object in `server.js` called `authConfig` that contains the audience and domain values. Grab those and paste them into their corresponding spots in `.env`.

If you don't have the domain and audience values, they can be found by clicking on "**APIs**" in the left-hand menu and then selecting the Vue Express API. Next, click on "**Quick Start**" and then select "**Node.js**". You'll see a value for `audience`, which you can paste directly into `AUTH0_AUDIENCE` and then another value for `issuer`. Copy this and paste it into `AUTH0_DOMAIN`.

> ⚠️ Important: For `AUTH0_DOMAIN`, omit the `https://` and the trailing `/`. It should be formatted exactly as shown above.

Next, modify the `authConfig` object in `server/server.js` to use those environment variables as follows:

``` js  
// Set up Auth0 configuration
const authConfig = {
  domain: process.env.AUTH0_DOMAIN,
  audience: process.env.AUTH0_AUDIENCE,
  clientId: process.env.CLIENT_ID,
  clientSecret: process.env.CLIENT_SECRET
};
```

And finally, you'll create a new instance of the `ManagementClient`, which takes an object that contains your Auth0 domain, client ID, and client secret.

Paste this just below the `authConfig` object in `server/server.js`:

``` js  
const managementAPI = new ManagementClient({
  domain: authConfig.domain,
  clientId: authConfig.clientId,
  clientSecret: authConfig.clientSecret
});
```

Now, when you use `managementAPI`, it will automatically perform the Client Credentials Grant in the background using the domain, client ID, and the client secret, which will result in an access token that can be used to make requests to the Management API.

Now it's time to test it out.

## Calling the Management API

Back in `server/server.js`, scroll down to where the `events` array is defined. Paste in the following code right below it:

``` js  
app.get('/users', (req, res) => {
  managementAPI
    .getUsers()
    .then(function(users) {
      res.send(users);
    })
    .catch(function(err) {
      console.log(err);
    });
});
```

This will create an API route in your Express application that calls the [Management API Node Client to get all users](https://auth0.github.io/node-auth0/module-management.ManagementClient.html#getUsers) whenever that route is accessed.

To verify that it's working, switch to your terminal and start your Express application if you haven't already by running:

``` bash  
npm start
```

Navigate to [`http://localhost:8000/users`](http://localhost:8000/users) in your browser, and you should see all of the users that have signed up for your application! 💃

If you're getting an error, **reach out in the comments below**, and I'll try to help troubleshoot.

You're also going to need a route to delete a user, so since you're here, just set that up now. Below the previous route, paste in:

``` js  
app.get('/users/:id/delete', (req, res) => {
  managementAPI
  .deleteUser({ id: req.params.id })
  .then(response => {
    res.send('User deleted!');
  })
  .catch(function(err) {
    res.send(err);
  });
});
```

This will grab the `id` of the user, which will be passed to the server from the Vue client. Then it will call the Management API to do the deletion.

Now that you're able to pull all of your users into the application and delete a user, it's time to switch to the frontend.

<include src="tutorial/NextButton" nextPart="build-an-admin-dashboard-with-express-and-vue-creating-the-frontend/" completedMessage="I've set up the Express backend"/>

<include src="tutorial/IssueButton" communityTopic="53302"/>


Build an Admin Dashboard with Express and Vue: Creating the Backend



The **Auth0 dashboard** has extensive tools that you can use to manage your application's authentication and authorization. You can create users, delete users, assign roles to users, ban IPs, and much more. While it's great to have the option to manage users straight from the dashboard, you might sometimes run into a scenario where you need to have that control straight from your own application.

Consider this use case. You're building a blogging platform for a client, and you're using Auth0 as an identity solution. The client has a few employees that will need full admin access to the blog. They'll have the ability to make updates to any users that sign up, ban users, view user data, and more.

Here's the caveat: the client doesn't want her employees to have to sign into another platform to do this. She wants you to build a dashboard on the blogging platform that will give administrators the capability to manage users straight from the blogging application. Lucky for you, you can do all of this using the [Auth0 Management API](https://auth0.com/docs/api/management/v2)! 

In this article, you'll learn how to **build a simple user management dashboard** using Vue.js, Node.js, and [Auth0](https://auth0.com). You'll be using the Auth0 Management API to pull all of your application's users into your Vue Express application. You'll also add a delete button so that you can delete users straight from your own dashboard. You can check out the final [User Management Dashboard code here](https://github.com/auth0-blog/express-vue-management-api).

![Auth0 user dashboard Management API](https://images.ctfassets.net/23aumh6u8s0i/6tjQ9rvSCgOcZ9MIrd9dCx/61d999a28e841ab4aac8a07c547226d0/auth0-user-management-api-dashboard)

## Getting Started

To keep this focused on user management, you're going to be building the dashboard from an existing application that was built in two previous tutorials: [Beginner Vue.js Login Tutorial](https://auth0.com/blog/beginner-vuejs-tutorial-with-user-login/) and [Making HTTP Requests with Vue and Express](https://auth0.com/blog/how-to-make-secure-http-requests-with-vue-and-express/).

You don't need to read those to follow along with this tutorial, but you should be familiar with Vue and Express. If not, those two tutorials will be a great starting point, even for a beginner!

To begin, clone the [Vue and Express Events app repository](https://github.com/auth0-blog/vue-express-auth) and follow the instructions in the README to get everything set up. You'll also need to <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for a free Auth0 account</a>. The [Auth0 configuration details](https://github.com/auth0-blog/vue-express-auth#configuring-auth0) are also in the README.

Without further ado, let's dive into the Management API!

## Using the Management API

This will be covered step by step, but here's a quick overview of what you'll need to do to get access to the Auth0 Management API:

* Create a Machine-to-Machine Application in the Auth0 dashboard
* Connect it to your Express API
* Get a short-lived access token for production

[In the Auth0 dashboard](https://manage.auth0.com/dashboard/), click on "APIs" in the left menu and then select "Auth0 Management API". This is a pre-configured Auth0 system API that you can use to connect to the Management API.

To use the Management API, you first need to get an access token called the *Auth0 Management API Token*. This token is used to **authorize your application to access the Management API**. As you'll see soon, whenever you make a request to the API, you'll send this token along with it, and the Auth0 server will check that it's valid.

You can get this token straight from the dashboard so that you can immediately experiment with the API. This method is for testing only. Let's play around with the API this way first, and then you'll generate an API access token on the fly from your own application afterward.

## Get a Token from the Dashboard

Make sure you're still on the Auth0 Management API page and click on "**API Explorer**" from there. Next, click the blue button that says "**CREATE & AUTHORIZE TEST APPLICATION**". A test access token will then be generated for you. Copy this token and head to the [Auth0 Management API Explorer](https://auth0.com/docs/api/management/v2). In the top left corner, you should see a button that says "**SET API TOKEN**." Click on this, paste your token in, and click "Set Token."

![Auth0 Management API explorer](https://images.ctfassets.net/23aumh6u8s0i/5DOSy4hJXfauYKGrRojrbv/31ba756ff4cdf854c3f9c7a848c755cc/auth0-api-explorer)

The API explorer provides a convenient way to test out any API calls that you might need to use once you start working on your application. You can scroll through the API Reference in the left menu to see everything you can do with the Management API.

Go ahead and test out one of the requests you'll be making in this tutorial. Scroll down to [List or search users](https://auth0.com/docs/api/management/v2#!/Users/get_users). You'll see some documentation and optional parameters that you can use to build your request. Just leave all of these blank for now and press the blue button that says "Try" (you'll have to scroll down a bit).

The response will be an array of objects, where each object contains information about an individual user such as name, email, number of logins, when their account was created, and more.

![Auth0 management API explorer - get all users](https://images.ctfassets.net/23aumh6u8s0i/2wnwGQAykgydsRq9lgi8WT/4c7f5a42fa1c3049ed5587ab1ee85620/auth0-management-api-explorer)

Feel free to experiment with the Management API here. You can always get a new token from the dashboard whenever yours expires.

## Setup to Get a Token Programmatically

Since the point of this tutorial is to streamline some of this user management process, you're going to want to be able to **automatically generate** a new Auth0 Management API Token straight from your application.

To do this, you need to connect your client application to the Auth0 Management API in the dashboard so that it knows who it's issuing an access token to. In this case, **the client application is your Express API**.

> Note: If you're scratching your head wondering how an Express application is the client, don't worry, you're not alone. It seems strange, but Express is the client in relation to the Auth0 Management API. Your Express application will be the one requesting access to a resource from the Management API.

Make sure you're still on the Auth0 Management API page [in the Auth0 dashboard](https://manage.auth0.com/dashboard/) and click on "**Machine to Machine Applications**". Click on the switch next to "**Vue Express API**" or whatever you named your Express API when you set it up in Auth0 from the [Vue and Express Events app repository README](https://github.com/auth0-blog/vue-express-auth). It should now be green and say "Authorized."

![Auth0 Management API authorized client](https://images.ctfassets.net/23aumh6u8s0i/3bnn4TcXg4JJ6Ti42f4ymi/1545602b9f43d8c6dcfafda536730d27/auth0-management-api-authorized)

You'll also need to add permissions to this application, so go ahead and handle that now. Click on the down arrow `V` next to the authorized switch. For the purpose of this application, select `read:users`, `delete:users`, and `read:user_idp_tokens` and then click "Update".

* `read:users` &mdash; Read your Auth0 application's users
* `delete:users` &mdash; Delete your Auth0 application's users
* `read:user_idp_tokens` &mdash; Read the [identity provider](https://auth0.com/docs/identityproviders) access token

If you scroll back up, you'll see a tab titled "**Test**" next to "**Machine to Machine Applications**". Click on "**Test**", and you should see your API in the dropdown right underneath "Asking Auth0 for tokens from my application". Select the "**Vue Express API**" and then click on "**Node.JS**" underneath it. This will give you the code for the API call that will allow the Express API to request a token from the Auth0 Management API.

Leave this page open, as you'll be using it in the next section.

<include src="tutorial/NextButton" nextPart="build-an-admin-dashboard-with-express-and-vue-creating-the-backend/" completedMessage="I've set up my application in the Auth0 dashboard"/>

<include src="tutorial/IssueButton" communityTopic="53302"/>


Build an Admin Dashboard with Express and Vue

ramiro

I am an internet guy who loves reading and asking questions—those are the two things that helped me the most as an autodidact 🤓. If I am not learning about the latest trends in digital marketing or listening to house music, you can probably find me watching a tennis tournament. And also, I manage Social Media at Auth0 ✌️

Manager, Social Media

Ramiro Nunez Dosio

Our 10 most-popular identity posts in 2018 ranging from auth standards to web authentication.



Time flies when you are having fun. It's December already and we are getting ready to wrap up this year. 2018 was a prolific year for the Auth0 blog: we published more than 200 posts (😱) where we tackled a diverse amount of topics: frontend and backend technologies, data breaches, GDPR, Cybersecurity, Company Culture, and of course, Identity.

We believe looking back is key to look ahead. That is why this week, we are going to take a look back at the best and most impactful posts we have published in 2018.

One article wouldn't be enough to review this amazing year, that's why we have decided to split this year in review into 3 parts: [Developer Posts](https://auth0.com/blog/10-most-popular-developer-posts-in-2018/), [Security Posts](https://auth0.com/blog/10-most-popular-security-posts-in-2018/), and Identity Posts.

Without much further ado, here's the roundup of our 10 most-popular Identity posts this year!

![Auth0's 10 Most-Popular Identity Posts](https://images.ctfassets.net/23aumh6u8s0i/2PZojrBsthRTB6sKxDI0nw/cf5db7303eafa89f7ef46b4bc5f05e81/identity-posts)

## Auth0's 10 Most-Popular Identity Posts in 2018

> The following posts are not listed in any particular order.

1. <a href="#an-overview-of-open-standards" target="_self">An Overview of Open Standards</a>
2. <a href="#3-iam-examples-to-support-digital-transformation" target="_self">3 IAM Examples to Support Digital Transformation</a>
3. <a href="#a-look-at-the-draft-for-jwt-best-current-practices" target="_self">A Look at The Draft for JWT Best Current Practices</a>
4. <a href="#introduction-to-web-authentication-the-new-w3c-spec" target="_self">Introduction to Web Authentication: The New W3C Spec</a>
5. <a href="#how-to-have-a-successful-idm-project" target="_self">How To Have a Successful IDM Project</a>
6. <a href="#how-to-have-a-successful-idm-project-part-2" target="_self">How To Have a Successful IDM Project (Part 2)</a>
7. <a href="#on-the-nature-of-oauth2s-scopes" target="_self">On The Nature of OAuth2’s Scopes</a>
8. <a href="#hashing-passwords-one-way-road-to-security" target="_self">Hashing Passwords: One-Way Road to Security</a>
9. <a href="#adding-salt-to-hashing-a-better-way-to-store-passwords" target="_self">Adding Salt to Hashing: A Better Way to Store Passwords</a>
10. <a href="#how-utilities-can-use-ciam-to-avoid-3-common-problems" target="_self">How Utilities Can Use CIAM to Avoid 3 Common Problems</a>

## <a name="an-overview-of-open-standards"></a>1. [An Overview of Open Standards](https://auth0.com/blog/an-overview-of-open-standards/)

In this overview, we will go over what open standards are and why they matter. We will also go over the top open standards used for identity including OAuth 2, OpenID Connect, JWT, and SAML. Open standards are important to understand but one can easily get overwhelmed by the technical specifications.

<include src="ClickImg" externalUrl="https://auth0.com/blog/an-overview-of-open-standards/" imgUrl="https://cdn.auth0.com/blog/10-most-popular-identity-posts-in-2018/open-certificationpng.png" altText="Open Certification" imgWidth="560" imgHeight="560"/>

## <a name="3-iam-examples-to-support-digital-transformation"></a>2. [3 IAM Examples to Support Digital Transformation](https://auth0.com/blog/3-iam-examples-to-support-digital-transformation/)

From basic website authentication to implementing an OpenID Connect server and API authentication: This article covers 3 IAM examples to support your Digital Transformation.

<include src="ClickImg" externalUrl="https://auth0.com/blog/3-iam-examples-to-support-digital-transformation/" imgUrl="https://cdn.auth0.com/blog/iam-digital-transform/sso-data-model.png" altText="SSO Data Model" imgWidth="714" imgHeight="559"/>

## <a name="a-look-at-the-draft-for-jwt-best-current-practices"></a>3. [A Look at The Draft for JWT Best Current Practices](https://auth0.com/blog/a-look-at-the-latest-draft-for-jwt-bcp/)

In this post, we will take a look at the draft for the JWT Best Current Practices document. This document describes common pitfalls and attacks related to the use of JWTs, and how to implement mitigations against them. Read on!

<include src="ClickImg" externalUrl="https://auth0.com/blog/a-look-at-the-latest-draft-for-jwt-bcp/" imgUrl="https://cdn.auth0.com/blog/jwt-bcp/Substitution-Attack-Different-Recipient.png" altText="Different Recipient JWT Substitution Attack" imgWidth="590" imgHeight="492"/>

## <a name="introduction-to-web-authentication-the-new-w3c-spec"></a>4. [Introduction to Web Authentication: The New W3C Spec](https://auth0.com/blog/introduction-to-web-authentication/)

Web Authentication brings a stronger authentication mechanism to the masses by defining an API that both authenticators and web browsers can implement. Learn why Google, Paypal, Mozilla, and others back it up.

<include src="ClickImg" externalUrl="https://auth0.com/blog/introduction-to-web-authentication/" imgUrl="https://cdn.auth0.com/blog/webauthn/1-Web-Authentication-Entities.png" altText="Web Authentication Entities" imgWidth="617" imgHeight="409"/>

## <a name="how-to-have-a-successful-idm-project"></a>5. [How To Have a Successful IDM Project](https://auth0.com/blog/how-to-have-a-successful-idm-project/)

Learn how to create a realistic project plan to have a good Identity Management project deployment.

<include src="ClickImg" externalUrl="https://auth0.com/blog/how-to-have-a-successful-idm-project/" imgUrl="https://cdn.auth0.com/blog/good-idm-project/enabling-mfa.png" altText="Eanbling Multi-factor Authentication (MFA) from Auth0" imgWidth="617" imgHeight="361"/>

## <a name="how-to-have-a-successful-idm-project-part-2"></a>6. [How To Have a Successful IDM Project (Part 2)](https://auth0.com/blog/how-to-have-a-successful-idm-project-part-2/)

Learn how to plan for failures and changes in your identity project.

<include src="ClickImg" externalUrl="https://auth0.com/blog/how-to-have-a-successful-idm-project-part-2/" imgUrl="https://cdn.auth0.com/blog/how-to-have-a-successful-idm-project-part-2/resetting-a-users-multi-factor-account-with-auth0.png" altText="Resetting a user's multi-factor account" imgWidth="617" imgHeight="439"/>

## <a name="on-the-nature-of-oauth2s-scopes"></a>7. [On The Nature of OAuth2’s Scopes](https://auth0.com/blog/on-the-nature-of-oauth2-scopes/)

Auth0 Principal Architect and Identity expert Vittorio Bertocci on why using OAuth2 scopes in every authorization scenario is not a good idea.

<include src="ClickImg" externalUrl="https://auth0.com/blog/on-the-nature-of-oauth2-scopes/" imgUrl="https://cdn.auth0.com/blog/on-the-nature-of-oauth2-scopes/oauth2-scopes-mail-api.png" altText="OAuth2 Scopes Mail API exmaple" imgWidth="617" imgHeight="280"/>

## <a name="hashing-passwords-one-way-road-to-security"></a>8. [Hashing Passwords: One-Way Road to Security](https://auth0.com/blog/hashing-passwords-one-way-road-to-security/)

A strong password storage strategy is critical to mitigating data breaches that put the reputation of any organization in danger. Hashing is the foundation of secure password storage.

<include src="ClickImg" externalUrl="https://auth0.com/blog/hashing-passwords-one-way-road-to-security/" imgUrl="https://cdn.auth0.com/blog/hashing-one-way-road-to-security/hash-flow.png" altText="Hashing algorithm flow example - one-way" imgWidth="617" imgHeight="340"/>

## <a name="adding-salt-to-hashing-a-better-way-to-store-passwords"></a>9. [Adding Salt to Hashing: A Better Way to Store Passwords](https://auth0.com/blog/adding-salt-to-hashing-a-better-way-to-store-passwords/)

A salt is added to the hashing process to force their uniqueness, increase their complexity without increasing user requirements, and to mitigate password attacks like rainbow tables

<include src="ClickImg" externalUrl="https://auth0.com/blog/adding-salt-to-hashing-a-better-way-to-store-passwords/" imgUrl="https://cdn.auth0.com/blog/adding-salt-to-hashing-a-better-way-to-store-passwords/password-salt-example.png" altText="Example showing how using a salt with hashing produces unique hashes." imgWidth="617" imgHeight="277"/>

## <a name="how-utilities-can-use-ciam-to-avoid-3-common-problems"></a>10. [How Utilities Can Use CIAM to Avoid 3 Common Problems](https://auth0.com/blog/how-utilities-can-use-ciam-to-avoid-3-common-problems/)

Customer identity and management technology helps utilities reshape how they interact with users, improve their services, and tighten security.

<include src="ClickImg" externalUrl="https://auth0.com/blog/how-utilities-can-use-ciam-to-avoid-3-common-problems/" imgUrl="https://cdn.auth0.com/blog/how-utilities-can-use-ciam-to-avoid-3-common-problems/progressive-profiling-flow.png" altText="Utility customer progressive profiling flow" imgWidth="617" imgHeight="303"/>

## What's Next?

We are already preparing our content pipeline for 2019. Identity and digital transformation are key areas that will keep businesses evolving to tackle challenges around privacy, usability, growth, and sociopolitical policies. We are committed to keep our content relevant to these changes and offer effective solutions through our products and services.

We'd like to take this opportunity to thank all of our readers for their consistent support and feedback. Is there anything that you'd like us to cover in 2019? Any particular identity topic or trend? Please let us know in the comments below or through social media ([Twitter](https://twitter.com/auth0), [LinkedIn](https://www.linkedin.com/company/auth0)). As always, you can subscribe to our newsletter to receive a weekly digest of our blog content.

Happy Holiday Season!

<include src="asides/AboutAuth0" />


10 Most-Popular Identity Posts in 2018

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

Damian Schenkelman

Damian was one of Auth0's earliest employees. He loves building products for developers and taking things from 0 to 1.
<br><br>
He played key roles in implementing product features and growing the engineering organization in the early stages, and later on defining Auth0's architecture for scale and creating new products. Today he helps shape Auth0's long term strategy and leads Auth0Lab, a small and amazing team doing research and development of forward-looking products.
<br><br>
He spends his spare time with family, and friends, exercising, and catching up on all things NBA.

VP R&D (Auth0Lab)

Learn how to add JWT API keys to a DenyList so they are no longer valid.

**tl;dr**: If you understand why and how to support blacklisting JWTs, then skip to the [code](#impl).

In a [previous post](https://auth0.com/blog/2014/12/02/using-json-web-tokens-as-api-keys/), we proposed an approach to using [JSON Web Tokens](https://auth0.com/learn/json-web-tokens/) as API Keys, going over some of the benefits of doing so and also providing some examples based on our [API v2 scenarios](https://auth0.com/docs/apiv2). This post follows up by explaining an aspect that was not covered before: how to add JWT API keys to a DenyList so they are no longer valid.

If you need an in-depth introduction to **JSON Web Tokens**, check out the **free** ebook below.

<include src="ebook-ads/JwtHandbook" />

## A Real World Example
Let's for a second assume that GitHub used JSON Web Tokens as API Keys and one of them was accidentally published on the web. You would want to make sure an app can no longer access your information by revoking that token:

<a href="https://images.ctfassets.net/23aumh6u8s0i/3FcfGQTrWrTXz2L7aOrTQJ/4b7e1f65761e5d45e6613534b5cd953b/blacklist_token.png" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/3FcfGQTrWrTXz2L7aOrTQJ/4b7e1f65761e5d45e6613534b5cd953b/blacklist_token.png"/></a>

## Framing the Problem
Providing support for blacklisting JWTs poses the following questions:

1. How are JWTs individually identified?
2. Who should be able to revoke JWTs?
3. How are tokens revoked?
4. How do we avoid adding overhead?

This blog post aims to answer the previous questions by leveraging our experience from implementing this feature in our [API v2](https://docs.auth0.com/apiv2).



### 1. How are JWTs individually identified?

To revoke a JWT we need to be able to tell one token apart from another one. The JWT spec proposes the [`jti`](http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html#jtiDef) (JWT ID) as a means to identify a token. From the specification:
> The jti (JWT ID) claim provides a unique identifier for the JWT. The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object; if the application uses multiple issuers, collisions MUST be prevented among values produced by different issuers as well.

As a quick reminder, this is how the claims section of one of our JWT API tokens looks like:
<a href="https://images.ctfassets.net/23aumh6u8s0i/42R0pKeDgBxWfnogCtEQnZ/75b06ae9b03c6121e8a0b9b39c21251f/jwt_blacklist_01.png" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/42R0pKeDgBxWfnogCtEQnZ/75b06ae9b03c6121e8a0b9b39c21251f/jwt_blacklist_01.png"/></a>

The tokens accepted by our API use the `aud` claim to determine the tenant for which the JWT is valid. If we use the `(aud, jti)` pair as the token's identifier then each tenant is in charge of guaranteeing that there's no duplication among their tokens.

Similarly, if a token does not include the `jti` claim we do not allow it to be revoked.

### 2. Who should be able to revoke JWTs?

If anyone could revoke our API keys then unfortunately they wouldn't be of much use. We need a way of restricting who can revoke a JWT.

<include src="TweetQuote" quoteText="If anyone could revoke our API keys then unfortunately they wouldn't be of much use."/>

The way we solved it in our API is by defining a specific scope (permission) that allows blacklisting tokens. If you generate a JWT like the one shown in the next figure you will be able to revoke JWTs:
<a href="https://images.ctfassets.net/23aumh6u8s0i/2tovQjfBsagwVFQAchw6JV/790bee0566e203e69fd071955369a456/jwt_blacklist_02.png" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/2tovQjfBsagwVFQAchw6JV/790bee0566e203e69fd071955369a456/jwt_blacklist_02.png"/></a>

> Notice the `blacklist` action nested inside the `scopes` object.

### 3. How are tokens revoked?

To blacklist/revoke a token, you need a JWT API key (referred to as `JWT_API_KEY`) like the one described in #2. With it you can issue a `POST` request to `/api/v2/blacklists/tokens` as shown below (new lines added for clarity):

```
curl -H "Authorization: Bearer {JWT_API_KEY}"
-X POST
-H "Content-Type: application/json"
-d '{"aud":"u6nnAxGVjbBd8etXjj554YKGAG5HuVrp","jti":"test-token"}'
https://login.auth0.com/api/v2/blacklists/tokens
```

The complete documentation for the endpoint is [here](https://auth0.com/docs/apiv2#!/blacklists/post_tokens) but basically you need to:

* Send the `aud` and `jti` claims of the JWT to revoke.
* Send the JWT with the permissions necessary to blacklist tokens in the **Authorization** header.

To get the revoked tokens you can issue a `GET` to `/api/v2/blacklists/tokens`. You can use the [docs](https://auth0.com/docs/apiv2#!/blacklists/get_tokens) to figure out the how.

### 4. How do we avoid adding overhead?
You might be thinking:

> Wasn't the whole point of using JWTs avoiding a DB query?

Well, that is a benefit, though hardly the _whole point_. There is a caveat though: that question only applies if you have an application with a single issuer, not a multi-tenant system.

If there is more than one tenant, you don't want all of them to share the same secret. You still have to perform a database query to map the `aud` claim to the required `secret`.

With that in mind, these are some of the optimizations that you can implement:

* **Optimization 1**: The aforementioned operation involves I/O so it can be performed in parallel with our query to verify if a token has been revoked.

  > Of course, you can also add a caching layer with a reasonable expiration time to avoid the DB trips altogether.

* **Optimization 2**: Skip the expiration check if the `jti` claim is not part of the JWT.

* **Optimization 3**: To reduce the size of the revoked tokens store you could automatically remove JWTs from it once their [`exp`](http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html#expDef) is reached (assuming there is one).

<a name="impl"></a>
## Implementation
We have shipped version 1.3.0 of the open source [express-jwt](https://github.com/auth0/express-jwt) with support for [multi-tenancy](https://github.com/auth0/express-jwt#multi-tenancy) and [blacklisted tokens](https://github.com/auth0/express-jwt#revoked-tokens). We also put together a [sample](https://github.com/auth0/multitenant-jwt-auth) that shows everything working together. The sample is based on our [API v2](https://docs.auth0.com/apiv2) implementation.

The following code snippets use show the core sample parts:

### Securing the endpoint
The first thing we have is an API that we would like to protect. The `express-jwt` middleware is configured by providing:

* `secret` - A function in charge of retrieving the secret.
* `isRevoked` - A function in charge of checking if a JWT is revoked.

```javascript
var expressJwt = require('express-jwt');
// to protect /api routes with JWTs
app.use('/api', expressJwt({
  secret: secretCallback,
  isRevoked: isRevokedCallback
}));
```

### Handling multi-tenancy
The implementation for the `secretCallback` function reads the backing data store to retrieve the secret for a tenant.  It caches the secrets using the tenant identifier as the cache key.

If the data layer provides an encrypted tenant secret, it needs to be decrypted before calling `done`.

```javascript
var LRU = require('lru-cache');

var secretsCache = LRU({ /* options */ });

var secretCallback = function(req, payload, done){
  var audience = payload.aud;
  var cachedSecret = secretsCache.get(audience);

  if (cachedSecret) { return done(null, cachedSecret); }

  data.getTenantByIdentifier(audience, function(err, tenant){
    if (err) { return done(err); }
    if (!tenant) { return done(new Error('missing_secret')); }

    var secret = utilities.decrypt(tenant.secret);
    secretsCache.set(audience, secret);
    done(null, secret);
  });
};
```

### Supporting revoked JWTs
Similarly, the `isRevokedCallback` implementation caches whether a token is revoked or not using the `(aud, jti)` pair as the cache key. It also skips the check in case the `jti` claim is not present.

```javascript
var jtiCache = LRU({ /* options */ });

var isRevokedCallback = function(req, payload, done){
  var tokenId = payload.jti;
  if (!tokenId){
    // if it does not have jti it cannot be revoked
    return done(null, false);
  }

  var tokenIdentifier = payload.aud + ':' + payload.jti;
  var blacklisted = jtiCache.get(tokenIdentifier);
  if (typeof blacklisted !== 'undefined') { return done(null, blacklisted); }

  data.getRevokedTokenByIdentifier(tokenIdentifier, function(err, token){
    if (err) { return done(err); }
    blacklisted = !!token;
    jtiCache.set(tokenIdentifier,blacklisted)
    return done(null, blacklisted);
  });
};
```

## Conclusion
Most of the aforementioned content applies to blacklisting JWTs in general, not just JWT API keys.

Hopefully this blog post has provided some useful ideas on how to tackle this problem.

If you have any comments or questions don't hesitate to post them!

You an also get involved in [express-jwt](https://github.com/auth0/express-jwt)!
<iframe src="https://ghbtns.com/github-btn.html?user=auth0&amp;repo=express-jwt&amp;type=star&amp;count=true" frameborder="0" scrolling="0" width="170px" height="20px"></iframe>

<include src="asides/Jwt" />

Adding JSON Web Token API Keys to a DenyList

Most APIs today use an API Key to authenticate legitimate clients. API Keys are very simple to use from the consumer perspective:  You get an API key from the

Most APIs today use an **API Key** to authenticate legitimate clients. **API Keys** are very simple to use from the consumer perspective:

1. You get an **API key** from the service (in essence a shared secret).
2. Add the key to an `Authorization` header.
3. Call the API.

It can't get simpler than that, but this approach has some limitations.

The last couple of months, we've been working on our [API v2](https://docs.auth0.com/apiv2). We wanted to share what we've learnt implementing a more powerful security model using [JSON Web Tokens](http://jwt.io).



Using a JSON Web Token offers many advantages:

* **Granular Security**: API Keys provide an all-or-nothing access. JSON Web Tokens can provide much finer grained control.
* **Homogenous Auth Architecture**: Today we use cookies, API keys, home grown SSO solutions, OAuth etc. Standardizing on JSON Web Tokens gives you an homogenous token format across the board.
* **Decentralized Issuance**: API keys depend on a central storage and a service to issue them. JSON Web Tokens can be "self-issued" or be completely externalized, opening interesting scenarios as we will see below.
* **OAuth2 Compliance**: OAuth2 uses an opaque token that relies on a central storage. You can return a stateless JWT instead, with the allowed scopes and expiration.
* **Debuggability**: API keys are opaque random strings. JSON Web Tokens can be inspected.
* **Expiration Control**: API keys usually don't expire unless you revoke them. JSON Web Tokens can (and often do) have an expiration.
* **Devices**: You can't put an API key that has full access on a device, because what is on a phone or tablet can easily be stolen. But you can put a JWT with the right set of permissions.

If you'd like an in-depth introduction to **JSON Web Tokens**, check out our **free** ebook below.

<include src="ebook-ads/JwtHandbook" />

## Granular Security

One of the most interesting benefits of using JWTs is the first one listed above. Back in the old days, when databases were at the center of our client-server applications, we could create users with specific permissions on the database:

<a href="https://images.ctfassets.net/23aumh6u8s0i/2paJRM6vdAq4RO2k6ypich/b960d3ab0c364b327b2d4a2f1afc66c4/permissions-sql" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/s9tyvnrUrUjg7i39zWBOn/db84bd0b3a904e879c3484841d34cd1a/permissions-sql.png"/></a>

_Remember this?_

APIs are becoming central pieces of our distributed systems architecture. They are now the "gatekeepers" of our data. But in contrast with what was available in databases, virtually all API keys provide all-or-nothing access. Readers will likely be familiar with the `scope` parameter of OAuth2 based systems that offers this finer grained consent to access.

There are many situations in which you want to keep the simplicity of an **API Key** but only for a subset of all possible API operations.

[GitHub acknowledged this requirement](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) and now provides a way of creating a token with the scopes you need (mimicking the OAuth2 consent):

![](https://images.ctfassets.net/23aumh6u8s0i/6fdGKpvxjgD7seKbyvjb9O/4d82a5cb332aa836d93cb7e3044b5707/token_scopes)

In the next section, we will go through the details of how this can be implemented.

### How to implement it?

We don't know how GitHub implemented it (they probably used Ruby), but we will use it as an example. Let's say we want to implement an endpoint in the API to **create new repos**. You could model this with the following **JSON Web Token** payload. If you provide any of those scopes, then you can create repos:

```
{
  iat: 1416929109, // when the token was issued (seconds since epoch)
  jti: "aa7f8d0a95c", // a unique id for this token (for revocation purposes)
  scopes: ["repo", "public_repo"]  // what capabilities this token has
}
```
_Look at this token in <a href="http://jwt.io?value=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0MTY5MjkxMDksImp0aSI6ImFhN2Y4ZDBhOTVjIiwic2NvcGVzIjpbInJlcG8iLCJwdWJsaWNfcmVwbyJdfQ.XCEwpBGvOLma4TCoh36FU7XhUbcskygS81HE1uHLf0E" target="_blank">jwt.io</a>_

The API endpoint would simply check for the presence of the right **scope** atribute (this example is written in node.js but any language would work):

```
// intercept all calls to API and validae the token
app.use('/api', express_jwt({secret: SECRET, userProperty: 'token_payload'}));

// for POST /user/repo validate that there is a scope `repo` or `public_repo`
app.post('/api/user/repo',
        check_scopes(['repo', 'public_repo']),
        function(req, res, next) {
    // create a repo
    ....
});

```

Notice the `check_scopes` middleware on the `/api/user/repo` route. This is how the `check_scopes` function is implemented:

```
function check_scopes(scopes) {
  return function(req, res, next) {
    //
    // check if any of the scopes defined in the token,
    // is one of the scopes declared on check_scopes
    //
    var token = req.token_payload;
    for (var i =0; i<token.scopes.length; i++){
      for (var j=0; j<scopes.length; j++){
          if(scopes[j] === token.scopes[i]) return next();
      }
    }

    return res.send(401, 'insufficient scopes')
  }
}

```

> Notice that no one can change the scopes variables. JWTs are digitally signed, so its content cannot be tampered with.  

Documenting an API is equally important. What would be a good way for surfacing this on an API explorer?

For Auth0, we decided to build our own documentation using [swagger](http://swagger.io/). Since we are a multi-tenant system, each tenant has an API Key and Secret that is used to sign the token. As a developer, you mark which scopes you need and a token will be auto-generated. You can copy and paste it to [jwt.io](http://jwt.io) to see the structure (this is the __debuggable__ piece, by the way).

<a href="https://images.ctfassets.net/23aumh6u8s0i/33kBdPt5Hlzt2UEt0yoRQp/e7227bdb1d82dc16fed9a145dc64896b/api-explorer3" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/7uKm8Sq6OiHUEs5v9AoKT7/3550cf71dfa93c43bbd0eb2b2b2c2191/api-explorer3.gif"/></a>

Scopes required by each operation are clearly identified:

<a href="https://images.ctfassets.net/23aumh6u8s0i/4FDPqZmzwJWGdg9YGSUcEf/5f6ecef62c9d7f3ae0f64edad904a3a1/api-scopes2" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/4FDPqZmzwJWGdg9YGSUcEf/5f6ecef62c9d7f3ae0f64edad904a3a1/api-scopes2"/></a>

Our token format is a bit different from the one in the example we showed for GitHub. The good thing about JWTs is that they can contain _any_ data structure:

```
{
  iat: 1416929061,
  jti: "802057ff9b5b4eb7fbb8856b6eb2cc5b",
  scopes: {
    users: {
      actions: ['read', 'create']
    },
    users_app_metadata: {
      actions: ['read', 'create']
    }
  }
}
```

The string representation of the scope is `read:users` but in the JSON Web Token, we are using a more structured representation (note the hierarchy), this allows us to be more consistent. It also allows us to have an easy way to extend it for other scenarios.

## Conclusion & Resources

We have shown a new way of securing APIs based on JSON Web Tokens. This approach has some interesting benefits, in particular around _granular security_. In future posts we will go over other aspects, starting with how to revoke tokens.

Below are some of the resources that we used in our node.js backend implementation:

* The [hapi.js](http://hapijs.com) framework to create the API.
* A [fork](https://github.com/auth0/hapi-auth-jwt) of [hapi-auth-jwt](https://github.com/ryanfitz/hapi-auth-jwt) with [support for multitenant apps](https://github.com/ryanfitz/hapi-auth-jwt/pull/10) to handle authentication with JWTs.
* The awesome [ratify](https://github.com/mac-/ratify) library to both validate API input using [JSON schemas](http://json-schema.org) and automatically generate [swagger](http://swagger.io/) from said schemas for our docs.
* Swagger's support for arbitrary [authorizations objects](https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md#514-authorizations-object) and a slightly [customized swagger-ui template](https://github.com/swagger-api/swagger-ui#customize) to render the scopes per operation.

If you want to see an example of this working, you can check out our API v2: <https://docs.auth0.com/apiv2>

We would love to hear your thoughts about this approach!

[Discuss here](https://ask.auth0.com/t/using-json-web-tokens-as-api-keys/357)

<include src="asides/Jwt" />

"scopes"