Sign users in to your web app using the redirect model

Add authentication with Okta's redirect model (opens new window) to your server-side web app. This example uses Okta as the user store.

---

Learning outcomes

• Create an integration that represents your app in your Okta org.
• Add dependencies and configure your app to use Okta redirect authentication.
• Test user sign in flow.

Sample code

Quickstart sample app (opens new window)

---

Note: For single-page (browser) apps, see Sign users in to your SPA using the redirect model. For servers returning non-HTML API responses, see Protect your API endpoints.

Set up Okta

Set up your Okta org. The CLI is the quickest way to work with your Okta org, so we recommend using it for the first few steps. If you don't want to install the CLI, you can manually sign up for an org (opens new window) instead. We provide non-CLI instructions along with the CLI steps below.

1. Install the Okta command-line interface: Okta CLI (opens new window).

2. If you don't already have a free Okta developer account, create one by entering okta register on the command line.

3. Make a note of the Okta Domain as you need that later.

4. IMPORTANT: Set the password for your Okta developer org by opening the link that's shown after your domain is registered. Look for output similar to this:

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

   Note: 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.

5. Connect to your Okta developer org if you didn't create one in the last step (successfully creating an Okta org also signs you in) by running the following command. You need the URL of your org — which is your Okta domain with https:// prepended — and an API/access token.

   okta login
   

Create an Okta integration for your app

An application integration represents your app in your Okta org. The integration configures how your app integrates with the Okta services including: which users and groups have access, authentication policies, token refresh requirements, redirect URLs, and more. The integration includes configuration information required by the app to access Okta.

To create your app integration in Okta using the CLI:

1. Create the app integration by running:

   okta apps create web
   

2. Enter Quickstart when prompted for the app name.

3. Specify the required Redirect URI values:

   • Redirect URI: http://localhost:8080/authorization-code/callback
   • Logout Redirect URI: http://localhost:8080/signout/callback (you end up changing these later)

4. The Okta CLI creates an .okta.env file with export statements containing the Client ID, Client Secret, and Issuer. Keep this safe as you use it later to configure your web app.

At this point, you can move to the next step: Creating your app. If you want to set up the integration manually, or find out what the CLI just did for you, read on.

1. Sign in to your Okta organization (opens new window) with your administrator account.
2. Click the Admin button on the top right of the page.
3. Open the Applications configuration pane by selecting Applications > Applications.
4. Click Create App Integration.
5. Select a Sign-in method of OIDC - OpenID Connect, then click Next.
6. Select an Application type of Web Application, then click Next.

   Note: If you choose an inappropriate application type, it can break the sign-in or sign-out flows by requiring the verification of a client secret, which is something that public clients don't have.

7. Enter an App integration name.
8. Enter the Sign-in redirect URIs for local development, such as http://localhost:xxxx/authorization-code/callback.
9. Enter the Sign-out redirect URIs for both local development, such as http://localhost:xxxx/signout/callback. For more information on callback URIs, see Define callback route.
10. In the Assignments section, define the type of Controlled access for your app. Select the Everyone group for now. For more information, see the Assign app integrations (opens new window) topic in the Okta product documentation.
11. Click Save to create the app integration. The configuration pane for the integration opens after it's saved. Keep this pane open as you copy some values when configuring your app.

Create app

In this section you create a sample web app and add redirect authentication using your new app integration.

Create a new project

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

