In order to authenticate against Blackfynn’s Clinical Data Management System (CDMS) API we require our partners to 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
To understand how Blackfynn generates and securely distributes these credentials to our partners see our GPG Encryption Guide.
Once in the possession of our partners, we ask you to follow these best practices for securely storing your credentials.
As a developer, you'll be working with credentials issued to you by Blackfynn, as well as token values representing the specific features of your application.
Client ID and secret
- Your Client ID identifies your application and appears in OAuth token negotiation requests. Your Client ID can be shared freely in code and email. It cannot be used alone to act on your application's behalf.
- Your Client Secret should be considered private. It is how you securely authenticate your application’s identity when requesting access tokens from Blackfynn.
Once you’ve exchanged your client credentials for an access token you’ll be given an access token scoped to the resources related to the requests you’d like to make to the Blackfynn API. These tokens should be considered opaque. Practically, they are signed JWTs with which Blackfynn is able to authenticate and authorize requests. Access tokens come with an expiration date. Expired access tokens can be newly generated using the same client credentials grant flow they were initially generated with.
Safely storing authentication secrets is important, and how you do it best depends on context, usage, and design requirements. Here are some ways to ensure that you’re doing everything you can to prevent the accidental exposure of your secrets.
- Do not store your client secret in any public or semi-public formats. This includes emails, instant messages, code repositories, or within native or client applications.
- Do store your client secret within a persistent storage solution which preferably allows for encryption at rest and during transit. (Ex. Store your client id and secret in a database which communicates with your application via SSL.)
- Do encrypt your client secret using a key which only you (or your application) have access to for decryption. (Ex. Use AWS Key Management Service to encrypt your client secret within your database and decrypt within your application for use in the client credentials grant flow.)
- Do not persist your access token. Access tokens are ephemeral and opaque. They are used to authenticate and authorize requests but not used to regenerate access themselves. These do not need to be stored above, and can be generally left in-memory in your application. You can store them temporarily outside memory but there’s no need to store them long-term.
When using your client credential or access tokens over HTTP, follow the below best practices to ensure your secrets remain private.
- Do communicate exclusively over HTTPS.
- Do not send your credentials via query parameters over GET requests. Rather use a POST request for the client credentials grant and keep the client secret restricted to the payload or request headers.
- Do request only the scopes relevant to the resources you require. When performing the client credentials grant to receive an access token you can specify the scopes relevant to the HTTP resources you wish to access in order to limit the scope of the access token itself.