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,
    [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.

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.

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

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.

See also: reauthenticate!.

source

JuliaHub.reauthenticate! — Function

JuliaHub.reauthenticate!([auth::Authentication]; force::Bool = false, maxcount::Integer = 3, [hook::Base.Callable])

Attempts to update the authentication token in auth:

If the original auth.toml file has been updated, it simply reloads the token from the file.
If loading from auth.toml fails or force=true, it will attempt to re-authenticate with the server, possibly interactively.

If auth is omitted, it will reauthenticate the global Authentication object. The force, maxcount and hook are relevant for interactive authentication, and behave the same way as in the authenticate function.

This is mostly meant to be used to re-acquire authentication tokens in long-running sessions, where the initial authentication token may have expired.

As Authentication objects are mutable, the token will be updated in all contexts where the reference to the Authentication has been passed to.

source

JuliaHub.Secret — Type

mutable struct Secret

A helper type for storing secrets. Internally it is a covenience wrapper around Base.SecretBuffer. Predominantly used in Authentication objects to store the JuliaHub authentication token.

The String(::Secret) function can be used to obtain an unsecure string copy of the secret stored in the object.

julia> s = JuliaHub.Secret("secret-string")
JuliaHub.Secret("*******")

julia> String(s)
"secret-string"

Constructors

Secret(::AbstractString)
Secret(::Vector{UInt8})

Create a Secret object from the input strings.

source