Identity Providers#

Thejupyter_server.auth.IdentityProvider class is responsible for the “authentication” step,identifying the user making the request,and constructing information about them.

It principally implements two methods.

classjupyter_server.auth.IdentityProvider(**kwargs)#

Interface for providing identity management and authentication.

Two principle methods:

• get_user() returns aUser objectfor successful authentication, or None for no-identity-found.

• identity_model() turns aUser into a JSONable dict.The default is to usedataclasses.asdict(),and usually shouldn’t need override.

Additional methods can customize authentication.

Added in version 2.0.

get_user(handler)#

Get the authenticated user for a request

Must return ajupyter_server.auth.User,though it may be a subclass.

Return None if the request is not authenticated.

_may_ be a coroutine

Return type:

User | None | t.Awaitable[User | None]

identity_model(user)#

Return a User as an Identity model

Return type:

dict[str,Any]

The first isjupyter_server.auth.IdentityProvider.get_user().This method is given a RequestHandler, and is responsible for deciding whether there is an authenticated user making the request.If the request is authenticated, it should return ajupyter_server.auth.User object representing the authenticated user.It should return None if the request is not authenticated.

The default implementation accepts token or password authentication.

This User object will be available asself.current_user in any request handler.Request methods decorated with tornado’s@web.authenticated decoratorwill only be allowed if this method returns something.

The User object will be a Pythondataclasses.dataclass -jupyter_server.auth.User:

classjupyter_server.auth.User(username,name='',display_name='',initials=None,avatar_url=None,color=None)#

Object representing a User

This or a subclass should be returned from IdentityProvider.get_user

A custom IdentityProvidermay return a custom subclass.

The next method an identity provider has isidentity_model().identity_model(user) is responsible for transforming the user object returned from.get_user()into a standard identity model dictionary,for use in the/api/me endpoint.

If your user object is a simple username string or a dict with ausername field,you may not need to implement this method, as the default implementation will suffice.

Any required fields missing from the dict returned by this method will be filled-out with defaults.Onlyusername is strictly required, if that is all the information the identity provider has available.

Missing will be derived according to:

• ifname is missing, useusername

• ifdisplay_name is missing, usename

Other required fields will be filled withNone.

Authorization#

Authorization is the second step in allowing an action,after a user has beenauthenticated by the IdentityProvider.

Authorization in Jupyter Server serves to provide finer grained control of access to itsAPI resources. With authentication, requests are accepted if the current user is known bythe server. Thus it can restrain access to specific users, but there is no way to give allowedusers more or less permissions. Jupyter Server provides a thin and extensible authorization layerwhich checks if the current user is authorized to make a specific request.

classjupyter_server.auth.Authorizer(**kwargs)#

Base class for authorizing access to resourcesin the Jupyter Server.

All authorizers used in Jupyter Servershould inherit from this base class and, at the very minimum,implement anis_authorized method with thesame signature as in this base class.

Theis_authorized method is called by the@authorized decoratorin JupyterHandler. If it returns True, the incoming requestto the server is accepted; if it returns False, the serverreturns a 403 (Forbidden) error code.

The authorization check will only be applied to requeststhat have already been authenticated.

Added in version 2.0.

is_authorized(handler,user,action,resource)#

A method to determine ifuser is authorized to performaction(read, write, or execute) on theresource type.

Parameters:

• user (jupyter_server.auth.User) – An object representing the authenticated user,as returned byjupyter_server.auth.IdentityProvider.get_user().

• action (str) – the category of action for the current request: read, write, or execute.

• resource (str) – the type of resource (i.e. contents, kernels, files, etc.) the user is requesting.

Returns:

True if user authorized to make request; False, otherwise

Return type:

bool

This is done by calling ais_authorized(handler,user,action,resource) method before eachrequest handler. Each request is labeled as either a “read”, “write”, or “execute”action:

• “read” wraps allGET andHEAD requests.In general, read permissions grants access to read but not modify anything about the given resource.

• “write” wraps allPOST,PUT,PATCH, andDELETE requests.In general, write permissions grants access to modify the given resource.

