Bintray gives you fine-grained control over how Bintray users can access your private repositories through Teams and Permissions. But what if you need to provide access to users who do not have an account with Bintray? Signed URLs give you a way to provide time-limited download links to anyone, but this is not always enough. When downloads are managed by an external tool that uses package and version metadata to download individual files (such as in the case of Docker, Debian, Yum, etc.), no single file permission can be applied. Also, when needing to map permissions from an external identity system, such as LDAP, or from an internal product entitlement system, you cannot use fully fledged Bintray accounts that are publicly visible and require users to sign-up to Bintray. This is where Entitlements and Access Keys come into play.
This page describes how to work with signed URLs and Entitlements.
When you (as a Bintray Organization) purchase one of Bintray’s Premium plans, Bintray creates a signing key for you which you can use to sign URLs. Signed URLs give you fine-grained access control over specific files in any of your premium repositories. The main benefit of this feature is that it is a convenient way to distribute files from a private repository to users who do not have general access, or even to users who do not have a Bintray account at all, without exposing any other content in that private repository. An additional benefit is that whether your repository is private or not, signed URLs authenticate you as the distributor of the file by validating the signed URL against your signing key.
Generating a Signed URL
You can generate a signed URL using the URL signing API call. With this call, you specify which file you want to distribute, as well as an optional expiry date for the generated URL.
Regenerating Your Signing Key
You can regenerate your URL signing key at any time, and there are two ways to do this:
Once you regenerate your organization’s URL signing key, any signed URLs that you have previously distributed will be rendered invalid.
Entitlements and Access Keys
Entitlements are permissions assigned to different entities that contain files. These may be:
Paths in a repository
*Version level entitlements are available in all repository types except Maven.
Access Keys are unique identifiers generated for anyone who is not in one of your Bintray teams (such as external users), and to which permissions specified in Entitlements are assigned. Optional parameters are available including: expiry of key, existence check of the source identity, and CIDRs to control access from different IPs.
How Do They Work?
The way it works is that you (as a Bintray Organization) create access keys where each key has its associated password. Then you create entitlements to define what access privileges are provided to your Bintray resources for these access keys. You can now provide the keys and passwords to external users who use them to access your Bintray resources using the Bintray API. The external users can only access your Bintray resources that are specified in entitlements.
You can assign any number of access keys to an entitlement, and the same access key can be associated with any number of entitlements. An access key is always scoped to the subject it is created under, so other users cannot see it.
Scoped Users - Signing In With Access Keys
Any user who has received an access key can use that key (together with the password provided) to sign in to and navigate through Bintray. When signing in with an access key, the user is "scoped" and can only access those parts of the Bintray UI that are accessible according to the entitlements associated with the access key.
Sample Use Case
Say, for example, that you’ve created a Docker repo named "client1-images" under the "myorg" organization, and you’ve also created a download key under "myorg" with the id of "bob" and the password "secret".
Now, to allow bob to use the "client1-images" Docker repo, you simply need to create an entitlement on the "client1-images" repo containing the "bob" download key id (in the
access_keys field), with "rw" access.
This will allow the user bob to push and pull from the "client1-images" repo using the username "bob@myorg" (remember, access keys are scoped) and the password "secret".
You can attach any number of arbitrary strings as tags to any entitlement you create, and then search for entitlements according to those tags. This offers a way to categorize entitlements according to any scheme you find convenient. To manage entitlement tags (i.e. add or delete them to existing entitlements), you can use the Update Entitlement REST API endpoint.
For more information about how to create and use entitlements, please refer to the Entitlements REST API.