Authentication

In order to talk to a JuliaHub instance, you must authenticate with your user account, and have an authentication token. JuliaHub.jl aims to make it as easy and painless as possible to manage your authentication tokens.

Overview

To use this package to authenticate in your current Julia session, you can call the authenticate function. It will return an Authentication object, containing the token.

In principle, nearly every function here takes an (optional) auth keyword argument, that should be passed an Authentication object. However, this is usually not needed in practice, since JuliaHub.jl remembers your last authentication, and uses that as the default value for auth. Additionally, if there is no active authentication, calling any function that requires authentication will try to automatically authenticate (and may also trigger an interactive authentication). You can access the currently active authentication object with current_authentication.

In order for authenticate to work, you must specify which JuliaHub instance to authenticate against (e.g. juliahub.com). There are two options for this:

1. You can configure the Julia package server to point to the JuliaHub instance by explicitly setting the JULIA_PKG_SERVER environment variable. See Local environments below to for more information on how to do it in local environments. In JuliaHub jobs, however, it is automatically set.
2. You can directly pass the JuliaHub instance URL to authenticate, e.g. JuliaHub.authenticate("juliahub.com").

If a valid token for the JuliaHub instance exists on the disk, authenticate will use that directly. Otherwise it will attempt an interactive, browser-based authentication against the Julia instance. For the latter, under the hood, it uses the PkgAuthentication package to perform the interactive authentication

JuliaHub cloud environments

When working with JuliaHub.jl in JuliaHub cloud environment, such as in JuliaHub Cloud IDEs or in JuliaHub jobs, you generally do not have to worry about authentication. The JULIA_PKG_SERVER should always be correctly set up, and the auth.toml file will also be present and up-to-date. This means that authenticate should automatically be able to authenticate your session, and you should never be prompted for interactive authentication.

@info "JuliaHub authentication token" JuliaHub.authenticate()

Local environments

When using JuliaHub.jl outside of JuliaHub (e.g. on your local laptop), you must explicitly configure the Julia package server, or pass the JuliaHub URL to authenticate.

The Julia package server can be configured via the JULIA_PKG_SERVER environment variable, and there are a few options for this. In a live Julia session, you can simply set it via ENV, e.g.

ENV["JULIA_PKG_SERVER"] = "juliahub.com"

You can also do it this way in the Julia startup.jl script.

Alternatively, on an UNIX-y system, you can set it in the shell or a script with e.g.

export JULIA_PKG_SERVER=juliahub.com

If you're exclusively using the VS Code editor with the Julia extension, you can configure the package server in the UI directly, and it will apply to any REPLs you open in VS Code.

When running JuliaHub.jl on your local computer for the first time, or when you have not used JuliaHub.jl in a while, you will likely see something like:

julia> using JuliaHub

julia> JuliaHub.authenticate()
Authentication required: please authenticate in browser.
The authentication page should open in your browser automatically, but you may need to switch to the opened window or tab. If the authentication page is not automatically opened, you can authenticate by manually opening the following URL: ...

Once you perform the browser-based authentication, the local auth.toml file gets updated, and JuliaHub.jl will be able to talk to the JuliaHub instance.