Authentication

Audience

This is aimed at NetFoundry customers and trial users who will use the API directly to augment and automate their use of the NF Console.

Overview

All authenticated operations require an HTTP header like

Authorization: Bearer {NETFOUNDRY_API_TOKEN}

where {NETFOUNDRY_API_TOKEN} is an expiring JSON Web Token (JWT) that you obtain from Cognito, NetFoundry API’s identity provider, by authenticating with your API account.

Get an API Account

1. Start a free trial if you need a login for NF Console
2. Log in to NF Console
3. In NF Console, navigate to “organization”, “Manage API Account”, and click
4. Click the button to download “credentials.json”
5. Save in one of
   • project default: ./credentials.json
   • user default: ~/.netfoundry/credentials.json
   • device default: /netfoundry/credentials.json

You may override the default paths with an environment variable.

NETFOUNDRY_API_ACCOUNT=~/Downloads/example-account.json

Get a Token in the Current Shell

If you are using a shell such as bash or zsh you can download and source this script which will setup your shell quickly and easily for use with the samples below.

# get an API token with the default API account ~/.netfoundry/credentials.json
❯ source ./export-netfoundry-api-token.bash

# or override the default credentials file to use a different API account
❯ NETFOUNDRY_API_ACCOUNT=~/Downloads/example-account.json \
    source ./export-netfoundry-api-token.bash

Get the export-netfoundry-api-token.bash Script

download

Expand to see the full source of export-netfoundry-api-token.bash

# source this file in bash or zsh to make
#  NETFOUNDRY_API_TOKEN 
# available to processes run in the same shell

# troubleshooting function that drops all authentication variables
nonf(){
    unset   NETFOUNDRY_API_ACCOUNT \
            NETFOUNDRY_API_TOKEN \
            NETFOUNDRY_CLIENT_ID \
            NETFOUNDRY_PASSWORD \
            NETFOUNDRY_OAUTH_URL \
            NFNETWORK NFNETWORKID \
            MOPENV MOPURL
}

