Package: ipython_oidc_client
OAuth2 on Jupyter NotebookA Jupyter extension to perform OAuth2 flows (e.g. token, code) in notebooks.RationalA major challenge in using APIs from notebooks is to form a trust relationship between the client (notebook)
and the API.This problem is often solved by trusting thehostof the kernel. The typical approach here is the managed identity pattern through a metadata service, that all major cloud providers offer. A major disadvantage of this pattern is that any user that can access the execution engine (the kernel through a notebook), can also access whatever API that host has access to. I.e. it does not allow discrimatory access to APIs as it does not separate "access to notebooks" from "access to APIs". This generally leads to host-based access architectures with one host per set of access policies. An aditional limitation of this pattern is that it incentivizes vendor lock-in, as it implies that the service needs to run on the vendor's infrastructure.Another pattern to solve this problem is to use a service principal (OAuth2) to access the API through a client secret. This unfortunatelly suffers from the same problems as the managed identity: it leads to indiscrimatory access to the API by anyone with access to the execution engine. This pattern has another risk: in the context of a notebook, it is easy to programatically obtain the client secret, which gives an attacker indiscrimatory access to the API fromany hostin a zero trust network.This packageThis package allows users to perform OAuth2 flows (e.g. token, code) in notebooks, thus considering a notebook, and consequently the kernel, as a client application with limited trust. This allows kernels to run on infrastructure without a metadata service, while at the same time maintaining high security standards.How to installpip install ipython-oidc-client

jupyter nbextension install --py ipython_oidc_client
jupyter nbextension enable --py ipython_oidc_client
jupyter serverextension enable --py ipython_oidc_clientOn your identity provider (e.g. Azure, Google, Auth0), add a reply url to the path/redirect.html,
e.g.https://example.com/redirect.hml.How to useOpen a new notebook and runfrom ipython_oidc_client import authenticate


access_configuration = {
    'authority': 'https://.../.well-known/openid-configuration',
    'client_id': '...',
    'response_type': '...',
    'scope': '...',
}
# valid variables available here: https://github.com/IdentityModel/oidc-client-js/wiki#usermanager

token = {}
authenticate(access_configuration, token)  # this changes token (see note in README.md)At this point, you will be redirected to the authentication page of the identity provider declared
inauthority. Once authenticated (e.g. through MFA), you will be redirected back to the notebook.Once back in the notebook, re-run the cell above, andtoken['access_token']becomes the access token returned by the authority. Re-running the first cell does not trigger a new authentication; in fact, running that cell on any notebook on the same jupyterhub will yield the same access token.At this point, you can run e.g.import requests
r = requests.get('https://api....', headers={'Authorization': f'Bearer {token["access_token"]}'})Once the token expires (typically after 1 hour), re-run the cell above to get a new token.This procedure can be repeated for access tokens to multiple APIs within the same notebook.Why not returning the token?Due to alimitation in Jupyter,
the access token only becomes available to the kernel after the execution of thewholecell.
As such, we can't return the token fromauthenticateand instead have to assign it to a variable of global
scope. This may change in the future.ExampleDockerfilecontains a complete installation of the package from pypi on a server,
demonstrating how an administrator can install this extension system-wide. Run it withdockerbuild-tt.&&dockerrun-p8888:8888--rm-ittand addhttp://localhost:8888/redirect.htmlas a reply url to an application in your identity provider.After start, copy the snipped above to a cell and run it.SecurityThis package has to deal with two execution environments:javascript, on the browserPython, on the kernelOn the browser, it usesoidc-client-jsto perform
the oauth2 flows. In Python, it uses this package's source code, which performs a redirect and communicates with the browser.The flow after running the example above is:The client code is loaded when the kernel starts, loading external client dependencies (see below)The cell is ran, which stores the current path on a cookie and triggers a javascript redirect to the identity providerthe identity provider redirects to/redirect.htmlafter sucessful authenticationthe callback client code stores the token and redirects the user to the path in a cookieThis package does not deliver js dependencies; the client needs access tohttps://cdnjs.cloudflare.com/ajax/libs/oidc-client/1.10.0/oidc-client.min.jshttps://unpkg.com/universal-cookie@3/umd/universalCookie.min.jsthis may change in the future.Kernel - Browser trustThis package assumes that the kernel is less trustworthy than the browser. This is because, by design, in a notebook environment, it is easy toprint a variable on an output cell of a notebook andshare the notebook with someoneThese induce a risk of inadvertedly sharing tokens, in particular refresh tokens. To reduce this risk, the browser only shares access tokens with the kernel, which are extrictly necessary to communicate with an API.Another advantage of this pattern is that an attack on the kernel server requires significantly more effort to grant access to an API: a user needs to have printed its access token to a notebook and the attacker
needs to access that notebook (privileged access) within the expiration date of the token (within 1 hour).This is in opposition to the metadata service, which is available to any process running on the host (seeAWSandAzure).Browser trustThe pattern used by this library has the same risks of a single page application, including secret exfiltration from the browser. This implies that auditing is required for any client-side code that jupyter delivers to end users, as to not exfiltrate tokens from the client.How to developThis package has 4 components:js client running on the browserPython extension running on the serverPython API to authenticate on a notebookhtml/js callback page to process the response from the IPThe easiest way to develop this package is to rundockerbuild-fDockerfile.dev-tt.&&dockerrun-p8888:8888-v$(pwd):/project--rm-ittand open the browser athttp://localhost:8888/?token=(note,not127.0.0.1). Afterwards, addhttp://localhost:8888/redirect.htmlas a reply url in your identity provider.This runs a Python-based image with Jupyter and the package installed in a way that
changing the js only requires refreshing the page. Changing the Python code requires re-running the image.