The BCL API requires a Service Account to support authentication, authorization and data transfer.
For security reasons, we request that you use different service accounts for BCL’s staging and production environments. This gives you the ability to separately control who on your end has access to each environment.
Supported Service Accounts
We support Service Accounts provided by Google. The account will need to be established in your own GCP project, where you will need to maintain full control of its access and private keys. Additional information regarding impersonation and private keys can be found in our help center.
We require the following information for Google service accounts:
- Email Address (Required): the full email address of the service account. It will most likely end with @iam.gserviceaccount.com.
- OAuth2 Client ID (Required): the numeric identifier for your service account in Google. You can find this on the IAM > Service Account page, in a column labeled “OAuth 2 Client ID”.
Auth0
We can establish a service account on your behalf through our Auth0 environment, and provide you access to generate tokens and rotate your client secrets as needed. For Auth0 service accounts, we require the following information:
- Service Account Name (Required): A human-readable name we will associate with your service account. This can be your organization name. We will create an email address for your service account and provide it to you. It will be in the form {service_account_name}@clients.broadinstitute.org.
- Admin Emails (Required): One or more email addresses of people in your organization who will administer the service account. These people will be granted access in Auth0 to download the client ID and client secret, and rotate the secret as needed. These users will need to retrieve the Client ID and secret from the Auth0 user interface.
Service Accounts at Other Identity Providers
If you create a service account with a different Identity Provider (IdP), we will attempt a best effort to support the service account, however cannot guarantee that it is compatible. Take note of the following pieces of information to share with the Broad team:
- Issuer (Required): the fully-qualified URL of the token issuer.
- JWKS URI (Required): a URL pointing to the public key certificates for the service account. This URL must work, and must return a payload containing one or more key IDs and corresponding certificates.
We currently require this URL to return x509 PEM certificates associated with key IDs. We can currently support v1 URLs, or v3 URLs provided they include an x5c portion for each key definition.
- Email address (Optional): the fully-qualified email address of the service account, if the service account has one.
- Identity-specific claim information (Required): If your service account does not have an email address, we will need to match other claims within incoming JWT tokens to uniquely identify your account. Depending on how your IdP generates its tokens, this might be the sub claim, or perhaps a combination of oid and tid claims. You will need to register these claims with the Broad team so we can recognize them.
We do not currently support service accounts managed by Microsoft Azure or Amazon AWS as these have so far been unable to generate tokens with sufficient claims we need for verification.
If you are unable to use Google or Auth0 SA, speak with a member of the BCL support team bcl-support@broadinstitute.org. We will attempt a best effort to support the service account, however cannot guarantee that it is compatible.