summaryrefslogtreecommitdiff
path: root/docs/guides
diff options
context:
space:
mode:
Diffstat (limited to 'docs/guides')
-rw-r--r--docs/guides/auth/gitlab-self-hosted.md6
-rw-r--r--docs/guides/auth/ldap-AD.md42
-rw-r--r--docs/guides/auth/nextcloud.md52
-rw-r--r--docs/guides/images/auth/nextcloud-oauth2-1-settings.pngbin0 -> 47047 bytes
-rw-r--r--docs/guides/images/auth/nextcloud-oauth2-2-client-add.pngbin0 -> 11684 bytes
-rw-r--r--docs/guides/images/auth/nextcloud-oauth2-3-clientid-secret.pngbin0 -> 13428 bytes
6 files changed, 97 insertions, 3 deletions
diff --git a/docs/guides/auth/gitlab-self-hosted.md b/docs/guides/auth/gitlab-self-hosted.md
index 89bc996f..60f62616 100644
--- a/docs/guides/auth/gitlab-self-hosted.md
+++ b/docs/guides/auth/gitlab-self-hosted.md
@@ -7,12 +7,12 @@
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.
-![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:`
@@ -29,4 +29,4 @@
7. Run `docker-compose up -d` to apply your settings.
8. Sign in to your HackMD using your GitLab ID:
-![Sign in via GitLab](images/auth/gitlab-sign-in.png)
+![Sign in via GitLab](../images/auth/gitlab-sign-in.png)
diff --git a/docs/guides/auth/ldap-AD.md b/docs/guides/auth/ldap-AD.md
new file mode 100644
index 00000000..77521db3
--- /dev/null
+++ b/docs/guides/auth/ldap-AD.md
@@ -0,0 +1,42 @@
+AD LDAP auth
+===
+
+
+To setup your CodiMD instance with Active Directory you need the following configs:
+
+```
+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_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_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).
+
+*Only using `sAMAccountName` looks like this:* `(&(objectcategory=person)(objectclass=user)(sAMAccountName={{username}}))`
+
+`CMD_LDAP_USERIDFIELD` says we want to use `sAMAccountName` as unique identifier for the account itself.
+
+`CMD_LDAP_PROVIDERNAME` just the name written above the username and password field on the login page.
+
+
+Same in json:
+
+```json
+"ldap": {
+ "url": "ldap://internal.example.com",
+ "bindDn": "cn=binduser,cn=Users,dc=internal,dc=example,dc=com",
+ "bindCredentials": "<super secret password>",
+ "searchBase": "dc=internal,dc=example,dc=com",
+ "searchFilter": "(&(objectcategory=person)(objectclass=user)(|(sAMAccountName={{username}})(mail={{username}})))",
+ "useridField": "sAMAccountName",
+},
+```
+
+More details and example: https://www.npmjs.com/package/passport-ldapauth
diff --git a/docs/guides/auth/nextcloud.md b/docs/guides/auth/nextcloud.md
new file mode 100644
index 00000000..108772dd
--- /dev/null
+++ b/docs/guides/auth/nextcloud.md
@@ -0,0 +1,52 @@
+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 guide uses the generic OAuth2 module for compatibility with Nextcloud 13 and above (this guide has been tested successfully with Nextcloud 14).
+
+1. Sign-in with an administrator account to your Nextcloud server
+
+2. Navigate to the OAuth integration settings: Profile Icon (top right) --> Settings
+ Then choose Security Settings from the *Administration* part of the list - Don't confuse this with Personal Security Settings, where you would change your personal password!
+ At the top there's OAuth 2.0-Clients.
+ ![Where to find OAuth2 in Nextcloud](../images/auth/nextcloud-oauth2-1-settings.png)
+
+3. Add your CodiMD instance by giving it a *name* (perhaps CodiMD, but could be anything) and a *Redirection-URI*. The Redirection-URI will be `\<your-codimd-url\>/auth/oauth2/callback`. Click <kbd>Add</kbd>.
+ ![Adding a client to Nextcloud](../images/auth/nextcloud-oauth2-2-client-add.png)
+
+
+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 CodiMD `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.
+ * `config.json`:
+ ```javascript
+ {
+ "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"
+ }
+ }
+ }
+ ```
+ * 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
+ ```
diff --git a/docs/guides/images/auth/nextcloud-oauth2-1-settings.png b/docs/guides/images/auth/nextcloud-oauth2-1-settings.png
new file mode 100644
index 00000000..82652a54
--- /dev/null
+++ b/docs/guides/images/auth/nextcloud-oauth2-1-settings.png
Binary files differ
diff --git a/docs/guides/images/auth/nextcloud-oauth2-2-client-add.png b/docs/guides/images/auth/nextcloud-oauth2-2-client-add.png
new file mode 100644
index 00000000..7909fa62
--- /dev/null
+++ b/docs/guides/images/auth/nextcloud-oauth2-2-client-add.png
Binary files differ
diff --git a/docs/guides/images/auth/nextcloud-oauth2-3-clientid-secret.png b/docs/guides/images/auth/nextcloud-oauth2-3-clientid-secret.png
new file mode 100644
index 00000000..b05513d1
--- /dev/null
+++ b/docs/guides/images/auth/nextcloud-oauth2-3-clientid-secret.png
Binary files differ