Enabling CORS#

Cross-Origin Resource Sharing (CORS) is a mechanism that gives a web application running at one origin, access to resources from a different origin. For security reasons, browsers restrict these “cross-origin” requests by default.

In the context of a BinderHub deployment, CORS is relevant when you wish to leverage binder as a computing backend for a web application hosted at some other domain. For example, the amazing libraries Juniper and Thebe leverage binder as a computing backend to facilitate live, interactive coding, directly within a static HTML webpage. For this functionality, CORS must be enabled.

Adjusting BinderHub config to enable CORS#

As mentioned above, for security reasons, CORS is not enabled by default for BinderHub deployments. To enable CORS we need to add additional HTTP headers to allow our BinderHub deployment to be accessed from a different origin. This is as simple as adding the following to your config.yaml:

config:
  BinderHub:
    cors_allow_origin: '*'

jupyterhub:
  hub:
    config:
      BinderSpawner:
        cors_allow_origin: '*'

For example, if you’re following on from the previous section Secure with HTTPS, your config.yaml might look like this:

config:
  BinderHub:
    hub_url: https://<jupyterhub-URL> # e.g. https://hub.binder.example.com
    cors_allow_origin: '*'

jupyterhub:
  hub:
    config:
      BinderSpawner:
        cors_allow_origin: '*'
  ingress:
    enabled: true
    hosts:
      - <jupyterhub-URL> # e.g. hub.binder.example.com
    annotations:
      kubernetes.io/ingress.class: nginx
      kubernetes.io/tls-acme: "true"
      cert-manager.io/issuer: letsencrypt-production
      https:
        enabled: true
        type: nginx
    tls:
      - secretName: <jupyterhub-URL-with-dashes-instead-of-dots>-tls # e.g. hub-binder-example-com-tls
        hosts:
          - <jupyterhub-URL> # e.g. hub.binder.example.com

ingress:
  enabled: true
  hosts:
    - <binderhub-URL> # e.g. binder.example.com
  annotations:
    kubernetes.io/ingress.class: nginx
    kubernetes.io/tls-acme: "true"
    cert-manager.io/issuer: letsencrypt-production
    https:
      enabled: true
      type: nginx
  tls:
    - secretName: <binderhub-URL-with-dashes-instead-of-dots>-tls  # e.g. binder-example-com-tls
      hosts:
        - <binderhub-URL> # e.g. binder.example.com

Once you’ve adjusted config.yaml to enable CORS, apply your changes with:

helm upgrade <namespace> jupyterhub/binderhub --version=<version>  -f secret.yaml -f config.yaml

It may take ~10 minutes for the changes to take effect.

Secure with HTTPS

Technical Reference