Protect your API endpoints

Add a layer of authorization to your web services with Okta API Access Management.

---

Learning outcomes

• Configure a web API to use Okta
• Define which endpoints require authorization and which don't
• Enable Cross-Origin Resource Sharing (CORS) for the API
• Test the API is secure

What you need

• An Okta Developer Edition org (opens new window)
• Postman (opens new window) to test the API

• A copy of Visual Studio Community, Professional or Enterprise 2019 version 16.4 or later.

Sample code

.NET Core 3.x API Quickstart Sample Code (opens new window)

Note: Several standalone tools can send requests to APIs and allow you to inspect the responses. Our documentation uses Postman and offers Postman Collections to test its APIs more efficiently with a GUI. It also includes HTTP requests as text for those who prefer to use a terminal utility such as cURL (opens new window).

---

Overview

Background services and third-party APIs that access your APIs require the same levels of authentication and authorization (opens new window) as users who access your web apps. However, a machine-to-machine sign-in flow is silent and requires no user interaction. Use Okta to grant the correct level of access to your APIs on your behalf.

This quickstart contains the following tasks:

1. Check that API Access Management is enabled
2. Create and configure a new web API to use Okta
3. Configure different levels of access for different endpoints
4. Enable CORS for your API
5. Test your API is secure

Tip: You need your Okta org domain to follow this tutorial. It looks like dev-123456.okta.com. See Find your Okta domain. Where you see {yourOktaDomain} in this guide, replace it with your Okta domain.

Note: For a similar use case where Okta secures a machine-to-machine sign-in flow between a background service app and the Okta APIs, rather than a service app and your own API, see Implement OAuth for Okta with a service app

Check that API Access Management is enabled

API Access Management (API AM) is the feature in your org that allows Okta to secure your APIs. When enabled, API AM allows you to create an authorization server that establishes a security boundary for your APIs. All new developer orgs have API AM enabled by default, but it’s optional for production orgs. Check that it’s enabled in your org as follows:

1. Open the Admin Console for your org.
   1. Sign in to your Okta organization (opens new window) with your administrator account.
   2. Click Admin in the upper-right corner of the page.
2. Go to Security > API to view the API AM area.

If no Authorization Servers tab exists, API AM isn’t enabled in your org. Contact your support team to enable this feature in your org or create an Okta Developer Edition org (opens new window).

Note your authorization server name and audience

This tutorial uses the default custom authorization server to secure your API. Make a note of its name and audience value to configure your API:

1. From the API AM area in the Admin Console, select the Authorization Servers tab.
2. Go to the entry for the default server and make a note of two values.
   • Audience: api://default.
   • Authorization Server Name: default.

Where you see {yourAudience} and {yourAuthServerName} in this guide, replace with api://default and default, respectively.

Note: You can either create a custom authorization server or use the default to protect your APIs. In either case, you need an appropriate license to use them in production. If you're using a custom authorization server other than default, you must use the id of the authorization server rather than the name.

For further information, see Authorization servers.

Create and configure a new web API to use Okta

Now that you have an authorization server and noted how to identify it, complete the following steps:

1. Create an API project.
2. Add the required packages to your project.
3. Configure your API to use Okta.
4. Create two endpoints to secure.

Create an API project

Create an empty API project in Visual Studio with the ASP.NET Core Web API project template.

1. Launch Visual Studio.
2. Select File > New > Project > ASP.NET Core Web API, and click Next.
3. Enter a Project name, and click Next.
4. Select .NET Core 3.1 as the Framework.
5. Ensure that Authentication is None. (Don't worry, Okta handles this part.)
6. Ensure that Configure for HTTPS is selected.
7. Click Create.

Alternatively, you can create a project with the .NET CLI:

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

Add the required packages to your project

The Okta.AspNetCore (opens new window) library enables communication between Okta and your API. Install the latest version of Okta.AspNetCore (opens new window) in your project with the NuGet Package Manager:

1. Right-click your project in the Solution Explorer and select Manage NuGet Packages.
2. Click Browse and search for the package that you want to install: Okta.AspNetCore.
3. Select your package and click Install.

Or, you can install the dependency with the .NET CLI:

dotnet add package Okta.AspNetCore

Note: All Okta .NET libraries are hosted on NuGet (opens new window).

Configure your API to use Okta

Earlier you noted your authorization server name and audience. Add these and your Okta domain to your API's configuration.

1. Open appsettings.json and add the following as a top-level node, replacing the placeholders with your own values.

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

   Note: If you're using a custom authorization server other than default, use the authorization server id in place of the {yourAuthServerName} placeholder. For example, ausjs4mxguGY4DImf136. See List all authorization servers (opens new window).

2. You must also configure your API to use Okta for authorization and authentication.

   1. Open Startup.cs and add the following using statements at the top:

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

   2. Replace the existing ConfigureServices method with the following:

      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();
      }
      

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

      app.UseAuthentication();
      

Create two endpoints to secure

Create two endpoints in your project 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. Create an empty API controller named InfoController.cs in the Controllers folder.

   1. Right-click the Controllers folder in Solution Explorer and select Add > Controller...
   2. Select API Controller - Empty, and then click Add.
   3. Enter the name InfoController.cs, and then click Add.

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

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

