From 8ed0543d644e0b54581a2010d80fb452537d64ed Mon Sep 17 00:00:00 2001
From: Johannes Keyser <johannes.keyser@sport.uni-giessen.de>
Date: Tue, 12 Apr 2022 14:46:44 +0200
Subject: [PATCH] Add English translation of handling authentication
---
de/Hilfe.md | 1 -
en/Help.md | 144 +++++++++++++++++++++++++++++++++++++++++++++++++---
2 files changed, 138 insertions(+), 7 deletions(-)
diff --git a/de/Hilfe.md b/de/Hilfe.md
index 3a69edf..fc4fe5f 100644
--- a/de/Hilfe.md
+++ b/de/Hilfe.md
@@ -142,7 +142,6 @@ Um ein PAT zu erstellen:
Nun wird die eindeutige, zufällige Zeichenkette des neuen Tokens angezeigt, beispielsweise `aztGzZkCT-kGyRs1M6x1`.
Da die Zeichenkette nur direkt nach dem Erstellen angezeigt wird, sollten Sie sie sofort [zur Verwendung sicher speichern (siehe unten)](#sicheres-speichern-und-verwenden-eines-access-tokens).
-
#### Sicheres Speichern und Verwenden eines Access Tokens
Um ein Access Token zu nutzen, muss es für jede Verbindung mit GitLab vorliegen.
diff --git a/en/Help.md b/en/Help.md
index c2e1ef3..391ef90 100644
--- a/en/Help.md
+++ b/en/Help.md
@@ -5,7 +5,6 @@ For specific information about JLU GitLab, see [information](Information.md).
[[_TOC_]]
-
## Important concepts
Git and GitLab are versatile tools using many technical concepts and terms.
@@ -41,21 +40,154 @@ This is only a well-intended overview; [further help](#further-help) provides a
## How to use GitLab?
-There are to major ways to use the various functions of GitLab.
+There are two major ways to use the various functions of GitLab.
Working via web browser is particularly convenient: For example, you can read content, comment on issues, edit wiki pages, and also edit files in the Git repository via the [web editor](https://docs.gitlab.com/ee/user/project/repository/web_editor.html) or the [Web IDE](https://docs.gitlab.com/ee/user/project/web_ide/).
For more extensive changes, it is recommended to work on a local copy of a Git repository.
For this you need Git on your computer to keep your local copy in sync with the one on GitLab (via Git `pull` and `push`).
Most common programming software (like Matlab or RStudio) support working with a local Git repository.
-To synchronize your changes with JLU GitLab you need to [authenticate yourself](#how-to-access-and-authenticate-at-jlu-gitlab).
+To synchronize your changes with JLU GitLab you need to [connect](#how-to-connect-to-jlu-gitlab) and [authenticate yourself](#how-to-authenticate-to-jlu-gitlab).
+
+
+## How to connect to JLU GitLab?
+
+JLU GitLab is accessible via two network protocols: via `HTTPS` or via `SSH`.
+Each application (such as web browser, Git, etc.) must use one of these protocols.
+
+Connections via HTTPS are recommended and are possible directly from the Internet.
+HTTPS provides access to all GitLab features (Git-over-HTTP and GitLab APIs).
+Authentication is possible via [JLU access data](#authentication-with-jlu-credentials) (insecure and inflexible) or via [Access Token](#authentication-with-access-token) (secure and flexible).
+
+Connections via SSH are only possible [via VPN](https://www.uni-giessen.de/fbz/svc/hrz/svc/netz/campus/vpn).
+SSH only provides synchronization of Git repositories, no other GitLab functions.
+For authentication you need [an SSH key](#authentication-with-ssh-key).
+
+Beware to select the URL with your desired connection type when you _clone_ a Git repository:
+
+
+
+
+## How to authenticate to JLU GitLab?
+
+To gain access to your GitLab account or your projects, you need to [authenticate](https://en.wikipedia.org/wiki/Authentication) to JLU GitLab.
+
+To [register your account](#how-to-register-an-account), you will need to log in once via browser using your JLU credentials.
+Once you have an account, there are several authentication methods you can choose from.
+
+Here are 3 methods of authentication compared to help weigh security and usability.
+Spoiler: The recommended method is [authentication with a (personal) access token](#authentication-with-access-token) as soon as the functions in the browser are no longer sufficient for you.
+
+- By [HRZ identifier and password](#authentication-with-access-token).
+- By [(personal) access token](#authentication-with-access-token).
+- By [SSH key](#authentication-with-ssh-key).
+
+Here is an overview of the main pros and cons; explanations can be found below.
+
+| Method | Recommended | Usable with 2FA | Usable without VPN | Flexible management |
+|-----------------------|-------------|-----------------|--------------------|---------------------|
+| JLU credentials | No | Yes | No | No |
+| Personal Access Token | Yes | Yes | Yes | Yes |
+| SSH key | Partial | No | No | Partial |
+
+
+### Authentication with JLU credentials
+
+When [connecting via HTTPS](#how-connect-with-jlu-gitlab) (e.g. via web browser or Git), you can authenticate yourself with your personal JLU identifier and JLU password.
+
+The only __advantage__ of this method is its simplicity.
+
+An important __disadvantage__ of this method is its potential for damage:
+In JLU GitLab, your JLU credentials are _always_ associated with _all_ your permissions, including deleting your data and usage account.
+This can lead to the greatest possible damage in the event of user error or password theft.
+Even outside of JLU GitLab, your JLU credentials are particularly worth protecting, as they are used as a "master key" for many JLU IT systems (e.g. email access).
+If you lose your JLU password, you will no longer have access yourself (temporarily).
+
+For flexible, restricted access, especially for (automatic) access from multiple devices, it is recommended to [use access tokens](#authentication-with-access-token) instead of your JLU credentials.
+
+For higher security against theft of your JLU password, you can enable [two-factor authentication (2FA)](https://docs.gitlab.com/ee/user/profile/account/two_factor_authentication.html) in JLU GitLab.
+Note that if you enable 2FA for [Git-over-HTTPS](#how-connect-to-jlu-gitlab), you must create and use a [personal access token](#authentication-with-access-token).
+
+### Authentication with access token
+
+An *access token* is a string of random characters, generated by JLU GitLab, with associated permissions that you can use in place of your JLU credentials.
+Using access tokens requires a [connection via HTTPS](#how-to-connect-to-jlu-gitlab).
+
+__Advantages__ of this method include the separation of your sensitive HRZ credentials and the flexibility of permissions by purpose, which can limit damage in the event of theft, loss, or user error.
+
+The __disadvantages__ are the required setup and familiarization, which should be simplified by the following help texts for [creating](#creating-a-personal-access-token) and [securely storing and using](#securely-storing-and-using-access-tokens) (personal) access tokens.
+
+A [personal](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) access token (PAT) allows permissions to all areas of your GitLab account (Git-over-HTTPS and API).
+If you want to use [2-factor authentication](https://docs.gitlab.com/ee/user/profile/account/two_factor_authentication.html) for more security, you need to create and use a PAT for authentication over HTTPS (see below).
+
+In addition to _personal_ access tokens, there are also tokens for [projects](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) and [user groups](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html).
+They are used analogously to a personal token, but allow more fine-grained restrictions to individual projects or groups.
+
+#### Creating a personal access token
+
+To create a personal Access Token (PAT), log in via browser, click on your profile in the upper right corner, select *Edit profile* and then *Access Tokens* in the left side menu.
+Alternatively, you can click on [this direct link](https://gitlab.ub.uni-giessen.de/-/profile/personal_access_tokens).
+
+Note that you can create multiple PATs for different purposes; for example, one for your laptop and another one with fewer permissions and earlier expiration date for a lab computer.
+
+To create a PAT:
+
+1. For __Token name__ choose an appropriate name for the token, for example the name of the device for which the token is intended.
+2. If possible, assign an expiry date for the validity of the token under __Expiry date__.
+ This consideration depends on the intended purpose.
+3. Allow the required permissions for the intended purpose of the token;
+ for example __write\_repository__ is sufficient for read and write access to all your Git repositories.
+ An overview of possible permissions can be found [here](https://gitlab.ub.uni-giessen.de/help/user/profile/personal_access_tokens.md#personal-access-token-scopes).
+4. Click *Create personal access token*:
+ Now the unique random string of the new token is displayed, for example `aztGzZkCT-kGyRs1M6x1`.
+ Since the string is displayed only immediately after creation, you should [save it securely for use (see below)](#securely-storing-and-using-access-tokens) immediately.
+
+#### Securely storing and using access tokens
+
+To use an access token, it must be available for each connection to GitLab.
+Rather than repeatedly typing it or storing it unsecured, the following recommended method is to store a token in an encrypted storage.
+<!--
+Note: Insecure storage is also possible; make sure your Git configuration meets your security needs.
+Because of the encryption used, this method is only useful for interactive work.
+(And since automated access requires further knowledge and consideration anyway, it will not be discussed further here).
+-->
+
+##### Requirement: Encrypted store for Git credentials
+
+Current Git versions support encrypted storage of your login credentials.
+Depending on the operating system, encryption is implemented by different utilities.
+
+When installing the current, [official Git client](https://git-scm.com/) on _Windows_ or _macOS_, secure defaults are set that use the native encrypted store.
+In this case, no configuration is required from you.
+You can view and modify the configured utility via `git config credential.helper`; the default secure setting for Windows is `manager-core`, for macOS `osxkeychain`.
+
+For _Linux_, or if you want to use _multifactor authentication_, the [*Git Credential Manager (GCM)*](https://github.com/GitCredentialManager/git-credential-manager#git-credential-manager) utility is recommended.
+On Linux, after [installing and configuring *GCM*](https://github.com/GitCredentialManager/git-credential-manager#linux), you also need to decide on a [*credential store*](https://github.com/GitCredentialManager/git-credential-manager/blob/main/docs/credstores.md#credential-stores), for example *SecretService*, via `git config --global credential.credentialStore secretservice`.
+
+##### Securely storing and using tokens
+
+If the [requirement for secure storage](#requirement-encrypted-store-for-git-credentials) is met and you have [created a token](#creating-a-personal-access-token), only two steps remain to use the token:
+
+1. Start any Git action from your device that requires authentication to GitLab via HTTPS; for example, read access to a private project via `git pull` or `git clone`.
+ Be sure to use an HTTPS URL that starts with `https://` (if in doubt, check the configured Git remote URL).
+2. Enter your new token *in place of your password* when asked for your login data:
+ - As username, enter your JLU identifier.
+ - For the password, enter the token's string you received during [creation](#creating-a-personal-access-token), for example `aztGzZkCT-kGyRs1M6x1`.
+
+Here is a screenshot of the expected dialog box of Windows 10:
+
+
+
+### Authentication with SSH key
-## How to access and authenticate at JLU GitLab?
+Note that access via SSH is only possible [via VPN](https://www.uni-giessen.de/fbz/svc/hrz/svc/netz/campus/vpn).
-Please note that access from the Internet is restricted to HTTPS; access via SSH is only possible [via VPN](https://www.uni-giessen.de/fbz/svc/hrz/svc/netz/campus/vpn/).
+The __advantages and disadvantages__ of this method hover between the insecure and inflexible use of your HRZ credentials and the more secure and flexible [authentication via access token](#authentication-with-access-token).
-If you use [2-factor authentication](https://docs.gitlab.com/ee/user/profile/account/two_factor_authentication.html) and want to interact via HTTPS, you have to create a [personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) and use it in place of your password.
+To create an SSH key pair there are [instructions in the book *Pro Git*, chapter 4.3](https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key).
+Afterwards you have to deposit the public(!) key to your JLU GitLab account.
+Read for example [this documentation](https://gitlab.ub.uni-giessen.de/help/ssh/index.md#add-an-ssh-key-to-your-gitlab-account).
## How to register an account?
--
GitLab