_get_nf_token(){
    set -o pipefail
    [[ $# -eq 3 ]] || {
        echo "ERROR: send params: client_id client_pass oauth_url" >&2
        return 1
    }
    client_id=$1
    client_pass=$2
    oauth_url=$3
    mop_env=$(_get_mop_env $oauth_url)
    access_token=$(curl \
        --silent \
        --show-error \
        --fail \
        --request POST \
        --user "${client_id}:${client_pass}" \
        ${oauth_url} \
        --header 'content-type: application/x-www-form-urlencoded' \
        --data "grant_type=client_credentials&scope=https%3A%2F%2Fgateway.${mop_env}.netfoundry.io%2F%2Fignore-scope" \
            | python -c 'import json,sys;print(json.load(sys.stdin)["access_token"]);'
    ) || return 1
    echo ${access_token}
}

_get_mop_env(){
    oauth_url=$1                                              #https://netfoundry-sandbox-hnssty.auth.us-east-1.amazoncognito.com/oauth2/token
    mop_env=${oauth_url#https://netfoundry-}                  #sandbox-hnssty.auth.us-east-1.amazoncognito.com/oauth2/token
    mop_env=${mop_env%%-*.amazoncognito.com/oauth2/token}     #sandbox
    echo $mop_env
}

_get_api_account(){
    if [[ ! -z ${NETFOUNDRY_API_ACCOUNT:-} && -s ${NETFOUNDRY_API_ACCOUNT} ]]; then
        true
    elif [[ -s ./credentials.json ]]; then
        NETFOUNDRY_API_ACCOUNT=./credentials.json               # project default
    elif [[ -s ~/.netfoundry/credentials.json ]]; then
        NETFOUNDRY_API_ACCOUNT=~/.netfoundry/credentials.json   # user default
    elif [[ -s /netfoundry/credentials.json ]]; then
        NETFOUNDRY_API_ACCOUNT=/netfoundry/credentials.json     # device default
    else
        echo "ERROR: missing API account credentials file i.e. NETFOUNDRY_API_ACCOUNT or a default project, user, or device credential e.g. ./credentials.json" >&2
        return 1
    fi
    echo "WARN: using API account from file $NETFOUNDRY_API_ACCOUNT" >&2
    for TOKEN in NETFOUNDRY_CLIENT_ID NETFOUNDRY_PASSWORD NETFOUNDRY_OAUTH_URL; do
        printf 'export %s="%s"\n' \
            $TOKEN \
            $(python -c '
import json,sys;
varmap = {
    "NETFOUNDRY_CLIENT_ID": "clientId", 
    "NETFOUNDRY_PASSWORD": "password", 
    "NETFOUNDRY_OAUTH_URL": "authenticationUrl"
}; 
print(json.load(sys.stdin)[varmap["'$TOKEN'"]]);
            ' < $NETFOUNDRY_API_ACCOUNT)
    done
}

[[ ! -z ${NETFOUNDRY_CLIENT_ID:-} && ! -z ${NETFOUNDRY_PASSWORD:-} && ! -z ${NETFOUNDRY_OAUTH_URL:-} ]] && {
    echo "WARN: using API account from environment variables for $NETFOUNDRY_OAUTH_URL" >&2
} || {
    source <(_get_api_account)
}

[[ ! -z ${NETFOUNDRY_CLIENT_ID:-} && ! -z ${NETFOUNDRY_PASSWORD:-} && ! -z ${NETFOUNDRY_OAUTH_URL:-} ]] || {
    echo "ERROR: API account not found in env vars or default file paths for project, user, or device" >&2
    return 1
}

NETFOUNDRY_API_TOKEN=$(_get_nf_token ${NETFOUNDRY_CLIENT_ID} ${NETFOUNDRY_PASSWORD} ${NETFOUNDRY_OAUTH_URL})

[[ ${NETFOUNDRY_API_TOKEN} =~ ^[A-Za-z0-9_=-]+\.[A-Za-z0-9_=-]+\.?[A-Za-z0-9_.+/=-]*$ ]] && {
    export NETFOUNDRY_API_TOKEN
} || {
    echo "ERROR: invalid JWT for NETFOUNDRY_API_TOKEN: '${NETFOUNDRY_API_TOKEN}'" >&2
    return 1
}

MOPENV=$(_get_mop_env ${NETFOUNDRY_OAUTH_URL})

Command-line Examples

These show how the script above obtains the token. Use your API account (clientId, password, authenticationUrl) to obtain a temporary access_token from the identity provider. Here are examples for HTTPie and cURL to get you started.

NETFOUNDRY_CLIENT_ID=3tcm6to3qqfu78juj9huppk9g3
NETFOUNDRY_PASSWORD=149a7ksfj3t5lstg0pesun69m1l4k91d6h8m779l43q0ekekr782
NETFOUNDRY_OAUTH_URL=https://netfoundry-production-xfjiye.auth.us-east-1.amazoncognito.com/oauth2/token

HTTPie

❯ http --form --auth "${NETFOUNDRY_CLIENT_ID}:${NETFOUNDRY_PASSWORD}" \
    POST ${NETFOUNDRY_OAUTH_URL} \
    "scope=https://gateway.production.netfoundry.io//ignore-scope" \
    "grant_type=client_credentials"

cURL

❯ curl --user ${NETFOUNDRY_CLIENT_ID}:${NETFOUNDRY_PASSWORD} \
    --request POST ${NETFOUNDRY_OAUTH_URL} \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data 'grant_type=client_credentials&scope=https%3A%2F%2Fgateway.production.netfoundry.io%2F%2Fignore-scope'

Send a Request to the NetFoundry API

Include the token in your request to the NetFoundry API. You could source the shell script above to make NETFOUNDRY_API_TOKEN available in the current shell.

HTTPie

❯ http GET https://gateway.production.netfoundry.io/core/v2/networks \
  "Authorization: Bearer ${NETFOUNDRY_API_TOKEN}"

cURL

❯ curl https://gateway.production.netfoundry.io/core/v2/networks \
    --header "Authorization: Bearer ${NETFOUNDRY_API_TOKEN}"