Background
In order to authenticate against Blackfynn’s PPMI 2.0 API we require our partners use the OAuth 2.0 client credentials grant to generate a temporary access token with which to make requests.
The client credentials grant requires the use of a client_id
and client_secret
.
Blackfynn generates a client with the above credentials, which uniquely identifies each of our partners. This information is private and should be stored securely by our partners. Please see our guide to Safely Storing Credentials for securely storing and managing your client credentials.
In order to securely transmit these credentials to our partners we rely on the cryptographic encryption software GPG. Below is a step-by-step guide for our partners to help us facilitate this transfer.
Instructions
The below instructions are specific to a Unix or MacOS X environment. If you are using Windows we recommend using the GUI GPG application Gpg4win. The instruction text is hopefully generic enough to apply to a GUI program but if not please reach out to us.
Install GPG
- On macOS X we recommend using the package manager Homebrew. Once you have homebrew installed you can run:
brew install gnupg
- For other *nix operating systems we recommend usings the systems default package manager CLI tool to install GPG. For example, on Debian-based operating system such as Ubuntu you can use the package manager
apt
to run:apt-get install gnupg2
Create a GPG Key Pair
Once you have GPG installed you’ll need to create a GPG key pair (public and private key).
- Create a new primary key pair:
gpg --full-generate-key
- Select (1) RSA and RSA (default) for the type of key.
- Enter
4096
for the key size. - Enter
1m
(one month) for the expiration of your key pair. - Enter a name, email address, and comment to associate with the key pair.
- Enter a passphrase of your choosing. Ensure the passphrase is strong by including multiple-case alphanumeric characters.
- If you see the following message, the system requires more entropy to generate a key pair. You can accomplish this by typing randomly into your keyboard:We need to generate a lot of random bytes. It is a good idea to perform some other action (type on the keyboard, move the mouse, utilize the disks) during the prime generation; this gives the random number generator a better chance to gain enough entropy.
You can verify the key pair has been added to your keyring using: gpg --list-keys
Export your GPG Public Key
Once you’ve created a GPG key pair you’ll need to export its public key and send it to Blackfynn.
- Export the public key. Replace
user@example.com
with the email address associated with the key’s owner’s email address. Replace public-key.gpg with whatever name you desire for the output file. This will save the output file to your current working directory.
gpg --armor --output public-key.gpg --export user@example.com
- Send
public-key.gpg
to Blackfynn. This file will be located in your current working directory. As its name suggests, this key is public and can be shared without secrecy. Feel free to send it as an attachment in an email to directly to Blackfynn. For additional security please send your key’s fingerprint. To do so, send the full output of the below command in the above email, replacinguser@example.com
with the email you used to generate the GPG key above:
gpg --fingerprint user@example.com
Decrypt your Client Credentials
Once you’ve sent Blackfynn your GPG public key we’ll send you a downloadable link to a GPG encrypted file with your client credentials. You’ll want to decrypt this file using the instructions below and securely store these credentials. See our guide for Safely Storing Credentials for best practices relevant to securely storing your credentials.
- Download the file at the link sent to you from Blackfynn. The file should be named
example-credentials.gpg
where example should be your company’s name. - Decrypt your client credentials. Replace
example-credentials.json
with the name of the output you would like your decrypted client credentials saved to.gpg \ --output example-credentials.json \ --decrypt /path/to/example-credentials.gpg
- The contents of the decrypted client credentials file should be a JSON document containing two keys,
client_id
andclient_secret
, each containing respective values.
cat example-credentials.json
{
"client_id": "...",
"client_secret": "..."
}