diff --git a/docs/de/navigation.yml b/docs/de/navigation.yml index bf2e185da2..0e25b8ec53 100644 --- a/docs/de/navigation.yml +++ b/docs/de/navigation.yml @@ -4,3 +4,4 @@ - /user/user/ - /user/group/ - /user/admin/ + - /user/profile/ diff --git a/docs/de/user/profile/assets/api-key-created.png b/docs/de/user/profile/assets/api-key-created.png new file mode 100644 index 0000000000..1bc4b0cc17 Binary files /dev/null and b/docs/de/user/profile/assets/api-key-created.png differ diff --git a/docs/de/user/profile/assets/api-key-overview.png b/docs/de/user/profile/assets/api-key-overview.png new file mode 100644 index 0000000000..b072d280a2 Binary files /dev/null and b/docs/de/user/profile/assets/api-key-overview.png differ diff --git a/docs/de/user/profile/index.md b/docs/de/user/profile/index.md new file mode 100644 index 0000000000..6e399bfa13 --- /dev/null +++ b/docs/de/user/profile/index.md @@ -0,0 +1,50 @@ +--- +title: Profil +partiallyActive: true +--- + +Über den Link zum Profil im Footer können Einstellungen zum eigenen Konto vorgenommen werden. + +## Passwort ändern + +Hier kann das Passwort für das Konto geändert werden, wenn es sich um ein lokales Konto handelt (wenn die Anmeldung +also nicht über ein Fremdsystem erfolgt). Um die Änderung zu autorisieren, muss zunächst das aktuelle Passwort +eingegeben werden. Danach muss das neue Passwort zweimal eingegeben werden. + +## Öffentliche Schlüssel + +Zum Prüfen von Signaturen für z. B. Commits können hier die entsprechenden öffentlichen Schlüssel hinterlegt werden. +Zudem können hier die vom SCM-Manager erstellten Signaturschlüssel heruntergeladen werden. + +## API Schlüssel + +Zur Nutzung in anderen Systemen wie z. B. CI Systemen können sogenannte API Schlüssel erstellt werden. Sie können für +den Zugriff auf Repositories über die REST API sowie über SCM-Clients genutzt werden. Dazu wird ein Anzeigename sowie +eine [Rolle](../admin/roles/) ausgewählt. Der Anzeigename ist ausschließlich zur Verwaltung gedacht und hat keine +weitere technische Bewandnis. Mithilfe der Rolle können die Berechtigungen eingeschränkt werden, die bei einer Anmeldung +zur Verfügung stehen. + +Hat z. B. ein Konto schreibende Rechte für ein Repository und wird ein API-Schlüssel mit der Rolle "READ" erzeugt, so +kann über diesen Schlüssel nur lesend auf das Repository zugegriffen werden. Eine Ausweitung der Rechte hingegen ist +selbstverständlich nicht möglich. Es kann also mithilfe eines API-Schlüssels mit der Rolle "WRITE" nicht schreibend auf +ein Repository zugegriffen werden, für das bei dem Konto nur ein lesender Zugriff gestattet ist. + +![API Key Overview](assets/api-key-overview.png) + +Nach der Erstellung eines Schlüssels, wird dieser **einmalig** angezeigt. Nachdem dieses Fenster +geschlossen wurde, kann der Schlüssel nicht mehr abgerufen und nicht wiederhergestellt werden. + +![API Key Created](assets/api-key-created.png) + +### Beispiel REST API + +Um einen Schlüssel mit der REST API zu nutzen, muss der Schlüssel als Cookie mit dem Namen „X-Bearer-Token“ +übergeben werden. Für die Nutzung mit curl sieht ein Aufruf z. B. wie folgt aus: + +``` +curl -v localhost:8081/scm/api/v2/repositories/ -H "Cookie: X-Bearer-Token=eyJhcGlLZXlJZCI...RTRHeCJ9" +``` + +### Zugriff mit SCM-Client + +Für einen Zugriff mit einem SCM-Client (z. B. `git`, `hg` oder `svn`) muss der Schlüssel als Passwort übergeben werden. diff --git a/docs/en/navigation.yml b/docs/en/navigation.yml index 3d5b6518a8..89a8367a9f 100644 --- a/docs/en/navigation.yml +++ b/docs/en/navigation.yml @@ -12,6 +12,7 @@ - /user/user/ - /user/group/ - /user/admin/ + - /user/profile/ - section: Administration entries: diff --git a/docs/en/user/profile/assets/api-key-created.png b/docs/en/user/profile/assets/api-key-created.png new file mode 100644 index 0000000000..1bc4b0cc17 Binary files /dev/null and b/docs/en/user/profile/assets/api-key-created.png differ diff --git a/docs/en/user/profile/assets/api-key-overview.png b/docs/en/user/profile/assets/api-key-overview.png new file mode 100644 index 0000000000..b072d280a2 Binary files /dev/null and b/docs/en/user/profile/assets/api-key-overview.png differ diff --git a/docs/en/user/profile/index.md b/docs/en/user/profile/index.md new file mode 100644 index 0000000000..50746c2f56 --- /dev/null +++ b/docs/en/user/profile/index.md @@ -0,0 +1,49 @@ +--- +title: Profile +partiallyActive: true +--- + +Settings for the active user account can be managed with the link "Profile" in the footer. + +## Change password + +Here the password for the current account can be changed when it is a local account (when the login is not managed by an +external system). To authorize the change, the current password has to be put first. Then the new password has to be +entered twice. + +## Öffentliche Schlüssel + +To check signatures for example for commits, public keys can be stored here. Additionally the keys created by +SCM-Manager can be accessed here, too. + +## API keys + +To access SCM-Manager from other systems like for example CI servers, API keys can be created. They can be used to call +the REST APi and for the access with SCM clients. To create a key you have to specify a display name and a +[role](../admin/roles/). The display name is solely to keep track of your keys. The role limits the permissions granted +when the SCM-Manager is accessed with such a key. + +If, for exapmple, an account has write access for a repository and an API key with the role "READ" is created for this +account, this repository can only be accessed read only using this key. Of course it is not possible to extend +permissions. So you cannot create an API key with the role "WRITE" to get write access to a repository, where the +original account has only read access for. + +![API Key Overview](assets/api-key-overview.png) + +After the creation of a key, it will be displayed **once only**. After the window has been closed, the key cannot be +retrieved or reconstructed again. + +![API Key Created](assets/api-key-created.png) + +### Example for the REST API + +To use an API key for the REST API, the key has to sent as a cookie with the name “X-Bearer-Token”. Using curl, this +can be done like this: + +``` +curl -v localhost:8081/scm/api/v2/repositories/ -H "Cookie: X-Bearer-Token=eyJhcGlLZXlJZCI...RTRHeCJ9" +``` + +### Access with an SCM-Client + +For access with an SCM client like `git`, `hg`, or `svn` the key simply has to be passed as a password.