1. Launch Visual Studio 2022, select New project > ASP.NET Core Web App (Model-View-Controller), and click Next.
2. Name your project and click Next.
3. Select Framework as .NET Core 3.1, Authentication as None (don't worry, Okta handles this part) and select Configure for HTTPS.
4. Click Create.

Note: This guide uses .NET Core 3.1.

Note: If you're using the Okta CLI, you can also run okta start okta-dotnetcore3-webapp-quickstart to create an app. This command creates an OIDC app in Okta, downloads the okta-dotnetcore3-webapp-quickstart (opens new window) sample, and configures it to work with the OIDC app. This quickstart uses a basic .NET Core starter app instead, as it's easier to understand the Okta-specific additions if you work through them yourself.

Add packages

Add the required dependencies for using the Okta SDK with your web app.

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 through 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: Okta.AspNetCore.
3. Select your package and click Install.

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

dotnet add package Okta.AspNetCore --version 4.0.0

Configure your app

Our app uses information from the Okta integration that we created earlier to configure communication with the API: Client ID, Client Secret, and Issuer.

The Okta CLI created an .okta.env file in your current directory containing these values, for example:

export OKTA_OAUTH2_ISSUER=https://${yourOktaDomain}/oauth2/${authorizationServerId}
export OKTA_OAUTH2_CLIENT_ID=${clientId}
export OKTA_OAUTH2_CLIENT_SECRET=${clientSecret}

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

   "Okta": {
     "OktaDomain": "https://${yourOktaDomain}",
     "ClientId": "${clientId}",
     "ClientSecret": "${clientSecret}", "AuthorizationServerId": "default"
   }
   

2. You also need to configure your MVC app to enable cookies and OpenID Connect as the default protocol for authentication. Open Startup.cs and add the following using statements at the top:

   using Microsoft.AspNetCore.Authentication.Cookies;
   using Microsoft.AspNetCore.Authentication.OpenIdConnect;
   using Okta.AspNetCore;
   

3. Replace the existing ConfigureServices method with the following:

   public void ConfigureServices(IServiceCollection services)
   {
         services.ConfigureApplicationCookie(options =>
         {
             options.Cookie.HttpOnly = true;
             options.Cookie.SecurePolicy = Microsoft.AspNetCore.Http.CookieSecurePolicy.Always;
         })
         .AddAuthentication(options =>
     {
         options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
         options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
     })
     .AddCookie()
     .AddOktaMvc(new OktaMvcOptions
     {
           // Replace these values with your Okta configuration
           OktaDomain = Configuration.GetValue<string>("Okta:OktaDomain"),
           AuthorizationServerId = Configuration.GetValue<string>("Okta:AuthorizationServerId"),
       ClientId = Configuration.GetValue<string>("Okta:ClientId"),
       ClientSecret = Configuration.GetValue<string>("Okta:ClientSecret"),
       Scope = new List<string> { "openid", "profile", "email" },
     });
   
     services.AddControllersWithViews();
   }
   

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

   app.UseAuthentication();
   

Find your config values

If you don't have your configuration values handy, you can find them in the Admin Console (choose Applications > Applications and find the application integration that you created earlier):

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

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

• 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.

Redirect to the sign-in page

To authenticate a user, your web app redirects the browser to the Okta-hosted sign-in page. This usually happens from a sign-in action such as clicking a button or when a user visits a protected page.

1. By default, the redirect to the sign-in page happens automatically when users access a protected route. In Visual Studio, to create a universal sign-in link, expand Views > Shared and open your _Layout.cshtml file.

2. Insert the following code directly above <ul class="navbar-nav flex-grow-1>:

   @if (User.Identity.IsAuthenticated)
   {
     <ul class="nav navbar-nav navbar-right">
       <li><p class="navbar-text">Hello, @User.Identity.Name</p></li>
       <li><a class="nav-link" asp-controller="Home" asp-action="Profile" id="profile-button">Profile</a></li>
       <li>
         <form class="form-inline" asp-controller="Account" asp-action="SignOut" method="post">
           <button type="submit" class="nav-link btn btn-link text-dark" id="logout-button">Sign Out</button>
         </form>
       </li>
     </ul>
   }
     else
   {
     <ul class="nav navbar-nav navbar-right">
       <li><a asp-controller="Account" asp-action="SignIn" id="login-button">Sign In</a></li>
     </ul>
   }
   

3. Now you need to handle the Sign In click. Create an empty MVC Controller named AccountController in the Controllers folder.

4. Add the following using statements to the top of the controller:

   using Microsoft.AspNetCore.Authentication;
   using Microsoft.AspNetCore.Authentication.Cookies;
   using Okta.AspNetCore;
   

5. Add a new IActionResult for SignIn:

   public IActionResult SignIn()
   {
     if (!HttpContext.User.Identity.IsAuthenticated)
     {
       return Challenge(OktaDefaults.MvcAuthenticationScheme);
     }
   
     return RedirectToAction("Index", "Home");
   }
   

6. Add another IActionResult right below it for SignOut:

   [HttpPost]
   public IActionResult SignOut()
   {
   return new SignOutResult(
           new[]
           {
           OktaDefaults.MvcAuthenticationScheme,
           CookieAuthenticationDefaults.AuthenticationScheme,
           },
           new AuthenticationProperties { RedirectUri = "/Home/" });
   }
   

After successful authentication Okta redirects back to the app with an authorization code that's then exchanged for an ID and access token that you can use to confirm sign in status. Later we look at displaying some of the returned user information in the app.

Note: To customize the Okta sign-in form, see Style the Okta-hosted Sign-In Widget.

Define a callback route

To sign users in, your application redirects the browser to an Okta-hosted sign-in page. Okta then redirects back to your application with information about the user. You can learn more about how this works on Okta-hosted flows (opens new window).

Your web application must host a route that Okta sends information to when a user signs in. This route is called a callback route or redirect URI. The callback route isn't seen by the user, and it's not the user's final destination. It's just one step in the authentication redirect flow.

Similarly, when your web application contacts Okta to sign a user out, Okta redirects the browser to a sign-out redirect URI that the application must also host.

The Okta ASP.NET Core SDK configures and hosts these routes for you in your web app. By default, the sign-in route is hosted at /authorization-code/callback and the sign-out route is hosted at /signout/callback. You need to update the redirect URIs of your Okta app integration to reflect the development URLs that Visual Studio assigned to your app.

1. In Visual Studio, open Properties > launchSettings.json.

2. Make a note of the sslPort settings under iisExpress. In the example below, that's 44300.

   "iisSettings": {
     "windowsAuthentication": false,
     "anonymousAuthentication": true,
     "iisExpress": {
       "applicationUrl": "http://localhost:1544",
       "sslPort": 44300
     }
   }
   

3. Open the Okta Admin Console.

4. Select Applications > Applications from the left navigation.

5. Click the entry for your application integration.

6. Click Edit on the General tab.

7. Scroll down to the LOGIN section.

8. Edit the Sign-in redirect URIs to use the sslPort that you made note of earlier, for example https://localhost:44300/authorization-code/callback.

9. Edit the Sign-out redirect URIs to use the sslPort that you made note of earlier, for example https://localhost:44300/signout/callback

10. Click Save.

Get info about the user

After the user signs in, Okta returns some of their profile information to your app, such as those shown in the /userinfo response example. One use of this information is updating your user interface, for example to display the customer's name.

The default profile items (called claims) returned by Okta include the user's email address, name, and preferred username. The claims that you see may differ depending on the scopes requested by your app. See Configure your app.

ASP.NET Core automatically populates HttpContext.User with the information Okta sends back about the user. You can check whether the user is signed in with User.Identity.IsAuthenticated in your actions or views and see all of the user's claims in User.Claims.

1. Open up your HomeController and add this using statement:

   using Microsoft.AspNetCore.Authorization;
   

2. Add a new IActionResult called Profile to hand the claim data over to your View:

   [Authorize]
   public IActionResult Profile()
   {
     return View(HttpContext.User.Claims);
   }
   

3. Expand your Views folder, add a new empty Razor View named Profile.cshtml to the Home folder, and replace the contents of the new file with the following code:

   @model IEnumerable<System.Security.Claims.Claim>
   
   @{
       ViewBag.Title = "View claims";
   }
   
   <h2>@ViewBag.Title</h2>
   
   <dl class="dl-horizontal">
       @foreach (var claim in Model)
       {
           <dt title="@claim.Type">
               @claim.Type
               <button type="button"
                       class="btn btn-link btn-xs"
                       aria-label="Copy to clipboard"
                       title="Copy to clipboard"
                       data-clipboard-text="@claim.Value">
                   <span class="glyphicon glyphicon glyphicon-copy" aria-hidden="true"></span>
               </button>
           </dt>
   
           <dd id="claim-@String.Format("{0}", claim.Type)">@claim.Value</dd>
       }
   </dl>
   

Sign in a user

Test your integration by starting your server and signing in a user.

1. Run the project from Visual Studio. The browser loads the welcome page for your new app.
2. Click Sign In and you are redirected to Okta to complete the sign-in flow with OIDC.
3. After you have successfully signed in, click Profile and you should see a list of user information that came along with the ID token from Okta.

Note: If you are sign in as an administrator in the same browser already, it displays your name. You can open an incognito window and create a test user in the Admin Console to use if you want.

Configure required authentication

Your app can require authentication for the entire site or just for specific routes. Routes that don't require authentication are accessible without signing in, which is also called anonymous access.

Require authentication for everything

Some apps require user authentication for all routes, for example a company intranet.

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

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

Require authentication for a specific route

Your website may have a protected portion that is only available to authenticated users.

Use the [Authorize] attribute on controllers or actions to require a signed-in user:

[Authorize]
public IActionResult Protected()
{
    // Only for signed-in users!
    return View();
}

Allow anonymous access

Your website may enable anonymous access for some content but require a user to sign in for other content or to take some other action. For example, an ecommerce site might allow a user to browse anonymously and add items to a cart, but require a user to sign in for checkout and payment.

You can grant anonymous access for specific URLs by using [AllowAnonymous] on your route:

[AllowAnonymous]
public IActionResult PublicAccess()
{
    // For all users, even anonymous ones!
    return View();
}

Next steps

• Protect your API endpoints.
• Custom domain and email address (opens new window)
• Style the Okta-hosted Sign-In Widget.
• Sign users in to your mobile app using the redirect model
• Multi-tenant solutions (opens new window)

Okta Developer Blog:

• Add user authentication and Okta Resource Management to your ASP.NET Core app
• Secure your ASP.NET Core app with OAuth 2.0
• Web Forms migration to Blazor in .NET Core