Add Auth Endpoints

To implement login and logout flows with Wristband, you'll need to use the Wristband SDK to create the following three endpoints in your Django application:

Login Endpoint
Callback Endpoint
Logout Endpoint

You'll create a dedicated file for these authentication endpoints (e.g., src/your_app/auth_views.py) to keep your auth logic organized and separate from your other application routes.

Login Endpoint

The Login Endpoint initiates login requests to Wristband. It constructs the authorization request and redirects the user to Wristband's Authorize Endpoint. From there, the user is directed to Wristband's hosted login page to complete the login process.

Below is a code snippet showing how to use Wristband's SDK to implement the Login Endpoint.

# your_app/auth_views.py

from django.http import HttpRequest, HttpResponse
from django.views.decorators.http import require_GET
from wristband.django_auth import (
    LogoutConfig,
    RedirectRequiredCallbackResult,
    session_from_callback,
)
from .wristband import wristband_auth

# Login Endpoint
@require_GET
def login_endpoint(request: HttpRequest) -> HttpResponse:
    # Call the Wristband login() method which will generate the response that 
    # should be used to redirect to Wristband's Authorize Endpoint.
    return wristband_auth.login(request)

...

Callback Endpoint

After the user successfully authenticates, Wristband redirects to your application's Callback Endpoint. Calling wristband_auth.callback() returns a CallbackResult object containing the user's tokens and claims.

Hydrate the session with the user's claims and tokens by calling the session_from_callback() helper function. Lastly, call wristband_auth.create_callback_response() after the callback() method is finished in order to complete the authentication flow. This will return a Django response object with the appropriate headers and cookies set.

Below is a code snippet showing how to use Wristband's SDK to implement the Callback Endpoint.

# your_app/auth_views.py (continued)

...

# Callback Endpoint
@require_GET
def callback_endpoint(request: HttpRequest) -> HttpResponse:
    # Call the Wristband callback() method to check if the user
    # successfully authenticated. If the user did authenticate successfully, 
    # the user's tokens and claims can be retrieved from the CallbackResult.
    callback_result = wristband_auth.callback(request)

    # For some edge cases, such as if an invalid grant was passed to the token
    # API, the SDK will return a redirect URL. Your code should redirect to it
    # in order to restart the login flow.
    if isinstance(callback_result, RedirectRequiredCallbackResult):
        return wristband_auth.create_callback_response(request, callback_result.redirect_url)

    # Create a session for the authenticated user. If needed, custom fields can 
    # be stored in the session using the custom_fields parameter of the 
    # session_from_callback() function.
    session_from_callback(request, callback_result.callback_data)
    
    # Once the Callback Endpoint has completed, redirect to your app's
    # default return URL (typically your app's home page) or to an explicit
    # return URL, if one was specified in the original login request.
    app_url = callback_result.callback_data.return_url or "<replace-with-default-app-url>"
    return wristband_auth.create_callback_response(request, app_url)

...

Logout Endpoint

When a user logs out of your application, you must ensure that all authenticated state associated with the user is cleared. The Logout Endpoint needs to perform three tasks to accomplish this:

Clear the application's local session state.
Revoke any refresh tokens associated with the user.
Redirect to Wristband's Logout Endpoint to terminate the user's Wristband auth session.

Below is a code snippet showing how to use Wristband's SDK to implement the Logout Endpoint.

# your_app/auth_views.py (continued)

...

# Logout Endpoint
@require_GET
def logout_endpoint(request: HttpRequest) -> HttpResponse:
    # Get all the necessary session data needed to perform the logout operation.
    logout_config = LogoutConfig(
        refresh_token=request.session.get("refresh_token"),
        tenant_name=request.session.get("tenant_name"),
    )
    
    # Clear your application's local session.
    request.session.flush()

    # Call the Wristband logout() method. This will revoke any refresh tokens
    # associated with the user and return a Response to redirect to Wristband's 
    # Logout Endpoint. Redirecting to Wristband's Logout Endpoint will terminate 
    # Wristband's auth session associated to the user. When Wristband is done
    # logging out the user it will redirect back to your application's login 
    # URL or to an explicitly provided redirect URL.
    return wristband_auth.logout(request, logout_config)

...

Map Auth Endpoints

After implementing the auth endpoints, add them to your Django app's URL configuration:

# your_app/urls.py

from django.urls import path
from . import auth_views

app_name = 'your_app'

# Roue path values can be whatever you prefer
urlpatterns = [
    path('auth/login/', auth_views.login_endpoint, name='login'),
    path('auth/callback/', auth_views.callback_endpoint, name='callback'),
    path('auth/logout/', auth_views.logout_endpoint, name='logout'),
    # Your other application URLs...
]

Don't forget to include your app's URLs in your project's main URL configuration:

# your_project/urls.py

from django.urls import path, include

urlpatterns = [
    path('', include('your_app.urls')),
]

Register Your Login Endpoint and Callback Endpoint With Wristband

For several authentication flows, Wristband will need to redirect to your application's Login Endpoint and Callback Endpoint. Therefore, we need to inform Wristband of the URLs for these two endpoints. To do that, we'll need to update the following two fields within the Wristband dashboard:

Application Login URL
Client Redirect URIs

In the sections below, we'll go over how to update these two fields.

Updating the Application Login URL

To update the Application Login URL, follow these steps.

From the Dashboard Home Page, select the appropriate application.

Next, on the Application Settings page, locate the Login URL field and set its value to the URL of your application's Login Endpoint. When you are finished, click the "Save" button.

Updating the Client Redirect URIs

To update the Client Redirect URIs, follow these steps.

Select "OAuth2 Clients" from the left navigation bar, then select the client whose ID matches the client ID that was registered with the SDK.

On the Edit Client page, navigate to the Redirect URIs section and click the "Add+" button. Then enter the URL of your application's Callback Endpoint. When you are finished, click the "Save" button.