Enhance Auth Endpoints To Support Sessions

Now that the Authentication Middleware is configured to support cookie authentication, we need to update our authentication endpoints to manage the lifecycle of the user's session.

Update Existing Auth Endpoints

First, we'll need to update the existing Callback and Logout endpoints to create and clean up a user's session, respectively.

Update Callback Endpoint

After a user has successfully authenticated, Wristband will redirect to your application's Callback Endpoint. Calling the IWristbandAuthService.callback method will return a CallbackResult object containing the user's tokens and claims. We can use these tokens and claims to create the user's session by calling the HttpContext.SignInAsync method.

The below code example shows how to update your existing Callback Endpoint to create the user's session:

// AuthRoutes.cs

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using Wristband.AspNet.Auth;

public static class AuthRoutes
{
    ...

    // Callback Endpoint
    app.MapGet("/auth/callback", async (HttpContext httpContext, IWristbandAuthService wristbandAuth) =>
    {
        try
        {
            // Call the Wristband Callback() method to get the user's tokens and claims.
            var callbackResult = await wristbandAuth.Callback(httpContext);
          
            if (callbackResult.Result == CallbackResultType.REDIRECT_REQUIRED)
            {
                return Results.Redirect(callbackResult.RedirectUrl);
            }
          
            /* ***** BEGIN NEW SESSION LOGIC ***** */

            // Use the data contained in the callbackResult to create the claims
            // that will be added to the session.
            var callbackData = callbackResult.CallbackData;
            var userinfo = callbackData.Userinfo;
            var claims = new List<Claim>
            {
                new("accessToken", callbackData.AccessToken),
                new("refreshToken", callbackData.RefreshToken ?? string.Empty),
                // Convert expiration seconds to a Unix timestamp in milliseconds.
                new("expiresAt", $"{DateTimeOffset.Now.ToUnixTimeMilliseconds() + (callbackData.ExpiresIn * 1000)}"),
                new("tenantDomainName", callbackData.TenantDomainName),
                new("tenantCustomDomain", callbackData.TenantCustomDomain ?? string.Empty),
                new("userId", userinfo.TryGetValue("sub", out var userId) ? userId.GetString() : string.Empty),
                new("tenantId", userinfo.TryGetValue("tnt_id", out var tenantId) ? tenantId.GetString() : string.Empty),
              
                //
                // Add any other session claims your app needs...
                //
            };

            // Create the user's session containing the above claims.
            await httpContext.SignInAsync(
                CookieAuthenticationDefaults.AuthenticationScheme, 
                    new ClaimsPrincipal(new ClaimsIdentity(claims, CookieAuthenticationDefaults.AuthenticationScheme)),
                new AuthenticationProperties { IsPersistent = true });
          
            /* ***** END NEW SESSION LOGIC ***** */
          
            var appUrl = string.IsNullOrWhiteSpace(callbackResult.CallbackData.ReturnUrl)
                  ? "<replace_with_a_default_return_url>" 
                  : callbackResult.CallbackData.ReturnUrl;
            return Results.Redirect(appUrl);
        } catch (Exception ex)
        {
            return Results.Problem(detail: $"Unexpected error: {ex.Message}", statusCode: 500);
        }
    });

    ...
};

Update Logout Endpoint

When a user logs out of your application, you need to ensure that all authenticated state associated with the user is cleaned up. Therefore, we need to update our Logout Endpoint to invalidate the user's session and revoke their refresh token (assuming the session contains a refresh token).

The below code example shows how to update your existing Logout Endpoint to clean up the user's session:

// AuthRoutes.cs

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using Wristband.AspNet.Auth;

public static class AuthRoutes
{
    ...

    // Logout Endpoint
    app.MapGet("/auth/logout", async (HttpContext httpContext, IWristbandAuthService wristbandAuth) =>
    {
        try
        {
            /* ***** BEGIN NEW SESSION LOGIC ***** */

            // Before deleting the user's session make sure to grab any necessary session 
            // data needed to call the Wristband Logout() function.
            var refreshToken = httpContext.User.FindFirst("refreshToken")?.Value;
            var tenantCustomDomain = httpContext.User.FindFirst("tenantCustomDomain")?.Value;
            var tenantDomainName = httpContext.User.FindFirst("tenantDomainName")?.Value;
          
            var logoutConfig = new LogoutConfig
            {
                RefreshToken = refreshToken,
                TenantCustomDomain = tenantCustomDomain,
                TenantDomainName = tenantDomainName
            };
      
            // Delete the user's session.
            await httpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
          
            /* ***** END NEW SESSION LOGIC ***** */

            // Calling the Wristband Logout() method will revoke the refresh token passed in 
            // the logoutConfig, if it's present.
            var wristbandLogoutUrl = await wristbandAuth.Logout(httpContext, logoutConfig);
          
            // Redirecting to Wristband's Logout Endpoint ensures that all session data 
            // maintained by Wristband is also deleted.
            return Results.Redirect(wristbandLogoutUrl);
        }
        catch (Exception ex)
        {
            return Results.Problem(detail: $"Unexpected error: {ex.Message}", statusCode: 500);
        }
    });

    ...
}

Create a Session Endpoint

In addition to updating the Callback and Logout endpoints, we'll also need to create a Session Endpoint. The Session Endpoint will check that the incoming request has a valid session, and, if so, it will return a response containing the user's session data. The Session Endpoint serves two primary purposes:

It provides a way for the frontend to check whether the user has a valid session.
It allows the frontend to access the user's session data so it can be utilized in the browser.

Since this guide uses a React frontend, we'll structure the response to match what the React Client Auth SDK expects (which will be covered in the next section of this guide).

At a minimum, the response should include userId and tenantId.

// AuthRoutes.cs

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using Wristband.AspNet.Auth;

public static class AuthRoutes
{
    ...

    // Session Endpoint
    app.MapGet("/session", (HttpContext httpContext) =>
    {
        var user = httpContext.User;
      
        // Check that the user has an authenticated session.  If they don't, return a 401
        if (user?.Identity == null || !user.Identity.IsAuthenticated)
        {
            return Results.Unauthorized();
        }
          
        //
        // If needed, you can make additional API calls to gather other session data you 
        // might want to return to your frontend.
        //

        // You can add any session data needed by the frontend to the response, but for 
        // now we'll add the bare minimum of the user's userId and tenantId.
        return Results.Ok(new
        { 
            userId = user.FindFirst("userId")?.Value ?? string.Empty,
            tenantId = user.FindFirst("tenantId")?.Value ?? string.Empty
        });
    });
      
    ....
}