API Documentation
Authentication

Authentication

Spacetime uses Private-Public Keypairs and Self Signed JSON Web Tokens (JWTs) to authenticate with its services.

Obtaining API credentials

In order to obtain API credentials, you’ll need to:

  1. Generate a Private-Public keypair on your computer.
  2. Send a self-signed x509 certificate containing the public key to your Aalyria’s contact.
  3. Receive the USER_ID and a KEY_ID and a DOMAIN that from now on will be associated with your Private-Public Keypair.

Creating Private-Public Keypairs

To create a Private-Public keypair, you can choose between using:

  • The Aalyria provided nbictl tool
  • The CLI provided by the OpenSSL project
  • any other software or hardware tool that can generate RSA Keypairs and x509 certificates

Before using the nbictl tool you need to install it as described here. Then, use it as follows:

nbictl generate-keys --org "my-organization.com"

After some seconds, you’ll receive an output like this one:

private key is stored under: ~/.config/nbictl/keys/922e75e63659b29b76631275.key
certificate is stored under: ~/.config/nbictl/keys/922e75e63659b29b76631275.crt

Then, go in the folder ~/.config/nbictl/keys and get the xxxx.crt file.

OpenSSL is generally already installed in every Linux distribution. To verify that it is so, type:

openssl version

To use OpenSSL to create a pair of keys, type:

openssl genrsa -out priv_key.pem 4096

To extract the public key from the private key, type:

openssl req -new -x509 -key priv_key.pem -out pub_key.cer -days 36500

Regardless of the process you used, now you have a private key (the .pem or .key file ) and a certificate (the .cert file). Keep the private key safe and give the certificate file to your contact in Aalyria.

Production Keypairs

In production, you’ll want to create and store your keypair using a Trusted Platform Module (TPM) to ensure that your private key cannot be exfiltrated.

While the instructions for using TPM to create and use a keypair are platform-specific, you can use this document as a reference for how to manually create and sign the JWT tokens required to successfully authenticate with the NBI server.

Generating Self-Signed JWT Tokens

The second step, after you created your private-public keypair and received the IDs from your contact in aalyria, is to create a JWT token.

To successfully authenticate when connecting to Spacetime APIs, the request needs to include a valid Self Signed JWT as bearer token in the Authorization header.

In particular the JWT must meet the following requirements:

Header Fields Spacetime JWT
algorithm (alg) RS256
key ID (kid) $KEY_ID
Payload Fields Spacetime JWT
issuer (iss) $USER_ID
subject (sub) $USER_ID
audience (aud) https://${DOMAIN}/${GRPC_SERVICE}/${GRPC_METHOD}
lifetime (exp) No more than 1h from time of signature

Now, let’s discuss the ways you can create a Self Signed JWT token.

Generating a Self-Signed JWT With nbictl

We provide a CLI tool called nbictl that, among other things, can help you generate Self-Signed JWTs. Hear how to do so here.

How To Connect to Spacetime APIs

After you created the Self-Signed JWT, you can interact with the Aalyria APIs.

Using gRPC client libraries

When connecting to Spacetime APIs programmatically, you will need to configure the gRPC-generated client libraries to include the JWT token in each request.

You can implement this manually when required (eg. when storing private key in a TPM module) or use the Spacetime provided Auth libraries when these fits your requirements.

Using nbictl tool

You can interact with Spacetime APIs using the command line tool nbictl. To install and configure nbictl read this guide.

Once nbictl is configured, you can verify access to the Spacetime APIs by creating a request as follows:

$ nbictl list --type "BAND_PROFILE"

This command will query Spacetime, throught the NBI API, for the list of BAND_PROFILE entities uploaded in the past.

If successful, you should see a list of band profile entities. The results returned will of course depend on the state of the Spacetime instance. It is normal for the results to be empty if no band profiles have yet been created in the instance.

Using grpcurl

You can interact with the APIs via grpcurl: a command-line tool that allows you to interact with gRPC services directly, similar to how curl is used for HTTP APIs.

It’s particularly useful for testing, debugging, and automating requests to gRPC servers without needing a full client implementation.

To install it you can read the gRPC section.

To use grpcurl to connect to spacetime APIs, you need to pass the self-signed JWT token in the headers, like so:

# Generate JWT token with nbictl for accessing the NetOps.VersionInfo API
SELF_SIGNED_JWT= $(nbictl generate-auth-token \
  --audience "https://nbi.$DOMAIN/aalyria.spacetime.api.nbi.v1alpha.NetOps/VersionInfo")

# Invoke the NetOps.VersionInfo API, using the CLI tool grpcurl
grpcurl -H "Authorization: Bearer $SELF_SIGNED_JWT" \
        nbi.$DOMAIN:443 aalyria.spacetime.api.nbi.v1alpha.NetOps.VersionInfo
nbictl tool