aws-jupyter-proxy 0.3.7
A Jupyter server extension to proxy requests with AWS SigV4 authentication
License: Apache License 2.0
Requires Python: >=3.6

# AWS Jupyter Proxy

![Build](https://github.com/aws/aws-jupyter-proxy/workflows/build/badge.svg)
[![Version](https://img.shields.io/pypi/v/aws_jupyter_proxy.svg)](https://pypi.org/project/aws-jupyter-proxy/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

A Jupyter server extension to proxy requests with AWS SigV4 authentication.

## Overview

This server extension enables the usage of the [AWS JavaScript/TypeScript SDK](https://github.com/aws/aws-sdk-js) to write Jupyter frontend extensions without having to export AWS credentials to the browser.

A single `/awsproxy` endpoint is added on the Jupyter server which receives incoming requests from the browser, uses the credentials on the server to add [SigV4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) authentication to the request, and then proxies the request to the actual AWS service endpoint.

All requests are proxied back-and-forth as-is, e.g., a 4xx status code from the AWS service will be relayed back as-is to the browser.

NOTE: This project is still under active development

## Install

Installing the package from PyPI will install and enable the server extension on the Jupyter server.

```bash
pip install aws-jupyter-proxy
```

## Usage

Using this requries no additional dependencies in the client-side code. Just use the regular AWS JavaScript/TypeScript SDK methods and add any dummy credentials and change the endpoint to the `/awsproxy` endpoint.

```typescript
    import * as AWS from 'aws-sdk';
    import SageMaker from 'aws-sdk/clients/sagemaker';

    // Reusable function to add the XSRF token header to a request
    function addXsrfToken<D, E>(request: AWS.Request<D, E>) {
      const cookie = document.cookie.match('\\b' + '_xsrf' + '=([^;]*)\\b');
      const xsrfToken = cookie ? cookie[1] : undefined;
      if (xsrfToken !== undefined) {
        request.httpRequest.headers['X-XSRFToken'] = xsrfToken;
      }
    }

    // These credentials are *not* used for the actual AWS service call but you have
    // to provide any dummy credentials (Not real ones!)
    AWS.config.secretAccessKey = 'IGNOREDIGNORE/IGNOREDIGNOREDIGNOREDIGNOR';
    AWS.config.accessKeyId = 'IGNOREDIGNO';

    // Change the endpoint in the client to the "awsproxy" endpoint on the Jupyter server.
    const proxyEndpoint = 'http://localhost:8888/awsproxy';

    const sageMakerClient = new SageMaker({
        region: 'us-west-2',
        endpoint: proxyEndpoint,
    });

    // Make the API call!
    await sageMakerClient
        .listNotebookInstances({
            NameContains: 'jaipreet'
        })
        .on('build', addXsrfToken)
        .promise();
```

### Usage with S3

For S3, use the `s3ForcePathStyle` parameter during the client initialization

```typescript
    import S3 from 'aws-sdk/clients/s3';

    const s3Client = new S3({
        region: 'us-west-2',
        endpoint: proxyEndpoint,
        s3ForcePathStyle: true,
        s3DisableBodySigning:false // for https
    });

    await s3Client
        .getObject({
            Bucket: 'my-bucket',
            Key: 'my-object'
        })
        .on('build', addXsrfToken)
        .promise();
```

### Whitelisting

On the server, the `AWS_JUPYTER_PROXY_WHITELISTED_SERVICES` environment variable can be used to whitelist the set of services allowed to be proxied through. This is opt-in - Not specifying this 
environment variable will whitelist all services.

```bash
export AWS_JUPYTER_PROXY_WHITELISTED_SERVICES=sagemaker,s3
jupyter-lab
```

## Development

Install all dev dependencies

```bash
pip install -e ".[dev]"
jupyter serverextension enable --py aws_jupyter_proxy --sys-prefix
```

Run unit tests using pytest

```bash
pytest tests/unit
```

## License

This library is licensed under the Apache 2.0 License.