Protect your API endpoints

Add authorization using Okta to protect your APIs. When you finish, you have a secure REST API application that validates incoming requests.

---

Learning outcomes

• Add Okta authorization (opens new window) to your API endpoints.
• Add dependencies and configure your API.
• Create an anonymous endpoint and restricted endpoint.
• Require authorization on protected routes.
• Make an HTTP request with and without a valid access token.

What you need

A custom authorization server to create and apply authorization policies to protect your APIs

Note: Okta's Developer Edition makes most key developer features available by default for testing purposes. Okta's API Access Management product — a requirement to use Custom Authorization Servers — is an optional add-on in production environments.

Sample code

Protected API sample (opens new window)

---

Set up Okta

Set up your developer account and Okta org. The Okta command-line interface (CLI) is the quickest way to do this. Alternatively, you can manually sign up for a developer account (opens new window).

1. Install Okta CLI (opens new window).
2. If you don't already have a free Okta developer account:

   1. Open your terminal.

   2. Run okta register, and enter your first name, last name, email address, and country.

   3. Click or tap Activate in the account activation email that is sent to the email address that you gave.

      Tip: If you don't receive the confirmation email sent as part of the creation process, check your spam filters for an email from noreply@okta.com

   4. Find your new domain and a link to set your password in the email:

      Your Okta Domain: https://dev-xxxxxxx.okta.com
      To set your password open this link:
      https://dev-xxxxxxx.okta.com/welcome/xrqyNKPCZcvxL1ouKUoh
      

   5. Set the password for your org by opening the link and following the instructions. Your Okta domain is returned, similar to the following:

      New Okta Account created!
      Your Okta Domain: https://dev-xxxxxxx.okta.com
      

   6. Make a note of your Okta domain. Use it wherever ${yourOktaDomain} appears in this guide.

Note: If you're using an existing org, verify that API Access Management is enabled: Open your Admin Console, go to Security > API, and verify that an Authorization Servers tab is present. If not, choose one of the following:

• Create a developer account and org with Okta CLI.
• Contact your support team to enable the feature in your org.

All accounts created with Okta CLI are developer accounts and have API Access Management enabled by default.

Create a REST API

Create a new application with a simple API endpoint to add authorization to.

Create a new API project

For this tutorial, we create a sample API from scratch using the Visual Studio ASP.NET Core Web API project template.

1. Launch Visual Studio 2022, select New Project > ASP.NET Core Web API, and click Next.
2. Name your project and click Next.
3. Select Framework as .NET Core 3.1, Authentication as None (Okta handles this part) and select Configure for HTTPS.
4. Click Create.

Alternatively you can create a new project from the command line using the dotnet CLI:

dotnet new webapi -o ${yourProjectName} --framework netcoreapp3.1

Note: This guide uses ASP.NET Core 3.1.

Note: We recomend using the latest .NET CLI (opens new window), even when using older framework versions.

Include the dependencies

The Okta.AspNetCore (opens new window) library enables your application to validate Okta access tokens. If you are working with an existing application and need lower-level access to validate access tokens see the JWT validation guide.

All of Okta's .NET libraries are hosted on NuGet (opens new window). Install the Okta.AspNetCore (opens new window) version 4.0.0 dependency in your project via the NuGet Package Manager:

1. In the Solution Explorer, right-click your project and select Manage Nuget Packages.
2. Click Browse and search for the package you want to install, for example, Okta.AspNetCore.
3. Select your package and click Add Package.

Alternatively, you can install the dependency through the dotnet CLI:

dotnet add package Okta.AspNetCore --version 4.0.0

Configure your API

You need to configure the API with some information about the authorization server used by your Okta organization.

Note: This tutorial uses the default custom authorization server to secure your protected API. You can create your own custom authorization server for this purpose. In either case, you need an appropriate license to use the custom authorization server in production.

Things you need

Our project uses information from the Okta organization we created earlier to configure communication with the API. You can find these values in the API section of the Admin Console: Select Security > API from the main menu.

There are three pieces of information you may need, depending on the platform you are using:

• Audience: api://default by default

• Authorization Server Name: default

• Okta Domain: Found in the global header located in the upper-right corner of the dashboard. Click the down arrow next to your email address and in the dropdown box that appears, move your pointer over the domain name. Click the Copy to clipboard icon that appears to copy the domain.

  Note: Your Okta domain is different from your admin domain. Your Okta domain doesn't include -admin, for example, https://dev-133337.okta.com.

1. Open your appsettings.json file and add the following manually as a top-level node (if you used the Okta CLI to create an app these values may already be configured with your account information).

   {
     "Okta": {
       "OktaDomain": "https://${yourOktaDomain}",
       "AuthorizationServerId": "${yourAuthServerName}",
       "Audience": "${yourAudience}"
     }
   }
   

2. Configure your API to use Okta for authorization and authentication. Open Startup.cs and add the following using statements at the top:

   using Okta.AspNetCore;
   using Microsoft.AspNetCore.Authorization;
   using Microsoft.AspNetCore.Mvc.Authorization;
   

3. Replace the existing ConfigureServices method with the following to include the Okta middleware configuration:

   public void ConfigureServices(IServiceCollection services)
   {
     services.AddAuthentication(options =>
     {
       options.DefaultAuthenticateScheme = OktaDefaults.ApiAuthenticationScheme;
       options.DefaultChallengeScheme = OktaDefaults.ApiAuthenticationScheme;
       options.DefaultSignInScheme = OktaDefaults.ApiAuthenticationScheme;
     })
     .AddOktaWebApi(new OktaWebApiOptions()
     {
       OktaDomain = Configuration["Okta:OktaDomain"],
       AuthorizationServerId = Configuration["Okta:AuthorizationServerId"],
       Audience = Configuration["Okta:Audience"]
     });
   
     services.AddAuthorization();
   
     services.AddControllers();
   }
   