• “execute” wraps all requests to ZMQ/Websocket channels (terminals and kernels).Execute is a special permission that usually corresponds to arbitrary execution,such as via a kernel or terminal.These permissions should generally be considered sufficient to perform actions equivalentto ~all other permissions via other means.

Theresource being accessed refers to the resource name in the Jupyter Server’s API endpoints.In most cases, this is the field after/api/.For instance, values forresource in the endpoints provided by the base Jupyter Server package,and the corresponding permissions:

Extensions may define their own resources.Extension resources should start withextension_name: to avoid namespace conflicts.

Ifis_authorized(...) returnsTrue, the request is made; otherwise, aHTTPError(403) (403 means “Forbidden”) error is raised, and the request is blocked.

By default, authorization is turned off—i.e.is_authorized() always returnsTrue andall authenticated users are allowed to make all types of requests. To turn-on authorization, passa class that inherits fromAuthorizer to theServerApp.authorizer_classparameter, implementing ais_authorized() method with your desired authorization logic, asfollows:

fromjupyter_server.authimportAuthorizerclassMyAuthorizationManager(Authorizer):"""Class for authorizing access to resources in the Jupyter Server.    All authorizers used in Jupyter Server should inherit from    AuthorizationManager and, at the very minimum, override and implement    an `is_authorized` method with the following signature.    The `is_authorized` method is called by the `@authorized` decorator in    JupyterHandler. If it returns True, the incoming request to the server    is accepted; if it returns False, the server returns a 403 (Forbidden) error code.    """defis_authorized(self,handler:JupyterHandler,user:Any,action:str,resource:str)->bool:"""A method to determine if `user` is authorized to perform `action`        (read, write, or execute) on the `resource` type.        Parameters        ------------        user : usually a dict or string            A truthy model representing the authenticated user.            A username string by default,            but usually a dict when integrating with an auth provider.        action : str            the category of action for the current request: read, write, or execute.        resource : str            the type of resource (i.e. contents, kernels, files, etc.) the user is requesting.        Returns True if user authorized to make request; otherwise, returns False.        """returnTrue# implement your authorization logic here

Theis_authorized() method will automatically be called whenever a handler is decorated with@authorized (fromjupyter_server.auth), similarly to the@authenticated decorator for authentication (fromtornado.web).

Updating trust#

A notebook’s trust is updated when the notebook is saved. If there areany untrusted outputs still in the notebook, the notebook will not betrusted, and no signature will be stored. If all untrusted outputs havebeen removed (either viaClearOutput or re-execution), then thenotebook will become trusted.

While trust is updated per output, this is only for the duration of asingle session. A newly loaded notebook file is either trusted or not in itsentirety.

Explicit trust#

Sometimes re-executing a notebook to generate trusted output is not anoption, either because dependencies are unavailable, or it would take along time. Users can explicitly trust a notebook in two ways:

• At the command-line, with:

  jupytertrust/path/to/notebook.ipynb

• After loading the untrusted notebook, withFile/TrustNotebook

These two methods simply load the notebook, compute a new signature, and addthat signature to the user’s database.

Javascript and CSS in Markdown cells#

While never officially supported, it had become common practice to puthidden Javascript or CSS styling in Markdown cells, so that they wouldnot be visible on the page. Since Markdown cells are now sanitized (byGoogle Caja), all Javascript(including click event handlers, etc.) and CSS will be stripped.

We plan to provide a mechanism for notebook themes, but in the meantimestyling the notebook can only be done via eithercustom.css or CSSin HTML output. The latter only have an effect if the notebook istrusted, because otherwise the output will be sanitized just likeMarkdown.

Collaboration#

When collaborating on a notebook, people probably want to see theoutputs produced by their colleagues’ most recent executions. Since eachcollaborator’s key will differ, this will result in each share startingin an untrusted state. There are three basic approaches to this:

• re-run notebooks when you get them (not always viable)

• explicitly trust notebooks viajupytertrust or the notebook menu(annoying, but easy)

• share a notebook signatures database, and use configuration dedicated to thecollaboration while working on the project.

To share a signatures database among users, you can configure:

c.NotebookNotary.data_dir="/path/to/signature_dir"

to specify a non-default path to the SQLite database (of notebook hashes,essentially).