Authentication Introduction

This page gives you an introduction to the core concepts, including authentication, authorization, and the user model.

Authentication vs. Authorization

Authentication answers the question, “Who is the user?” while authorization determines, “Does the authenticated user have the required rights?”.

Enable authentication

By default, there is no authentication provider configured (XLWINGS_AUTH_PROVIDERS=[]) and everyone will be able to run custom functions and custom scripts. The current user object will be User(id='n/a', name='Anonymous', email=None, domain=None, roles=[]).

To enable authentication, you need to set XLWINGS_AUTH_PROVIDERS in the Config. xlwings Server will then authenticate calls to Custom Functions and Custom Scripts using the specified authentication provider.

You can enable Microsoft Entra ID (SSO) or one of the Other Auth Providers, including your custom authentication provider.

Caution

Setting up an authentication provider requires users to be logged in to run Custom Functions or Custom Scripts but it doesn’t automatically lock down then task pane, see Task pane authentication.

User model

At the core of the authentication system is the User model. You can find it under app/models/user.py.

If you need access to the current user object from a custom script or a custom function, you can use a function parameter with the type hint CurrentUser:

from ..models import CurrentUser

@func
def get_current_user(current_user: CurrentUser):
    return f"The user's domain is {current_user.domain}"

Task pane authentication

Since the task pane is completely customizable, it is your responsibility to lock down the desired endpoints:

  • The landing page of the task pane needs to be publicly available

  • The rest of the pages can be locked down using the User dependency injection. Note that within FastAPI endpoints, you use the dependencies.User dependency—models.CurrentUser is only available with Custom Functions and Custom Scripts.

  • You will need to provide the Authorization header with every request. For htmx, there is a sample included under app/templates/examples/auth.