4. In the Configure method, add the following line immediately above app.UseAuthorization();:

   app.UseAuthentication();
   

Create your REST endpoints

Create new REST endpoints in your application that cover two different use cases:

• api/whoami — A protected endpoint (access-restricted API)
• api/hello — An endpoint that anonymous users can access (unsecured API)

1. Add a new empty API controller class to the Controller folder named InfoController.

2. Add the following using statements to the top of the file:

   using Microsoft.AspNetCore.Authorization;
   using Microsoft.AspNetCore.Cors;
   using Microsoft.AspNetCore.Http;
   using Microsoft.AspNetCore.Mvc;
   using System.Collections.Generic;
   using System.Linq;
   using System.Security.Claims;
   

3. Create your secure and anonymous access API routes by replacing the existing InfoController class with the following:

   [ApiController]
   [Route("api")]
   public class InfoController : ControllerBase
   {
     // GET: api/whoami
     [HttpGet]
     [Route("whoami")]
     public Dictionary<string, string> GetAuthorized()
     {
       var principal = HttpContext.User.Identity as ClaimsIdentity;
       return principal.Claims
          .GroupBy(claim => claim.Type)
          .ToDictionary(claim => claim.Key, claim => claim.First().Value);
     }
   
     // GET: api/hello
     [HttpGet]
     [Route("hello")]
     public string GetAnonymous()
     {
       return "You are anonymous";
     }
   }
   

Configure required authentication

In many APIs, all of the endpoints require authorization. In others, there may be a mix of protected and unprotected (anonymous) endpoints. These examples show you how to do both.

Require authorization for everything

To require authentication for all actions, create an authorization policy in the Startup.cs class that you can use everywhere:

public void ConfigureServices(IServiceCollection services)
{

  services.AddAuthorization();

  services.AddMvc(o =>
  {
    var policy = new AuthorizationPolicyBuilder()
      .RequireAuthenticatedUser()
      .Build();
    o.Filters.Add(new AuthorizeFilter(policy));
  });
}

Allow anonymous access for specific routes

If you have endpoints that need to be accessed without any authorization, instead of securing the entire API like the previous section, you can configure access per route.

Add the [Authorize] and [AllowAnonymous] attributes to the REST endpoints created earlier.

// GET: api/whoami with authorization required
[Authorize]
[HttpGet]
[Route("whoami")]
public Dictionary<string, string> GetAuthorized()...

// GET: api/hello with anonymous access allowed
[AllowAnonymous]
[HttpGet]
[Route("hello")]
public string GetAnonymous()...

Configure CORS if necessary

Configuring Cross-Origin Resource Sharing (CORS) is only required if the API is being called from a browser app hosted on a different domain. For example, if you are hosting a single-page JavaScript app at example.com, which consumes an API endpoint hosted on api.example.com, you need to enable CORS.

1. Add CORS to the ConfigureServices method in Startup.cs

   services.AddCors(options =>
   {
      // The CORS policy is open for testing purposes. In a production application, you should restrict it to known origins.
      options.AddPolicy(
         "AllowAll",
         builder => builder.AllowAnyOrigin()
                           .AllowAnyMethod()
                           .AllowAnyHeader());
   });
   

2. Enable CORS in the the Configure method:

   app.UseCors();
   

3. Add the CORS attribute to your API controller:

   [EnableCors("AllowAll")] // Enables CORS for this route
   [ApiController]
   [Route("api")]
   public class InfoController : ControllerBase
   

Consume your secure API endpoints

Test your APIs with an access token that is sent to your endpoint for validation.

Use an access token with your API endpoint

In order for someone to make a request to your API, they need an access token. How an access token is obtained depends on the client making the request.

If your API is consumed from another machine or service (instead of users), you can follow the Client Credentials flow to create an access token. See Sign users in to your single-page app using the redirect model or Sign users in to your mobile app using the redirect model for instructions on how to retrieve an access token in those types of app.

Note: The information contained within an access token varies depending on the type of flow used to create it. For example, the Client Credentials flow doesn't contain any claims with user information such as a user ID or email.

If you are using Postman and the Client Credentials flow, you can use an API call of the form https://${yourOktaDomain}/oauth2/default/v1/token, with an Authorization header set, and you will get a response containing an access token.

Copy the value in the access_token object field and use it for testing your API in the next step.

Run your API

Start your server to get your API running.

Click Play in Visual Studio to run your API in a web browser.

Alternatively, use the command line:

dotnet run

Leave your API running locally (or deployed if desired) and proceed to the next step.

Send a request to your API endpoint using Postman

After your API is running locally, you need to test it. Using a tool like Postman or cURL, call your API endpoints to see the responses with and without your token.

https://localhost:44336/api/whoami
Authorization: Bearer ${TOKEN}

https://localhost:44336/api/hello

The expected results are as follows, provided you followed the instructions in the Allow anonymous access for specific routes section:

• api/whoami — 401 response without a valid token, 200 response with a valid token.
• api/hello — response with or without a valid token, due to anonymous access.

If you are using Postman, your GET call and response should look something like this:

Next steps

• Define your own custom OAuth 2.0 scopes, claims, and access policies to support authorization for your APIs.
• Learn more about validating access tokens
• Include custom claims in your token returned from Okta

ASP.NET-specific resources:

• Okta Xamarin SDK (opens new window)
• Okta .NET Management SDK (opens new window)
• Okta ASP.NET OIDC Middleware (opens new window)
• Blazor resources
• ASP.NET Framework SDK resources
• ASP.NET Core SDK resources
• Create a Web API with ASP.NET Core (opens new window)