ASP.NET Core Web API Authentication with HS256

Sample Project

Download this sample project configured with your Auth0 API Keys.

System Requirements
  • .NET Core 1.0
  • Visual Studio 2015 Update 3 (Optional)
  • Visual Studio Code (Optional)
Show requirements

Signing Algorithm

Auth0 can sign JSON Web Tokens (JWT) using either a symmetric key (HS256) or an asymmetric key (RS256). This document demonstrates how to use tokens signed with the HS256 Algorithm.

It is however recommended that you rather use RS256 tutorial.

1. Enable OAuth 2.0 API Authorization

To execute the steps in this tutorial, you will need to enable a flag under your Account Settings. This will allow you to opt-in and out of this feature at any point in time while it remains under preview.

  1. Open the Dashboard and browse to Account Settings -> Advanced.
  2. Scroll down to the Settings section and turn on the flag "OAuth 2.0 API Authorization (Preview)"

You will see that the API section is now displayed on your sidebar.

2. Create a Resource Server (API)

In the APIs section of the Auth0 Dashboard, click the Create API button. Provide a Name and Identifier for your API. Be sure to choose the HS256 signing algorithm.

Create API

After you have created the API, navigate to the Settings tab of the API, and take note of the API Identifier and Signing Secret, as it will be used configuring the JWT middleware.

3. Update your settings

When using HS256, you will need your API's Signing Secret when configuring the JWT middleware, so be sure update the appsettings.json file included in the seed project to also add an ApiSecret attribute with the value of the Signing Secret, and be sure to set the correct values for the Domain and ApiIdentifier attributes:

  "Auth0": {
    "Domain": "YOUR_AUTH0_DOMAIN",
    "ApiIdentifier": "YOUR_API_IDENTIFIER",
    "ApiSecret": "YOUR_API_SECRET"

4. Configure the JWT Middleware

You will need to add the JWT middleware to your application's middleware pipeline.

Go to the Configure method of your Startup class and add a call to UseJwtBearerAuthentication passing in the configured JwtBearerOptions. The JwtBearerOptions needs to specify your Auth0 Domain as the ValidIssuer, the API Identifier as the ValidAudience, and the Signing Secret as the IssuerSigningKey:

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)

    var options = new JwtBearerOptions
        TokenValidationParameters =
            ValidIssuer = $"https://{Configuration["Auth0:Domain"]}/",
            ValidAudience = Configuration["Auth0:ApiIdentifier"],
            IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(Configuration["Auth0:ApiSecret"]))


Do not forget the trailing backslash

Please ensure that the URL specified for ValidIssuer contains a trailing backslash as this needs to match exactly with the issuer claim of the JWT. This is a common misconfiguration error which will cause your API calls to not be authenticated correctly.

5. Securing an API endpoint

The JWT middleware integrates with the standard ASP.NET Core Authentication and Authorization mechanisms.

You only need to decorate your controller action with the [Authorize] attribute to secure an endpoint:

public class PingController : Controller
    public string PingSecured()
        return "All good. You only get this message if you are authenticated.";

6. Using your API

In order to make calls to your API, you will need to obtain an access_token. An access_token can be obtained in a number of ways, depending on the type of application you are building. These are referred to as authorization grant flows. Please see the API Authorization section for more information of the types of flows and to determine which one is most appropriate for your application.

Once you have obtained an access_token you can pass that along in the Authorization header of requests to your API as a Bearer token.

Here is a sample RAW request:

GET /api/ping/secure HTTP/1.1
Host: localhost:5000
Authorization: Bearer <your access_token>

Or using RestSharp:

var client = new RestClient("http://localhost:5000/api/ping/secure");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer <your access_token>");
IRestResponse response = client.Execute(request);

7. Testing your API in Postman

During development, you may want to test your API with Postman. If you make a request to the /ping/secure endpoint you will notice that the API returns an HTTP status code 401 (Unauthorized):

Unauthorized request in Postman

As mentioned in the previous step, you will need to pass along an access_token in the HTTP Authorization header. A quick and easy way to obtain an access_token for test purposes is from the Test tab of your API settings:

Obtain a JWT

You can then use the access_token and pass it along in the Authorization header as a Bearer token:

Authorized request in Postman

Use Auth0 for FREECreate free Account