ASP.NET (System.Web)

Sample Project

Download a sample project specific to this tutorial configured with your Auth0 API Keys.

System Requirements
  • Microsoft Visual Studio 2017
  • Auth0-ASPNET v2.1.0
Show requirements

Install the Auth0-ASPNET NuGet Package

Install the Auth0-ASPNET package. In the NuGet Package Manager, click Tools > Library package manager > Package Manager Console. In the console, run the command:

Install-Package Auth0-ASPNET

This package adds the LoginCallback.ashx file to your project to process the login.

Configure Callback URLs

After authenticating the user on Auth0, send a POST request to the /LoginCallback.ashx URL on your website, for example http://localhost:PORT/LoginCallback.ashx.

For security, register this URL in your Client Settings.

Callback URLs

Fill Web.Config With Your Auth0 Settings

The NuGet package creates three settings on <appSettings>. Replace them with the following settings:

<add key="auth0:ClientId" value="YOUR_CLIENT_ID" />
<add key="auth0:ClientSecret" value="YOUR_CLIENT_SECRET" />
<add key="auth0:Domain" value="YOUR_AUTH0_DOMAIN" />

Authenticate the User

To authenticate the user, redirect them to Auth0's /authorize endpoint:

// Controllers/AccountController.cs
public ActionResult Login(string returnUrl)
{
    var client = new AuthenticationApiClient(
        new Uri(string.Format("https://{0}", ConfigurationManager.AppSettings["auth0:Domain"])));


    var request = this.Request;
    var redirectUri = new UriBuilder(request.Url.Scheme, request.Url.Host, this.Request.Url.IsDefaultPort ? -1 : request.Url.Port, "LoginCallback.ashx");

    var authorizeUrlBuilder = client.BuildAuthorizationUrl()
        .WithClient(ConfigurationManager.AppSettings["auth0:ClientId"])
        .WithRedirectUrl(redirectUri.ToString())
        .WithResponseType(AuthorizationResponseType.Code)
        .WithScope("openid profile")
        // adding this audience will cause Auth0 to use the OIDC-Conformant pipeline
        // you don't need it if your client is flagged as OIDC-Conformant (Advance Settings | OAuth)
        .WithAudience("https://" + @ConfigurationManager.AppSettings["auth0:Domain"] + "/userinfo");

    if (!string.IsNullOrEmpty(returnUrl))
    {
        var state = "ru=" + HttpUtility.UrlEncode(returnUrl);
        authorizeUrlBuilder.WithState(state);
    }

    return new RedirectResult(authorizeUrlBuilder.Build().ToString());
}

Access User Information

When the user logs in to the application, a ClaimsPrincipal class is generated. You can access it through the Current property:

// Controllers/HomeController.cs
public ActionResult Index()
{
  string name = ClaimsPrincipal.Current.FindFirst("name")?.Value;
}

The user profile you receive is always a normalized user profile. The profile includes the following attributes:

  • name
  • nickname
  • picture
  • updated_at

For more information about the user profile, read the user profile documentation.

Further Reading

Handle authorization

On each request, the LoginCallback.ashx handler and the Http module generate an IPrincipal. Because of that, you can use the following authorization methods:

  • The declarative [Authorization] protection
  • The <location path='..'> protection
  • Code-based checks, for example, User.Identity.IsAuthenticated

Automatically redirect to the login page

If the request is not authenticated, the [Authorize] attribute generates a 401 (Unauthorized) error. If you want to automatically redirect users to the login page, you can use the Forms Authentication module.

In web.config, configure the following:

<!--Web.config-->
<system.web>
  <authentication mode="Forms">
    <forms loginUrl="Account/Login" />
  </authentication>
</system.web>

In the above example, we are redirecting to the Login action in an Account controller, which in turn redirects to Auth0's /authorize endpoint for authentication, as described in #4.

In the example above, you are redirecting the user to a Login action in an Account controller. The action redirects them to the /authorize endpoint for authentication, as described in the Authenticate the User step.

Set up logout

To clear the cookie generated on login, use the FederatedAuthentication.SessionAuthenticationModule.SignOut() method on the AccountController\Logout method.

The example below shows a typical logout action on ASP.Net MVC:

// Controllers/AccountController.cs
public RedirectResult Logout()
{
  // Clear the session cookie
  FederatedAuthentication.SessionAuthenticationModule.SignOut();

  // Redirect to Auth0's logout endpoint
  var returnTo = Url.Action("Index", "Home", null, protocol: Request.Url.Scheme );
  return this.Redirect(
    string.Format(CultureInfo.InvariantCulture,
      "https://{0}/v2/logout?returnTo={1}",
      ConfigurationManager.AppSettings["auth0:Domain"],
      this.Server.UrlEncode(returnTo)));
}

The destination URL is stored in the returnTo value.

The destination URL must be on theAllowed Logout URLs list. Read more about redirecting users after they log out in the Logout article.

To allow users to link accounts from different providers, read the Linking User Accounts article.

To link accounts, you need the logged-in user's access token. You can get it from:

<%= ClaimsPrincipal.Current.FindFirst("access_token").Value %>

Flow the user's identity to a WCF service

If you want to flow the logged-in user's identity to a WCF service or an API, use the responseType: 'token' parameter on the login widget constructor. When the parameter is sent, Auth0 generates an ID token. You can send the ID token to your service or use it to generate an ActAs token. The ID token is a JSON Web Token.

Manage the dev, test and production environments

We recommend that you create one application per environment. For each environment, use a different client ID and secret. To learn more, read about using Auth0 with Microsoft Azure.

Use Auth0 for FREECreate free Account