Authenticate with ED25519
This section provides instructions on how to register and authenticate with an ED25519 keypair by using the CLI or by following the API workflow. ED25519 is best used when building applications on top of Space and Time. They're easy to generate and can be tied to a single application, limiting exposure to potential security risks with deployed applications.
If this is your first time using Space and Time, try walking through our Getting started guide.
Authenticating via Space and Time CLI
The Space and Time Command Line Interface (CLI) allows you to easily register a username and keypair to use when connecting via JDBC or running REST APIs. To get started, follow the instructions for using the CLI.
Authenticating via API workflow
Alternatively, you can register and authenticate by following the authentication API workflow.
Regardless of which workflow you choose, keep the following considerations in mind:
Basic considerations
Choosing a unique user identifier
When accessing the platform, you'll need to create a globally unique a user identifier (userId
), meaning one that's not used by anyone else in Space and Time. Make sure you note the userId
you pick - you'll use it every time you authenticate with Space and Time.
Generating a public/private keypair
Platform authentication (i.e. proving your identity) is based on public key cryptography, meaning you need a pair of public/private keys (publicKey
and privateKey
). The gist is that you request challenges from the platform and calculate a signature with your privateKey
. The platform verifies the validity of the signature with your publicKey
. Note that your privateKey
should never be shared with any person for any reason, and will always remain on your machine. Your publicKey
is stored in the platform and is safe to share.
Calculating a signature
Generating a valid signature proves you have ownership of your identity.
To calculate the signature
, you'll need to have access to your privateKey
and know the appropriate key algorithm for generating signatures. In general, it should look something like this:
// Sign the challenge with your private key
var signature = privateKey.sign(authCode);
Refreshing a session
If you've successfully authenticated with the platform and are now wondering how your session can last 24 hours if your accessToken
and refreshToken
both expire after half an hour, don't worry! All you have to do is refresh your session. Make sure you refresh your session before the expiration time of your refresh token has passed (otherwise, you'll have to go through the normal authentication workflow described above). Instructions for refreshing a session are included in both the CLI instructions and the API workflow.
A few important points:
- Authenticated sessions last a maximum of 24 hours, at which point the user must re-authenticate.
- The
accessToken
expires after 25 minutes. - The
refreshToken
expires after 30 minutes.
More information about public/private key authentication
This section contains extra information on how authentication works in Space and Time.
Key association
One primary difference in registration and authentication is related to the association between user identifier (userId
) and public key. During registration, the platform has no knowledge about the user or the user's public key. Thus, when requesting tokens, the user must provide both the public key as well as the key scheme (i.e., the algorithm to use).
After successful registration, the platform will store the given public key and key scheme and associate them with the user's identifier. Going forward the user must only provide the public key in the Token Request API, as the scheme can be retrieved from storage. This has the added benefit that the provided public key in the request will be checked against the user's associated public keys, preventing a malicious actor from associating a new public key with an existing user.
Key management
When registering with the platform for the first time, you must pick one of the supported algorithms (described below). However, you're not stuck with a single key pair or algorithm! Every user has a keychain stored in the platform which can contain any number of valid public keys and their associated algorithms.
Adding a new key to your keychain is very straightforward and similar to the authentication workflow. You request a challenge, sign it with your new private key, and submit a request to add the new public key to your keychain with the signature.
Check out our Key Management APIs to see how to interact with your keychain.
Key algorithms
The platform currently supports the following algorithms for signature-based authentication:
- ED25519 - for building applications on Space and Time
- Ethereum wallets - for accessing Space and Time
Specifying the algorithm in the Token Request API can be done via the following properties:
key
- the public key to validate the signature againstscheme
- the algorithm to use when validating the signature
For ED25519 signature verification, provide the following:
key
: your ED25519 public keyscheme
:"ed25519"
For Ethereum wallet signature verification, provide the following:
key
: your wallet addressscheme
: the Ethereum chain id (see EIP-155 for specifics)
Updated 2 months ago