3. Replace the existing InfoController class with the following code:

   [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 different levels of access for different endpoints

In many APIs, all endpoints require authorization. There may be a mix of protected and unprotected endpoints in others. These examples show you how to assign protected and unprotected access to an endpoint.

Require authorization for all endpoints

Add an authorization policy to the ConfigureServices method in Startup.cs to require authentication for all actions:

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

Configure access on a per-route basis to allow a mix of protected and anonymous endpoints.

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()...

Enable CORS for your API

Enable Cross-Origin Resource Sharing (CORS) (opens new window) only if the API is being called from an app or API hosted on a different domain. For example, if your API is hosted on api.example.com while your app is accessing it from example.com, you must 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 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
   

Test that your API is secure

You can now test if your endpoint security works as intended. To do this, complete the following steps:

1. Create an API services integration to represent another machine or service attempting to make requests to the API.
2. Create a custom scope for the API for the authorization server to assign to the API integration.
3. Run your API.
4. Use Postman (opens new window) to
   1. Request an access token for the API.
   2. Query both the \hello and \whoami endpoints.

Create an API Services integration

When another machine or service (rather than users) consumes an API, it uses the Client Credentials flow (opens new window) to identify itself and request an access token. Create an API services integration that has this flow enabled.

1. Open the Admin Console for your org.
2. Go to Applications > Applications to view the current app integrations.
3. Click Create App Integration.
4. Select API Services as the Sign-in method, and click Next.
5. Enter an integration name, and click Save.

The configuration page for the new API services integration appears. Make a note of two values that you use to request your access token:

• Client ID: Found on the General tab in the Client Credentials section.
• Client Secret: Found on the General tab in the Client Credentials section.

Moving on, where you see {yourClientId} and {yourClientSecret} in this guide, replace them with your client ID and client secret.

Create a custom scope for the API

Scope is a way to limit an app's access to your API. An access token must include a list of the scopes an app integration can perform. Create a custom scope to query both endpoints for the API.

1. Go to Security > API to view the API AM area.
2. Select the Authorization Servers tab.
3. Go to the entry for the default server and click its name.
4. Select the Scopes tab and click Add Scope.
5. Enter a name for the scope. For example, "AccessAll".
6. Click Create.
7. Ensure that the table contains the new scope.

Run Your API

Now, start your server to get your API running.

There are two options:

• Click Play in Visual Studio to run your API in a web browser.
• Call dotnet run in a terminal window.

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

Test with Postman

Start Postman if it's not open already. First, you request an access token from Okta and then check your APIs are protected correctly.

Request an access token for the API

Make an HTTP POST request to /token (opens new window) using the client ID and secret you noted earlier.

1. Select + in the Postman workbench to open a new request tab.

2. Select GET and change it to POST.

3. Enter https://{yourOktaDomain}/oauth2/{yourAuthServerName}/v1/token for the URL.

   Note: If you're using a custom authorization server other than default, use the authorization server id in place of the {yourAuthServerName} placeholder.

4. In the Params tab, create two key-value pairs:

   1. Key: grant_type, Value: client_credentials
   2. Key: scope, Value: {yourCustomScope}

5. Select the Authorization tab, and then select Basic Auth for type.

6. Enter {yourClientId} for Username and {yourClientSecret} for Password.

7. Select the Headers tab and add two new headers:

   1. Name: Cache-Control and Value: no-cache
   2. Name: Content-Type and Value: application/x-www-form-urlencoded

8. Click Send to receive an access token.

   

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

Query the hello and whoami endpoints

Now you can test your secured API endpoints. First, test the \whoami endpoint, which requires authorization:

1. Select + in the Postman workbench to open a new request tab.
2. Enter

   https://localhost:44336/api/whoami

   for URL.
3. Select the Authorization tab, and then select the Bearer Token for type.
4. Enter the token that you received earlier for Token.
5. Click Send.
6. Ensure that you received a 200 OK response.
7. Select the Authorization tab, and then select No Auth for type.
8. Ensure that you received a 401 Unauthorized response.

Now test the hello endpoint that doesn't require authorization:

1. Select + in the Postman workbench to open a new request tab.
2. Enter

   https://localhost:44336/api/hello

   for URL.
3. Select the Authorization tab, and then select the Bearer Token for type.
4. Enter the token that you received earlier for Token.
5. Click Send.
6. Ensure that you received a 200 OK response.
7. Select the Authorization tab, and then select No Auth for type.
8. Ensure that you still receive a 200 OK response.

Next steps

Learn more about the concepts introduced in this guide:

• API Access Management
• Authorization servers
• OAuth 2.0 Client Credentials flow
• Test the Okta REST APIs using Postman
• Define your own custom OAuth 2.0 scopes, claims, and access policies to support authorization for your APIs.
• Customize tokens returned from Okta from custom claims

.NET-specific resources:

• Build a REST API with ASP.NET Web API (opens new window)
• Secure your .NET 6 Web API (opens new window)