Using OAuth

A very basic summary of how OAuth works is:
  1. client sends the client_secret to the oauth server
  2. oauth server returns an access token
  3. client sends the authorization token to the service
  4. service uses the token to communicate with the oauth server

All interactions with the OAuth server are done over https with the address in "token_endpoint." Here's a shell function that uses curl and jq with your credentials file to obtain an access token and store it in a shell variable.

The first step is to request a bearer token using your provided client ID and client secret. The information provided should look something like: 

    {
        "token_endpoint": "https://authz.itlab.stanford.edu/token",
        "grant_type": "client_credentials",
        "scope": "netdb:all",
        "client_id": "netid",
        "client_secret": "..."
    }
The general curl command to get a bearer token is: 
    curl -s -u "{client_id}:{client_secret}" -d grant_type=client_credentials -d scope={scope} {token_endpoint}
using the values from our example credentials yields the command: 
    curl -s -u "netid:{client_secret}" -d grant_type=client_credentials -d "scope=netdb:all" "https://authz.itlab.stanford.edu/token"
And the server response will look like: 
    {
        "access_token": "{access_token}",
        "token_type": "Bearer",
        "expires_in": 3599,
        "scope": "netdb:all"
    }
The {access_token} is what the web service will need in order to authenticate, and expects the token in the headers. In the case of curl, the -H argument is how headers are specified: 
    curl -X GET "https://netdb-dev-api.stanford.edu/nodes/{node}" -H "Authorization: Bearer {access_token}"
It's important to note that each token is (currently) good for an hour, and that the web service does cache tokens. That means that although you can get a new token for every call, it will be slower than re-using a token until it expires.