Docs Revamp: Organizations and Security (#150)

NimaBoscarino · stevhliu · osanseviero · web-flow · commit c0dd0f9c02ff · 2022-05-20T13:21:01.000-07:00
Add docs for organizations, security, API

Co-authored-by: Steven Liu &lt;59462357+stevhliu@users.noreply.github.com&gt;
Co-authored-by: Omar Sanseviero &lt;osanseviero@gmail.com&gt;
diff --git a/docs/assets/hub/organizations-members.png b/docs/assets/hub/organizations-members.png
diff --git a/docs/assets/hub/security-soc-1.jpeg b/docs/assets/hub/security-soc-1.jpeg
diff --git a/docs/hub/_sections.yml b/docs/hub/_sections.yml
@@ -11,4 +11,13 @@
   title: Spaces
 
 - local: datasets-main
-  title: Datasets
+  title: Datasets
+
+- local: organizations-main
+  title: Organizations
+
+- local: security-main
+  title: Security
+
+- local: api-main
+  title: Hub API Endpoints
diff --git a/docs/hub/api-main.md b/docs/hub/api-main.md
diff --git a/docs/hub/organizations-cards.md b/docs/hub/organizations-cards.md
@@ -0,0 +1,27 @@
+---
+title: Organization cards
+---
+
+<h1>Organization cards</h1>
+
+You can create an organization card to help users learn more about what your organization is working on and how users can use your libraries, models, datasets, and Spaces. 
+
+An organization card is displayed on an organization's profile:
+
+![/docs/assets/hub/org-card.png](/docs/assets/hub/org-card.png)
+
+
+If you're a member of an organization, you'll see a button to create or edit your organization card on the organization's main page. Organization cards are a `README.md` static file inside a Space repo named `README`. The card can be as simple as Markdown text, or you can create a more customized appearance with HTML.
+
+The card for the [Hugging Face Course organization](https://huggingface.co/huggingface-course), shown above, [contains the following HTML](https://huggingface.co/spaces/huggingface-course/README/blob/main/README.md):
+
+```html
+<p>
+This is the organization grouping all the models and datasets used in the <a href="https://huggingface.co/course/chapter1" class="underline">Hugging Face course</a>.
+</p>
+```
+
+For more examples, take a look at:
+
+* [Amazon's](https://huggingface.co/spaces/amazon/README/blob/main/README.md) organization card source code
+* [spaCy's](https://huggingface.co/spaces/spacy/README/blob/main/README.md) organization card source code.
diff --git a/docs/hub/organizations-main.md b/docs/hub/organizations-main.md
@@ -0,0 +1,15 @@
+---
+title: Organizations
+---
+
+<h1>Organizations</h1>
+
+The Hugging Face Hub offers **Organizations**, which can be used to group accounts and manage datasets, models, and Spaces. The Hub also allows admins to set user roles to [**control access to repositories**](./organizations-security) and manage their organization's [subscription](https://huggingface.co/pricing).
+
+If an organization needs to track user access to a dataset due to licensing or privacy issues, an organization can enable [user access requests](./datasets-gated).
+
+## Contents
+
+- [Managing Organizations](./organizations-managing)
+- [Organization Cards](./organizations-cards)
+- [Access Control in Organizations](./organizations-security)
diff --git a/docs/hub/organizations-managing.md b/docs/hub/organizations-managing.md
@@ -0,0 +1,21 @@
+---
+title: Managing organizations
+---
+
+<h1>Managing organizations</h1>
+
+## Creating an organization
+
+Visit the [New Organization](https://hf.co/organizations/new) form to create an organization.
+
+## Managing members
+
+New members can be added to an organization by visiting the **Organization settings** and clicking on the **Members** tab. There, you'll be able to generate an invite link, add members individually, or send out email invitations in bulk. If the **Allow requests to join from the organization page** setting is enabled, you'll also be able to approve or reject any pending requests on the **Members** page.
+
+![The "Members" panel for an Organization](/docs/assets/hub/organizations-members.png)
+
+You can also revoke a user's membership or change their role on this page.
+
+## Organization domain name
+
+Under the **Account** tab in the Organization settings, you can set an **Organization domain name**. Specifying a domain name will allow any user with a matching email address on the Hugging Face Hub to join your organization.
diff --git a/docs/hub/organizations-security.md b/docs/hub/organizations-security.md
@@ -0,0 +1,17 @@
+---
+title: Access control in organizations
+---
+
+<h1>Access control in organizations</h1>
+
+Members of organizations can have three different roles: `read`, `write` or `admin`:
+
+- `read`: read-only access to the Organization's repos and metadata/settings (eg, the Organization's profile, members list, API token, etc).
+
+- `write`: additional write rights to the Organization's repos. Users can create, delete or rename any repo in the Organization namespace. A user can also edit and delete files from the browser editor and push content with `git`.
+
+- `admin`*: in addition to write rights on repos, admin members can update the Organization's profile, refresh the Organization's API token, and manage Organization members.
+
+As an organization `admin`, go to the **Members** section of the org settings to manage roles for users.
+
+![/docs/assets/hub/org-members-page.png](/docs/assets/hub/org-members-page.png)
diff --git a/docs/hub/security-gpg.md b/docs/hub/security-gpg.md
@@ -0,0 +1,93 @@
+---
+title: Signing commits with GPG
+---
+
+<h1>Signing commits with GPG</h1>
+
+`git` has an authentication layer to control who can push commits to a repo, but it does not authenticate the actual commit authors.
+
+In other words, you can commit changes as `Elon Musk <elon@tesla.com>`, push them to your preferred `git` host (for instance github.com), and your commit will link to Elon's GitHub profile. (Try it! But don't blame us if Elon gets mad at you for impersonating him.)
+
+The reasons we implemented GPG signing were:
+- To provide finer-grained security, especially as more and more Enterprise users rely on the Hub.
+- To provide ML benchmarks backed by a cryptographically-secure source.
+
+See Ale Segala's [How (and why) to sign `git` commits](https://withblue.ink/2020/05/17/how-and-why-to-sign-git-commits.html) for more context.
+
+You can prove a commit was authored by you with GNU Privacy Guard (GPG) and a key server. GPG is a cryptographic tool used to verify the authenticity of a message's origin. We'll explain how to set this up on Hugging Face below.
+
+The Pro Git book is, as usual, a good resource about commit signing: [Pro Git: Signing your work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work).
+
+## Setting up signed commits verification
+
+You will need to install [GPG](https://gnupg.org/) on your system in order to execute the following commands.
+> It's included by default in most Linux distributions.
+> On Windows, it is included in Git Bash (which comes with `git` for Windows).
+
+You can sign your commits locally using [GPG](https://gnupg.org/).
+Then configure your profile to mark these commits as **verified** on the Hub,
+so other people can be confident that they come from a trusted source.
+
+For a more in-depth explanation of how git and GPG interact, please visit the the [git documentation on the subject](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work)
+
+Commits can have the following signing statuses:
+
+| Status            | Explanation                                                  |
+| ----------------- | ------------------------------------------------------------ |
+| Verified          | The commit is signed and the signature is verified           |
+| Unverified        | The commit is signed but the signature could not be verified |
+| No signing status | The commit is not signed                                     |
+
+For a commit to be marked as **verified**, you need to upload the public key used to sign it on your Hugging Face account.
+
+Use the `gpg --list-secret-keys` command to list the GPG keys for which you have both a public and private key.
+A private key is required for signing commits or tags.
+
+If you don't have a GPG key pair or you don't want to use the existing keys to sign your commits, go to **Generating a new GPG key**.
+
+Otherwise, go straight to  [Adding a GPG key to your account](#adding-a-gpg-key-to-your-account).
+
+## Generating a new GPG key
+
+To generate a GPG key, run the following:
+
+```bash
+gpg --gen-key
+```
+
+GPG will then guide you through the process of creating a GPG key pair.
+
+Make sure you specify an email address for this key, and that the email address matches the one you specified in your Hugging Face [account](https://huggingface.co/settings/account).
+
+## Adding a GPG key to your account
+
+1. First, select or generate a GPG key on your computer. Make sure the email address of the key matches the one in your Hugging Face [account](https://huggingface.co/settings/account) and that the email of your account is verified.
+
+2. Export the public part of the selected key:
+
+```bash
+gpg --armor --export <YOUR KEY ID>
+```
+
+3. Then visit your profile [settings page](https://huggingface.co/settings/keys) and click on **Add GPG Key**.
+
+Copy & paste the output of the `gpg --export` command in the text area and click on **Add Key**.
+
+4. Congratulations! 🎉  You've just added a GPG key to your account!
+
+## Configure git to sign your commits with GPG
+
+The last step is to configure git to sign your commits:
+
+```bash
+git config user.signingkey <Your GPG Key ID>
+git config user.email <Your email on hf.co>
+```
+
+Then add the `-S` flag to your `git commit` commands to sign your commits!
+
+```bash
+git commit -S -m "My first signed commit"
+```
+
+Once pushed on the Hub, you should see the commit with a "Verified" badge.
diff --git a/docs/hub/security-main.md b/docs/hub/security-main.md
@@ -0,0 +1,17 @@
+---
+title: Security
+---
+
+<h1>Security</h1>
+
+The Hugging Face Hub offers several security features to ensure that your code and data are secure. Beyond offering [private repositories](./repositories-best-practices) for models, datasets, and Spaces, the Hub supports access tokens, commit signatures, and malware scanning.
+
+Hugging Face is also [SOC2 Type 1 certified](https://us.aicpa.org/interestareas/frc/assuranceadvisoryservices/aicpasoc1report.html), meaning we provide security certification to our customers and actively monitor and patch any security weaknesses.
+
+![SOC Type 1 Certification logo](/docs/assets/hub/security-soc-1.jpeg)
+
+## Contents
+
+- [User Access Tokens](./security-tokens)
+- [Signing commits with GPG](./security-gpg)
+- [Malware Scanning](./security-malware)
diff --git a/docs/hub/security-malware.md b/docs/hub/security-malware.md
@@ -0,0 +1,17 @@
+---
+title: Malware Scanning
+---
+
+<h1>Malware Scanning</h1>
+
+We run every file of your repositories through a [malware scanner](https://www.clamav.net/).
+
+Scanning is triggered at each commit or when you visit a repository page.
+
+Here is an [example view](https://huggingface.co/mcpotato/42-eicar-street/tree/main) of an infected file:
+
+![/docs/assets/hub/eicar-hub-tree-view.png](/docs/assets/hub/eicar-hub-tree-view.png)
+
+![/docs/assets/hub/eicar-hub-file-view.png](/docs/assets/hub/eicar-hub-file-view.png)
+
+_Note_: if your file has neither an ok nor infected badge, it could mean that it is either currently being scanned, waiting to be scanned, or that there was an error during the scan. It can take up to a few minutes to be scanned.
diff --git a/docs/hub/security-tokens.md b/docs/hub/security-tokens.md
@@ -0,0 +1,60 @@
+---
+title: User Access Tokens
+---
+
+<h1>User access tokens</h1>
+
+
+## What are User Access Tokens?
+
+User Access Tokens are the preferred way to authenticate an application or notebook to Hugging Face services. You can manage your access tokens in your [settings](https://huggingface.co/settings/tokens).
+
+![/docs/assets/hub/access-tokens.png](/docs/assets/hub/access-tokens.png)
+
+Access tokens allow applications and notebooks to perform specific actions specified by the scope of the roles shown in the following:
+
+- `read`: tokens with this role can only be used to provide read access to repositories you could read. That includes public and private repositories that you, or an organization you're a member of, own. Use this role if you only need to read content from the Hugging Face Hub (e.g. when downloading private models or doing inference).
+
+- `write`: tokens with this role additionally grant write access to the repositories you have write access to. Use this token if you need to create or push content to a repository (e.g., when training a model or modifying a model card).
+
+## How to manage User Access Tokens?
+
+To create an access token, go to your settings, then click on the [Access Tokens tab](https://huggingface.co/settings/tokens). Click on the **New token** button to create a new User Access Token.
+
+![/docs/assets/hub/new-token.png](/docs/assets/hub/new-token.png)
+
+Select a role and a name for your token and voilà - you're ready to go!
+
+You can delete and refresh User Access Tokens by clicking on the **Manage** button.
+
+![/docs/assets/hub/delete-token.png](/docs/assets/hub/delete-token.png)
+
+## How to use User Access Tokens?
+
+There are plenty of ways to use a User Access Token to access the Hugging Face Hub, granting you the flexibility you need to build awesome apps on top of it.
+
+User Access Tokens can be:
+- used **in place of a password** to access the Hugging Face Hub with git or with basic authentication.
+- passed as a **bearer token** when calling the [Inference API](https://huggingface.co/inference-api).
+- used in the Hugging Face Python libraries, such as `transformers` or `datasets`:
+
+```python
+from transformers import AutoModel
+
+access_token = "hf_..."
+
+model = AutoModel.from_pretrained("private/model", use_auth_token=access_token)
+```
+
+⚠️ Try not to leak your token! Though you can always rotate it, anyone will be able to read or write your private repos in the meantime which is 💩
+
+### Best practices
+
+We recommend you create one access token per app or usage. For instance, you could have a separate token for:
+ * A local machine.
+ * A Colab notebook.
+ * An awesome custom inference server. 
+ 
+ This way, you can invalidate one token without impacting your other usages.
+
+We also recommend only giving the appropriate role to each token you create. If you only need read access (i.e., loading a dataset with the `datasets` library or retrieving the weights of a model), only give your access token the `read` role.
