Gitlab Community Edition Instance

Commit 75f3c7d7 authored by Gregor Thiem's avatar Gregor Thiem
Browse files

Update to 1.7.2

parent ee38951f
......@@ -26,3 +26,5 @@ public/views/build
public/uploads/*
!public/uploads/.gitkeep
site/
![HedgeDoc Logo](docs/images/hedgedoc_logo_horizontal.png)
![HedgeDoc Logo](docs/content/images/hedgedoc_logo_horizontal.svg)
# HedgeDoc
......@@ -12,16 +12,16 @@ it by visiting our [HedgeDoc demo server][hedgedoc-demo].
It is inspired by Hackpad, Etherpad and similar collaborative editors. This
project originated with the team at [HackMD](https://hackmd.io) and now forked
into its own organisation. [A longer writeup can be read in the history doc](docs/history.md).
into its own organisation. [A longer writeup can be read in the history][history].
[![HedgeDoc 1.7.0 with its feature demonstration page open](docs/images/HedgeDoc-1.7.0-features.png)][hedgedoc-demo-features]
[![HedgeDoc 1.7.0 with its feature demonstration page open](public/screenshot.png)][hedgedoc-demo-features]
## Community and Contributions
We welcome contributions! There's a lot to do: If you would like to report bugs,
the [issue tracker][github-issue-tracker] is the right place. If you can help
translating, find us on [POEditor][poeditor-url]. To get started developing,
take a look at the [docs/dev](docs/dev) directory. In any case: come talk to us,
take a look at the [developer documentation][developer-documentation]. In any case: come talk to us,
we'll be delighted to help you with the first steps.
To stay up to date with our work or get support it's recommended to join our
......@@ -34,21 +34,20 @@ regular [community calls][hedgedoc-community-calls] ([RSS](https://community.hed
You can run HedgeDoc in a number of ways, and we created setup instructions for
all of these:
- [Docker](docs/setup/docker.md)
- [Kubernetes](docs/setup/kubernetes.md)
- [Cloudron](docs/setup/cloudron.md)
- [LinuxServer.io (multi-arch docker)](docs/setup/docker-linuxserver.md)
- [Heroku](docs/setup/heroku.md)
- [Manual setup](docs/setup/manual-setup.md)
- [Docker][setup-docker]
- [Cloudron][setup-cloudron]
- [LinuxServer.io (multi-arch docker)][setup-docker-linuxserver]
- [Heroku][setup-heroku]
- [Manual setup][setup-manual]
## Configuration
Theres two main ways to [configure](docs/configuration.md) your HedgeDoc instance:
Theres two main ways to [configure][configuration] your HedgeDoc instance:
config file or environment variables. You can choose what works best for you.
HedgeDoc can integrate with
- facebook, twitter, github, gitlab, mattermost, dropbox, google, ldap, saml and [oauth2](docs/guides/auth/oauth.md) **for login**
- facebook, twitter, github, gitlab, mattermost, dropbox, google, ldap, saml and [oauth2][configuration-oauth] **for login**
- imgur, s3, minio, azure **for image/attachment storage** (files can also be local!)
- dropbox **for export and import**
......@@ -61,8 +60,10 @@ To use HedgeDoc, your browser should match or exceed these versions:
- ![Chrome](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/chrome/chrome_24x24.png) Chrome >= 47, ![Chrome](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/chrome/chrome_24x24.png) Chrome for Android >= 47
- ![Safari](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/safari/safari_24x24.png) Safari >= 9, ![iOS Safarai](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/safari-ios/safari-ios_24x24.png) iOS Safari >= 8.4
- ![Firefox](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/firefox/firefox_24x24.png) Firefox >= 44
- ![IE](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/archive/internet-explorer_9-11/internet-explorer_9-11_24x24.png) IE >= 9, ![Edge](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/edge/edge_24x24.png) Edge >= 12
- ![Opera](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/opera/opera_24x24.png) Opera >= 34, ![Opera Mini](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/opera-mini/opera-mini_24x24.png) Opera Mini not supported
- ![Edge](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/edge/edge_24x24.png) Edge >= 12
- ![Opera](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/opera/opera_24x24.png) Opera >=
34, ![Opera Mini](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/opera-mini/opera-mini_24x24.png)
Opera Mini not supported
- ![Android Browser](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/android-webview-beta/android-webview-beta_24x24.png) Android Browser >= 4.4
## Backup/restore your instance
......@@ -71,7 +72,7 @@ To backup HedgeDoc, you should:
- backup your database
- backup your custom config file if you have one
- backup the upload folder (see the [uploadsPath](./docs/configuration.md#hedgedoc-paths-stuff) config directive)
- backup the upload folder (see the [uploadsPath][configuration-paths] config directive)
Restoring an existing instance of HedgeDoc is then just a matter of restoring these elements.
......@@ -86,6 +87,16 @@ Licensed under AGPLv3. For our list of contributors, see [AUTHORS](AUTHORS).
The license does not include the HedgeDoc logo, whose terms of usage can be found in the [github repository](https://github.com/hedgedoc/hedgedoc-logo).
[configuration-oauth]: https://docs.hedgedoc.org/configuration/#oauth2-login
[configuration]: https://docs.hedgedoc.org/configuration/
[configuration-paths]: https://docs.hedgedoc.org/configuration/#hedgedoc-paths-stuff
[setup-docker]: https://docs.hedgedoc.org/setup/docker/
[setup-cloudron]: https://docs.hedgedoc.org/setup/cloudron/
[setup-docker-linuxserver]: https://docs.hedgedoc.org/setup/docker-linuxserver/
[setup-heroku]: https://docs.hedgedoc.org/setup/heroku/
[setup-manual]: https://docs.hedgedoc.org/setup/manual-setup/
[developer-documentation]: https://docs.hedgedoc.org/dev/getting-started/
[history]: https://docs.hedgedoc.org/history/
[matrix.org-image]: https://img.shields.io/matrix/hedgedoc:matrix.org?logo=matrix&server_fqdn=matrix.org
[matrix.org-url]: https://chat.hedgedoc.org
[github-version-badge]: https://img.shields.io/github/release/hedgedoc/hedgedoc.svg
......
......@@ -4,9 +4,9 @@ You can choose to configure HedgeDoc with either a config file or with environme
Environment variables take precedence over configurations from the config files. They generally start with `CMD_` for our own options, but we also list node-specific options you can configure this way.
- Environment variables are processed in [`lib/config/environment.js`](../lib/config/environment.js) - so this is the first place to look if anything is missing not obvious from this document. The default values are defined in [`lib/config/default.js`](../lib/config/default.js), in case you wonder if you even need to override it.
- Environment variables are processed in [`lib/config/environment.js`](https://github.com/hedgedoc/hedgedoc/tree/master/lib/config/environment.js) - so this is the first place to look if anything is missing not obvious from this document. The default values are defined in [`lib/config/default.js`](https://github.com/hedgedoc/hedgedoc/tree/master/lib/config/default.js), in case you wonder if you even need to override it.
- The config file is processed in [`lib/config/index.js`](../lib/config/index.js) - so this is the first place to look if anything is missing not obvious from this document. The default values are defined in [`lib/config/default.js`](../lib/config/default.js), in case you wonder if you even need to override it. To get started, it is a good idea to take the `config.json.example` and copy it
- The config file is processed in [`lib/config/index.js`](https://github.com/hedgedoc/hedgedoc/tree/master/lib/config/index.js) - so this is the first place to look if anything is missing not obvious from this document. The default values are defined in [`lib/config/default.js`](https://github.com/hedgedoc/hedgedoc/tree/master/lib/config/default.js), in case you wonder if you even need to override it. To get started, it is a good idea to take the `config.json.example` and copy it
to `config.json` before filling in your own details.
**Note:** *Due to the rename process we renamed all `HMD_`-prefix variables to be `CMD_`-prefixed. The old ones continue to work.*
......
......@@ -11,14 +11,14 @@ You have to replace *\<NOTE\>* with either the alias or id of a note you want to
| ---------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/new` | `GET` | **Creates a new note.**<br>A random id will be assigned and the content will equal to the template (blank by default). After note creation a redirect is issued to the created note. |
| `/new` | `POST` | **Imports some markdown data into a new note.**<br>A random id will be assigned and the content will equal to the body of the received HTTP-request. The `Content-Type: text/markdown` header should be set on this request. |
| `/new/<ALIAS>` | `POST` | **Imports some markdown data into a new note with a given alias.**<br>This endpoint equals to the above one except that the alias from the url will be assigned to the note if [FreeURL-mode](../configuration-env-vars.md#users-and-privileges) is enabled. |
| `/new/<ALIAS>` | `POST` | **Imports some markdown data into a new note with a given alias.**<br>This endpoint equals to the above one except that the alias from the url will be assigned to the note if [FreeURL-mode](../configuration.md#users-and-privileges) is enabled. |
| `/<NOTE>/download` or `/s/<SHORT-ID>/download` | `GET` | **Returns the raw markdown content of a note.** |
| `/<NOTE>/publish` | `GET` | **Redirects to the published version of the note.** |
| `/<NOTE>/slide` | `GET` | **Redirects to the slide-presentation of the note.**<br>This is only useful on notes which are designed to be slides. |
| `/<NOTE>/info` | `GET` | **Returns metadata about the note.**<br>This includes the title and description of the note as well as the creation date and viewcount. The data is returned as a JSON object. |
| `/<NOTE>/revision` | `GET` | **Returns a list of the available note revisions.**<br>The list is returned as a JSON object with an array of revision-id and length associations. The revision-id equals to the timestamp when the revision was saved. |
| `/<NOTE>/revision/<REVISION-ID>` | `GET` | **Returns the revision of the note with some metadata.**<br>The revision is returned as a JSON object with the content of the note and the authorship. |
| `/<NOTE>/gist` | `GET` | **Creates a new GitHub Gist with the note's content.**<br>If [GitHub integration](../configuration-env-vars.md#github-login) is configured, the user will be redirected to GitHub and a new Gist with the content of the note will be created. |
| `/<NOTE>/gist` | `GET` | **Creates a new GitHub Gist with the note's content.**<br>If [GitHub integration](../configuration.md#github-login) is configured, the user will be redirected to GitHub and a new Gist with the content of the note will be created. |
## User / History
These endpoints return information about the current logged-in user and it's note history. If no user is logged-in, the most of this requests will fail with either a HTTP 403 or a JSON object containing `{"status":"forbidden"}`.
......
# Documentation
Our documentation is build with [mkdocs](https://www.mkdocs.org).
## Writing
All documentation files are found in the `docs/content` directory of the [hedgedoc/hedgedoc repo](https://github.com/hedgedoc/hedgedoc). These files are just normal markdown files with nothing special about them.
The configuration for mkdocs lies in the `docs` folder in a file called `mkdocs.yml`. With that file the theme and menu - amoung others - can be configured.
**Please note:** Any new files need to be linked to by other files or put in the navigation or the files will be very hard to find on the documentation website.
## Building
To build the documentation locally you need to perform the following steps:
0. Make sure you have python3 installed.
1. Go into the `docs` folder.
2. Install all the dependencies (E.g. with a [venv](https://docs.python.org/3/library/venv.html)) with `pip install -r requirements.txt`
3. Start the mkdocs dev server (`mkdocs serve`) or build the documentation (`mkdocs build`).
## Deployment
The documentation is deployed with [Messor Structor](https://github.com/traefik/structor).
The necessary Dockerfile and version menu template and also the github action to build the whole documentation can be found in the [docs.hedgedoc.org repo](https://github.com/hedgedoc/docs.hedgedoc.org). This repo is also used to deploy the actuall website to github.io.
Messor Structor builds and deploys the documentation by finding all branches that follow the pattern `v*`. For each branch the docs are generated separately by first installing the dependencies from `requirements.txt` and then running mkdocs. Afterwards the menu go template is used to include a version switcher in the theme.
# Developer Notes
# Getting started
## Preparing for running the code
......@@ -11,8 +11,8 @@
and create configs. The setup script is written in Bash, you would need bash
as a prerequisite.
3. Setup the [config file](../configuration-config-file.md) or set up
[environment variables](../configuration-env-vars.md).
3. Setup the [config file](../configuration.md) or set up
[environment variables](../configuration.md).
## Running the Code
......
......@@ -3,7 +3,7 @@ openapi: 3.0.1
info:
title: HedgeDoc
description: HedgeDoc is an open source collaborative note editor. Several tasks of HedgeDoc can be automated through this API.
version: 1.7.1
version: 1.7.2
contact:
name: HedgeDoc on GitHub
url: https://github.com/hedgedoc/hedgedoc
......
......@@ -17,7 +17,7 @@
6. Add the Client ID and Client Secret to your config.json file or pass them as environment variables
- `config.json`:
```js
```json
{
"production": {
"github": {
......@@ -29,7 +29,7 @@
```
- environment variables:
```sh
```shell
CMD_GITHUB_CLIENTID=3747d30eaccXXXXXXXXX
CMD_GITHUB_CLIENTSECRET=2a8e682948eee0c580XXXXXXXXXXXXXXXXXXXXXX
````
```
# GitLab (self-hosted)
*Note:* This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind :smile: thanks!
**Note:** *This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind 😃 thanks!*
1. Sign in to your GitLab
2. Navigate to the application management page at `https://your.gitlab.domain/admin/applications` (admin permissions required)
3. Click **New application** to create a new application and fill out the registration form:
![New GitLab application](../../images/auth/gitlab-new-application.png)
![New GitLab application](../../images/auth/gitlab-new-application.png)
4. Click **Submit**
5. In the list of applications select **HackMD**. Leave that site open to copy the application ID and secret in the next step.
5. In the list of applications select **HackMD**. Leave that site open to copy the application ID and secret in the next
step.
![Application: HackMD](../../images/auth/gitlab-application-details.png)
![Application: HackMD](../../images/auth/gitlab-application-details.png)
6. In the `docker-compose.yml` add the following environment variables to `app:` `environment:`
```Dockerfile
- CMD_DOMAIN=your.hedgedoc.domain
- CMD_URL_ADDPORT=true
- CMD_PROTOCOL_USESSL=true
- CMD_GITLAB_BASEURL=https://your.gitlab.domain
- CMD_GITLAB_CLIENTID=23462a34example99XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
- CMD_GITLAB_CLIENTSECRET=5532e9dexamplXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```
```yaml
- CMD_DOMAIN=your.hedgedoc.domain
- CMD_URL_ADDPORT=true
- CMD_PROTOCOL_USESSL=true
- CMD_GITLAB_BASEURL=https://your.gitlab.domain
- CMD_GITLAB_CLIENTID=23462a34example99XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
- CMD_GITLAB_CLIENTSECRET=5532e9dexamplXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```
7. Run `docker-compose up -d` to apply your settings.
8. Sign in to your HedgeDoc using your GitLab ID:
![Sign in via GitLab](../../images/auth/gitlab-sign-in.png)
![Sign in via GitLab](../../images/auth/gitlab-sign-in.png)
......@@ -30,7 +30,7 @@ You may note that a separate realm is specified throughout this tutorial. It is
5. In the `docker-compose.yml` add the following environment variables to `app:` `environment:`
```Dockerfile
```yaml
CMD_OAUTH2_USER_PROFILE_URL=https://keycloak.example.com/auth/realms/your-realm/protocol/openid-connect/userinfo
CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR=preferred_username
CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR=name
......
......@@ -2,19 +2,22 @@
To setup your HedgeDoc instance with Active Directory you need the following configs:
```env
```shell
CMD_LDAP_URL=ldap://internal.example.com
CMD_LDAP_BINDDN=cn=binduser,cn=Users,dc=internal,dc=example,dc=com
CMD_LDAP_BINDCREDENTIALS=<super secret password>
CMD_LDAP_BINDCREDENTIALS="<super secret password>"
CMD_LDAP_SEARCHBASE=dc=internal,dc=example,dc=com
CMD_LDAP_SEARCHFILTER=(&(objectcategory=person)(objectclass=user)(|(sAMAccountName={{username}})(mail={{username}})))
CMD_LDAP_USERIDFIELD=sAMAccountName
CMD_LDAP_PROVIDERNAME=Example Inc AD
CMD_LDAP_PROVIDERNAME="Example Inc AD"
```
`CMD_LDAP_BINDDN` is either the `distinguishedName` or the `userPrincipalName`. *This can cause "username/password is invalid" when either this value or the password from `CMD_LDAP_BINDCREDENTIALS` are incorrect.*
`CMD_LDAP_BINDDN` is either the `distinguishedName` or the `userPrincipalName`.
*This can cause "username/password is invalid" when either this value or the password from `CMD_LDAP_BINDCREDENTIALS`
are incorrect.*
`CMD_LDAP_SEARCHFILTER` matches on all users and uses either the email address or the `sAMAccountName` (usually the login name you also use to login to Windows).
`CMD_LDAP_SEARCHFILTER` matches on all users and uses either the email address or the `sAMAccountName` (usually the
login name you also use to login to Windows).
*Only using `sAMAccountName` looks like this:* `(&(objectcategory=person)(objectclass=user)(sAMAccountName={{username}}))`
......
......@@ -24,7 +24,7 @@ This guide uses the generic OAuth2 module for compatibility with Mattermost vers
7. Add the Client ID and Client Secret to your config.json file or pass them as environment variables
- `config.json`:
```javascript
```json
{
"production": {
"oauth2": {
......
# Authentication guide - Nextcloud (self-hosted)
*This has been constructed using the [Nextcloud OAuth2 Documentation](https://docs.nextcloud.com/server/14/admin_manual/configuration_server/oauth2.html?highlight=oauth2) combined with [this issue comment on the nextcloud bugtracker](https://github.com/nextcloud/server/issues/5694#issuecomment-314761326).*
*This has been constructed using
the [Nextcloud OAuth2 Documentation](https://docs.nextcloud.com/server/14/admin_manual/configuration_server/oauth2.html?highlight=oauth2)
combined
with [this issue comment on the nextcloud bugtracker](https://github.com/nextcloud/server/issues/5694#issuecomment-314761326)
.*
This guide uses the generic OAuth2 module for compatibility with Nextcloud 13 and above (this guide has been tested successfully with Nextcloud 14).
This guide uses the generic OAuth2 module for compatibility with Nextcloud 13 and above (this guide has been tested
successfully with Nextcloud 14 and Nextcloud 20).
1. Sign-in with an administrator account to your Nextcloud server
......@@ -18,35 +23,39 @@ This guide uses the generic OAuth2 module for compatibility with Nextcloud 13 an
4. You'll now see a line containing a *client identifier* and a *Secret*.
![Successfully added OAuth2-client](../../images/auth/nextcloud-oauth2-3-clientid-secret.png)
5. That's it for Nextcloud, the rest is configured in your HedgeDoc `config.json` or via the `CMD_` environment variables!
5. That's it for Nextcloud, the rest is configured in your HedgeDoc `config.json` or via the `CMD_` environment
variables!
6. Add the Client ID and Client Secret to your `config.json` file or pass them as environment variables. Make sure you also replace `<your-nextcloud-domain>` with the right domain name.
6. Add the Client ID and Client Secret to your `config.json` file or pass them as environment variables. Make sure you
also replace `<your-nextcloud-domain>` with the right domain name.
- `config.json`:
```javascript
```json
{
"production": {
"oauth2": {
"clientID": "ii4p1u3jz7dXXXXXXXXXXXXXXX",
"clientSecret": "mqzzx6fydbXXXXXXXXXXXXXXXX",
"authorizationURL": "https://<your-nextcloud-domain>/apps/oauth2/authorize",
"tokenURL": "https://<your-nextcloud-domain>/apps/oauth2/api/v1/token",
"userProfileURL": "https://<your-nextcloud-domain>/ocs/v2.php/cloud/user?format=json",
"userProfileUsernameAttr": "ocs.data.id",
"userProfileDisplayNameAttr": "ocs.data.display-name",
"userProfileEmailAttr": "ocs.data.email"
"clientID": "ii4p1u3jz7dXXXXXXXXXXXXXXX",
"clientSecret": "mqzzx6fydbXXXXXXXXXXXXXXXX",
"authorizationURL": "https://<your-nextcloud-domain>/apps/oauth2/authorize",
"tokenURL": "https://<your-nextcloud-domain>/apps/oauth2/api/v1/token",
"userProfileURL": "https://<your-nextcloud-domain>/ocs/v2.php/cloud/user?format=json",
"userProfileUsernameAttr": "ocs.data.id",
"userProfileDisplayNameAttr": "ocs.data.display-name",
"userProfileEmailAttr": "ocs.data.email"
}
}
}
```
- environment variables:
```sh
CMD_OAUTH2_CLIENT_ID=ii4p1u3jz7dXXXXXXXXXXXXXXX
CMD_OAUTH2_CLIENT_SECRET=mqzzx6fydbXXXXXXXXXXXXXXXX
CMD_OAUTH2_AUTHORIZATION_URL=https://<your-nextcloud-domain>/apps/oauth2/authorize
CMD_OAUTH2_TOKEN_URL=https://<your-nextcloud-domain>/apps/oauth2/api/v1/token
CMD_OAUTH2_USER_PROFILE_URL=https://<your-nextcloud-domain>/ocs/v2.php/cloud/user?format=json
CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR=ocs.data.id
CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR=ocs.data.display-name
CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR=ocs.data.email
```
- environment variables:
```sh
CMD_OAUTH2_CLIENT_ID=ii4p1u3jz7dXXXXXXXXXXXXXXX
CMD_OAUTH2_CLIENT_SECRET=mqzzx6fydbXXXXXXXXXXXXXXXX
CMD_OAUTH2_AUTHORIZATION_URL=https://<your-nextcloud-domain>/apps/oauth2/authorize
CMD_OAUTH2_TOKEN_URL=https://<your-nextcloud-domain>/apps/oauth2/api/v1/token
CMD_OAUTH2_USER_PROFILE_URL=https://<your-nextcloud-domain>/ocs/v2.php/cloud/user?format=json
CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR=ocs.data.id
CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR=ocs.data.display-name
CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR=ocs.data.email
```
......@@ -107,7 +107,7 @@ The configured mappers should look like this:
}
```
It you configure HedgeDoc with enviroment variables, these are the ones you have to set:
```bash
```shell
CMD_SAML_ATTRIBUTE_USERNAME=username
CMD_SAML_ATTRIBUTE_EMAIL=email
```
# Authentication guide - SAML (OneLogin)
**Note:** *This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind :smile: thanks!*
**Note:** *This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind 😃 thanks!*
1. Sign-in or sign-up for an OneLogin account. (available free trial for 2 weeks)
......@@ -34,7 +34,7 @@
8. In your HedgeDoc server, create IdP certificate file from (A)
9. Add the IdP URL (B) and the Idp certificate file path to your config.json file or pass them as environment variables.
- `config.json`:
```javascript
```json
{
"production": {
"saml": {
......@@ -46,7 +46,7 @@
```
- environment variables
```sh
```shell
CMD_SAML_IDPSSOURL=https://*******.onelogin.com/trust/saml2/http-post/sso/******
CMD_SAML_IDPCERT=/path/to/idp_cert.pem
```
......
# Authentication guide - SAML
*Note:* This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind :smile: thanks!
*Note:* This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind 😃 thanks!
The basic procedure is the same as the case of OneLogin which is mentioned in [OneLogin-Guide](./saml-onelogin.md). If you want to match your IdP, you can use more configurations as below.
The basic procedure is the same as the case of OneLogin which is mentioned in [OneLogin-Guide](./saml-onelogin.md). If
you want to match your IdP, you can use more configurations as below.
- If your IdP accepts metadata XML of the service provider to ease configuration, use this url to download metadata XML.
- {{your-serverurl}}/auth/saml/metadata
- *Note:* If not accessible from IdP, download to local once and upload to IdP.
- If your IdP accepts metadata XML of the service provider to ease configuration, use this url to download metadata XML:
`{{your-serverurl}}/auth/saml/metadata`
*Note:* If not accessible from IdP, download to local once and upload to IdP.
- Change the value of `issuer`, `identifierFormat` to match your IdP.
- `issuer`: A unique id to identify the application to the IdP, which is the base URL of your HedgeDoc as default
- `identifierFormat`: A format of unique id to identify the user of IdP, which is the format based on email address as default. It is recommend that you use as below.
- `identifierFormat`: A format of unique id to identify the user of IdP, which is the format based on email address as
default. It is recommend that you use as below.
- urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress (default)
- urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
......@@ -29,23 +31,24 @@ The basic procedure is the same as the case of OneLogin which is mentioned in [O
```
- environment variables
```env
```shell
CMD_SAML_ISSUER=myhedgedoc
CMD_SAML_IDENTIFIERFORMAT=urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
```
- Change mapping of attribute names to customize the displaying user name and email address to match your IdP.
- `attribute`: A dictionary to map attribute names
- `attribute.id`: A primary key of user table for your HedgeDoc
- `attribute.username`: Attribute name of displaying user name on HedgeDoc
- `attribute.email`: Attribute name of email address, which will be also used for Gravatar
- *Note:* Default value of all attributes is NameID of SAML response, which is email address if `identifierFormat` is default.
- *Note:* Default value of all attributes is NameID of SAML response, which is email address if `identifierFormat`
is default.
- `config.json`:
```javascript
```json
{
"production": {
"saml": {
......@@ -61,22 +64,25 @@ The basic procedure is the same as the case of OneLogin which is mentioned in [O
```
- environment variables
```sh
```shell
CMD_SAML_ATTRIBUTE_ID=sAMAccountName
CMD_SAML_ATTRIBUTE_USERNAME=nickName
CMD_SAML_ATTRIBUTE_EMAIL=mail
```
- If you want to control permission by group membership, add group attribute name and required group (allowed) or external group (not allowed).
- If you want to control permission by group membership, add group attribute name and required group (allowed) or
external group (not allowed).
- `groupAttribute`: An attribute name of group membership
- `requiredGroups`: Group names array for allowed access to HedgeDoc. Use vertical bar to separate for environment variables.
- `requiredGroups`: Group names array for allowed access to HedgeDoc. Use vertical bar to separate for environment
variables.
- `externalGroups`: Group names array for not allowed access to HedgeDoc. Use vertical bar to separate for environment variables.
- `externalGroups`: Group names array for not allowed access to HedgeDoc. Use vertical bar to separate for environment
variables.
- *Note:* Evaluates `externalGroups` first
- `config.json`:
```javascript
```json
{
"production": {
"saml": {
......@@ -90,7 +96,7 @@ The basic procedure is the same as the case of OneLogin which is mentioned in [O
```
- environment variables
```sh
```shell
CMD_SAML_GROUPATTRIBUTE=memberOf
CMD_SAML_REQUIREDGROUPS=hedgedoc-users|board-members
CMD_SAML_EXTERNALGROUPS=temporary-staff
......
# Authentication guide - Twitter
*Note:* This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind :smile: thanks!
**Note:** *This guide was written before the renaming. Just replace `HackMD` with `HedgeDoc` in your mind 😃 thanks!*
1. Sign-in or sign-up for a Twitter account
......@@ -24,7 +24,7 @@
7. Add your Consumer Key and Consumer Secret to your `config.json` file or pass them as environment variables:
- `config.json`:
```javascript
```json
{
"production": {
"twitter": {
......@@ -36,7 +36,7 @@
```
- environment variables:
```sh
```shell
CMD_TWITTER_CONSUMERKEY=esTCJFXXXXXXXXXXXXXXXXXXX
CMD_TWITTER_CONSUMERSECRET=zpCs4tU86pRVXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment