Authentication

In order to talk to a JuliaHub instance, you need to have a valid authentication token. JuliaHub reuses the Julia's built-in package server authentication tokens for this purpose. By default, the authentication uses the JULIA_PKG_SERVER environment variable to determine which JuliaHub instance to connect to, but this can be overridden by passing an argument to authenticate.

The authenticate function can be used to construct a token. If a valid token is available in ~/.julia/servers, it gets reused. Otherwise, a browser window is opened, starting an interactive authentication procedure.

All the functions that require authentication accept an auth keyword argument. However, JuliaHub.jl also stores the authentication token from the last authenticate call in a global variable and automatically uses that if auth is not provided, and also tries to authenticate automatically. The current global authentication object can be accessed via the current_authentication() function.

Token expiration and refresh tokens

By default, JuliaHub access tokens expire in 24 hours. However, the tokens usually also have a refresh token, which is valid for 30 days. If the access token has expired, but there is a valid refresh token available, authenticate will automatically try to use that, to re-acquire an access token without starting an interactive authentication.

In JuliaHub job and cloud IDE environments, the authentication token on disk will be continuously kept up to date. The reauthenticate! function can be used to reload the token from disk.

Reference

JuliaHub.authenticate — Function

JuliaHub.authenticate(
    server::AbstractString = Pkg.pkg_server();
    force::Bool = false,
    maxcount::Integer = 3,
    [project::Union{AbstractString, UUIDs.UUID, Nothing}],
    [hook::Base.Callable]
) -> JuliaHub.Authentication
JuliaHub.authenticate(server::AbstractString, token::Union{AbstractString, JuliaHub.Secret}) -> JuliaHub.Authentication

Authenticates with a JuliaHub server, returning a JuliaHub.Authentication object and setting the global authentication session (see JuliaHub.current_authentication). May throw an AuthenticationError if the authentication fails (e.g. expired token).

The zero- and one-argument methods will attempt to read the token from the current Julia depot. If a valid authentication token does not exist in the Julia depot, a new token is acquired via an interactive browser based prompt. By default, it attemps to connect to the currently configured Julia package server URL (configured e.g. via the JULIA_PKG_SERVER environment variable), but this can be overridden by passing the server argument. server is just the URL of your JuliaHub instance, so if you've logged on to the public JuliaHub server, this is "juliahub.com".

The two-argument method can be used when you do not want to read the token from the auth.toml file (e.g. when using a long-term token via an environment variable). In this case, you also have to explicitly set the server URL and JULIA_PKG_SERVER is ignored.

Extended help

The interactive prompts tries to authenticate for a maximum of maxcount times. If force is set to true, an existing authentication token is first deleted. This can be useful when the existing authentication token is causing the authentication to fail.

hook can be set to a function taking a single string-type argument, and will be passed the authorization URL the user should interact with in the browser. This can be used to override the default behavior coming from PkgAuthentication.

The returned Authentication object is also cached globally (overwriting any previously cached authentications), making it unnecessary to pass the returned object manually to other function calls. This is useful for interactive use, but should not be used in library code, as different authentication calls may clash.

Project Context

An Authentication object can also specify the default JuliaHub project. This can be set by passing the optional project argument, which works as follows:

If the project value is not passed, JuliaHub.jl will attempt to pick up the the project UUID from the JULIAHUB_PROJECT_UUID environment variable, and will fall back to the non-project context if that is not set.
If you pass an explicit UUID (either as a string or an UUID object), that will then be used as the project. Note that a UUID passed as a string must be a syntactically correct UUID.
Passing nothing makes JuliaHub.jl ignore any values in the JULIAHUB_PROJECT_UUID environment variable.

JULIAHUB_PROJECT_UUID

Generally, in JuliaHub jobs and cloud IDE environments that are launched in the context of a project, the JULIAHUB_PROJECT_UUID is automatically set, and JuliaHub.jl will pick it up automatically, unless explicitly disabled with project=nothing.

Project access checks

When the Authentication object is constructed, access to or existence of the specified project is not checked. However, if you attempt any project operations with with such an authentication object, they will fail and throw an error.

Examples

If JULIA_PKG_SERVER is set, authenticate() will pick it up automatically, although it can also be overridden by setting the instance hostname explicitly:

julia> ENV["JULIA_PKG_SERVER"]
"juliahub.com"

julia> JuliaHub.authenticate()
JuliaHub.Authentication("https://juliahub.com", "username", *****)

julia> JuliaHub.authenticate("mycompany.juliahub.com")
JuliaHub.Authentication("https://mycompany.juliahub.com", "username", *****)

If JULIAHUB_PROJECT_UUID is set to point to a JuliaHub Project (e.g. in JuliaHub cloud environments), it will also get automatically picked up, but can also be overridden:

julia> ENV["JULIAHUB_PROJECT_UUID"]
"b1a95ba8-43e6-4eb6-b280-3c5cbe0fa0b9"

julia> JuliaHub.authenticate()
JuliaHub.Authentication("https://juliahub.com", "username", *****; project_id = "b1a95ba8-43e6-4eb6-b280-3c5cbe0fa0b9")

julia> JuliaHub.authenticate(; project = "7ed96f69-a765-4de6-ac00-04a38684ce1c")
JuliaHub.Authentication("https://juliahub.com", "username", *****; project_id = "7ed96f69-a765-4de6-ac00-04a38684ce1c")

julia> JuliaHub.authenticate(; project = nothing)
JuliaHub.Authentication("https://juliahub.com", "username", *****)

source

JuliaHub.Authentication — Type

mutable struct Authentication

Authentication object constructed by the authenticate function that can be passed to the various JuliaHub.jl function via the auth keyword argument.

Objects have the following properties:

server :: URIs.URI: URL of the JuliaHub instance this authentication token applies to.
username :: String: user's JuliaHub username (used for e.g. to namespace datasets)
token :: JuliaHub.Secret: a Secret object storing the JuliaHub authentication token
project_id :: Union{UUID, Nothing}: the project ID of the currently active project.

Note that the object is mutable, and hence will be shared as it is passed around. And at the same time, functions such as reauthenticate! may modify the object.

No public constructors

Objects of this type should not be constructed explicitly. The contructor methods are not considered to be part of the public API.

source

JuliaHub.current_authentication — Function

JuliaHub.current_authentication() -> Union{Authentication, Nothing}

Returns the current globally active Authentication object, or nothing if authenticate has not yet been called.

julia> JuliaHub.current_authentication()
JuliaHub.Authentication("https://juliahub.com", "username", *****)

Note

Calling this function will not initialize authentication.

source

JuliaHub.check_authentication — Function

JuliaHub.check_authentication(; [auth::Authentication]) -> Bool

Checks if the authentication to a JuliaHub instance is still valid or not.

This can be used to periodically check an authentication token, to see if it is necessary to re-authenticate.