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
- Start a free trial if you need a login for NF Console
- Log in to NF Console
- In NF Console, navigate to “Organization”, “Manage API Account”, and click
- Click the button to download “credentials.json”
- Save in one of
- project default:
./credentials.json
- user default:
~/.netfoundry/credentials.json
- device default:
/netfoundry/credentials.json
- project default:
You may override the default paths with an environment variable.
NETFOUNDRY_API_ACCOUNT=~/Downloads/example-account.json
Get a Token in the Current Shell
Conveniently use your API account in a shell with this script.
# 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 Script
Preview
# 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}"