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 Aalyria.
3. Receive the USER_ID and a KEY_ID 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
  • source: tools/nbictl, executable: see releases page
• The CLI provided by the OpenSSL project
• any other software or hardware tool that can generate RSA Keypairs and x509 certificates

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

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

# generate a private key of size 4096 and save it to priv_key.pem
openssl genrsa -out priv_key.pem 4096

# extract the public key and save it to an x509 certificate named
# pub_key.cer (with an expiration far into the future)
openssl req -new -x509 -key priv_key.pem -out pub_key.cer -days 36500

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.

Connect to Spacetime APIs

Self Signed 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:

A tool to generate self-signed JWTs is included in the Spacetime API public repository under the name generate_jwt (source: tools/generate_jwt, executable: see releases page) and can be used as follow:

# Customer-specific details:
DOMAIN="${DOMAIN:?should be provided by your Aalyria contact}"
USER_ID="${USER_ID:?should be provided by your Aalyria contact}"
KEY_ID="${KEY_ID:?should be provided by your Aalyria contact}"
PRIV_KEY_FILE="/path/to/your/private/key/in/PKSC8/format.pem"
# API Specific details, example:
GRPC_SERVICE=aalyria.spacetime.api.nbi.v1alpha.NetOps
GRPC_METHOD=VersionInfo

generate_jwt --issuer "$USER_ID" --subject "$USER_ID" \
  --key-id "$KEY_ID" --private-key "$PRIV_KEY_FILE" \
  --audience "https://${DOMAIN}/${GRPC_SERVICE}/${GRPC_METHOD}"

You can test the JWT token and the authentication process using the grpcurl:

Example: obtain the current version of Spacetime

# Generate JWT for accessing the NetOps.VersionInfo API
SELF_SIGNED_JWT= $(generate_jwt \
  --issuer "$USER_ID" --subject "$USER_ID" --key-id "$KEY_ID" \
  --private-key "$PRIV_KEY_FILE" \
  --audience "https://${DOMAIN}/aalyria.spacetime.api.nbi.v1alpha.NetOps.VersionInfo")

# Generate JWT for accessing the gRPC Reflection Service, only needed when using grpcurl
SELF_SIGNED_JWT_REFLECT= $(generate_jwt \
  --issuer "$USER_ID" --subject "$USER_ID"  --key-id "$KEY_ID"
  --private-key "$PRIV_KEY_FILE" \
  --audience "https://${DOMAIN}/grpc.reflection.v1alpha.ServerReflection/ServerReflectionInfo")

# Invoke the NetOps.VersionInfo API, using the CLI tool grpcurl
grpcurl -rpc-header "Authorization: Bearer $SELF_SIGNED_JWT" \
        -reflect-header "Authorization: Bearer $SELF_SIGNED_JWT_REFLECT" \
        ${DOMAIN}:443 aalyria.spacetime.api.nbi.v1alpha.NetOps.VersionInfo

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.

• Go
  • Auth Library
• Java:
  • Auth Library
  • Code Samples
• Python:
  • Auth Library
  • Code Samples

Using nbictl CLI tool

You can interact with the Northbound API (NBI) using the command line tool nbictl.

To configure nbictl, with the credentials obtained above, you will use the set-config command:

$ nbictl set-config --url "nbi.$INSTANCE_NAME.spacetime.aalyria.com"
$ nbictl set-config --key_id "$KEY_ID"
$ nbictl set-config --user_id "$USER_ID"
$ nbictl set-config --priv_key "$PRIVATE_KEY_FILE_NAME"

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.