diff options
Diffstat (limited to 'docs/guides')
| -rw-r--r-- | docs/guides/auth.md | 241 | ||||
| -rw-r--r-- | docs/guides/auth/github.md | 36 | ||||
| -rw-r--r-- | docs/guides/auth/gitlab-self-hosted.md | 30 | ||||
| -rw-r--r-- | docs/guides/auth/saml-onelogin.md | 52 | ||||
| -rw-r--r-- | docs/guides/auth/saml.md | 83 | ||||
| -rw-r--r-- | docs/guides/auth/twitter.md | 42 |
6 files changed, 243 insertions, 241 deletions
diff --git a/docs/guides/auth.md b/docs/guides/auth.md deleted file mode 100644 index e4261724..00000000 --- a/docs/guides/auth.md +++ /dev/null @@ -1,241 +0,0 @@ -# Guide - Authentication - -### Twitter -1. Sign-in or sign-up for a Twitter account -2. Go to the Twitter Application management page [here](https://apps.twitter.com/) -3. Click on the **Create New App** button to create a new Twitter app: - - - -4. Fill out the create application form, check the developer agreement box, and click **Create Your Twitter Application** - - - -*Note: you may have to register your phone number with Twitter to create a Twitter application* - -To do this Click your profile icon --> Settings and privacy --> Mobile --> Select Country/region --> Enter phone number --> Click Continue - -5. After you receive confirmation that the Twitter application was created, click **Keys and Access Tokens** - - - -6. Obtain your Twitter Consumer Key and Consumer Secret - - - -7. Add your Consumer Key and Consumer Secret to your config.json file or pass them as environment variables: - * config.json: - ````javascript - { - "production": { - "twitter": { - "consumerKey": "esTCJFXXXXXXXXXXXXXXXXXXX", - "consumerSecret": "zpCs4tU86pRVXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" - } - } - } - ```` - * environment variables: - ```` - HMD_TWITTER_CONSUMERKEY=esTCJFXXXXXXXXXXXXXXXXXXX - HMD_TWITTER_CONSUMERSECRET=zpCs4tU86pRVXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX - ```` - -### GitHub -1. Sign-in or sign-up for a GitHub account -2. Navigate to developer settings in your GitHub account [here](https://github.com/settings/developers) and select the "OAuth Apps" tab -3. Click on the **New OAuth App** button, to create a new OAuth App: - - - -4. Fill out the new OAuth application registration form, and click **Register Application** - - - -*Note: The callback URL is <your-hackmd-url>/auth/github/callback* - -5. After successfully registering the application, you'll receive the Client ID and Client Secret for the application - - - -6. Add the Client ID and Client Secret to your config.json file or pass them as environment variables - * config.json: - ````javascript - { - "production": { - "github": { - "clientID": "3747d30eaccXXXXXXXXX", - "clientSecret": "2a8e682948eee0c580XXXXXXXXXXXXXXXXXXXXXX" - } - } - } - ```` - * environment variables: - ```` - HMD_GITHUB_CLIENTID=3747d30eaccXXXXXXXXX - HMD_GITHUB_CLIENTSECRET=2a8e682948eee0c580XXXXXXXXXXXXXXXXXXXXXX - ```` - -### SAML (OneLogin) -1. Sign-in or sign-up for an OneLogin account. (available free trial for 2 weeks) -2. Go to the administration page. -3. Select the **APPS** menu and click on the **Add Apps**. - - - -4. Find "SAML Test Connector (SP)" for template of settings and select it. - - - -5. Edit display name and icons for OneLogin dashboard as you want, and click **SAVE**. - - - -6. After that other tabs will appear, click the **Configuration**, and fill out the below items, and click **SAVE**. - * RelayState: The base URL of your hackmd, which is issuer. (last slash is not needed) - * ACS (Consumer) URL Validator: The callback URL of your hackmd. (serverurl + /auth/saml/callback) - * ACS (Consumer) URL: same as above. - * Login URL: login URL(SAML requester) of your hackmd. (serverurl + /auth/saml) - - - -7. The registration is completed. Next, click **SSO** and copy or download the items below. - * X.509 Certificate: Click **View Details** and **DOWNLOAD** or copy the content of certificate ....(A) - * SAML 2.0 Endpoint (HTTP): Copy the URL ....(B) - - - -8. In your hackmd 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 - { - "production": { - "saml": { - "idpSsoUrl": "https://*******.onelogin.com/trust/saml2/http-post/sso/******", - "idpCert": "/path/to/idp_cert.pem" - } - } - } - ```` - * environment variables - ```` - HMD_SAML_IDPSSOURL=https://*******.onelogin.com/trust/saml2/http-post/sso/****** - HMD_SAML_IDPCERT=/path/to/idp_cert.pem - ```` -10. Try sign-in with SAML from your hackmd sign-in button or OneLogin dashboard (like the screenshot below). - - - -### SAML (Other cases) -The basic procedure is the same as the case of OneLogin which is mentioned above. 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 configuraion, use this url to download metadata XML. - * {{your-serverurl}}/auth/saml/metadata - * _Note: If not accessable 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 HackMD 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. - * urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress (default) - * urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified - * config.json: - ````javascript - { - "production": { - "saml": { - /* omitted */ - "issuer": "myhackmd" - "identifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" - } - } - } - ```` - * environment variables - ```` - HMD_SAML_ISSUER=myhackmd - HMD_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 HackMD - * `attribute.username`: Attribute name of displaying user name on HackMD - * `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._ - * config.json: - ````javascript - { - "production": { - "saml": { - /* omitted */ - "attribute": { - "id": "sAMAccountName", - "username": "displayName", - "email": "mail" - } - } - } - } - ```` - * environment variables - ```` - HMD_SAML_ATTRIBUTE_ID=sAMAccountName - HMD_SAML_ATTRIBUTE_USERNAME=nickName - HMD_SAML_ATTRIBUTE_EMAIL=mail - ```` - -* If you want to controll 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 HackMD. Use vertical bar to separate for environment variables. - * `externalGroups`: Group names array for not allowed access to HackMD. Use vertical bar to separate for environment variables. - * _Note: Evaluates `externalGroups` first_ - * config.json: - ````javascript - { - "production": { - "saml": { - /* omitted */ - "groupAttribute": "memberOf", - "requiredGroups": [ "hackmd-users", "board-members" ], - "externalGroups": [ "temporary-staff" ] - } - } - } - ```` - * environment variables - ```` - HMD_SAML_GROUPATTRIBUTE=memberOf - HMD_SAML_REQUIREDGROUPS=hackmd-users|board-members - HMD_SAML_EXTERNALGROUPS=temporary-staff - ```` - - -### GitLab (self-hosted) - -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: - - - -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. - - - - -6. In the `docker-compose.yml` add the following environment variables to `app:` `environment:` - -``` -- HMD_DOMAIN=your.hackmd.domain -- HMD_URL_ADDPORT=443 -- HMD_PROTOCOL_USESSL=true -- HMD_GITLAB_BASEURL=https://your.gitlab.domain -- HMD_GITLAB_CLIENTID=23462a34example99fid0943c3fde97310fb7db47fab1112 -- HMD_GITLAB_CLIENTSECRET=5532e9dexample70432secret0c37dd20ce077e6073ea9f1d6 -``` - -7. Run `docker-compose up -d` to apply your settings. -8. Sign in to your HackMD using your GitLab ID: - - diff --git a/docs/guides/auth/github.md b/docs/guides/auth/github.md new file mode 100644 index 00000000..62910cb2 --- /dev/null +++ b/docs/guides/auth/github.md @@ -0,0 +1,36 @@ +Authentication guide - GitHub +=== + +1. Sign-in or sign-up for a GitHub account +2. Navigate to developer settings in your GitHub account [here](https://github.com/settings/developers) and select the "OAuth Apps" tab +3. Click on the **New OAuth App** button, to create a new OAuth App: + + + +4. Fill out the new OAuth application registration form, and click **Register Application** + + + +*Note: The callback URL is <your-hackmd-url>/auth/github/callback* + +5. After successfully registering the application, you'll receive the Client ID and Client Secret for the application + + + +6. Add the Client ID and Client Secret to your config.json file or pass them as environment variables + * config.json: + ````javascript + { + "production": { + "github": { + "clientID": "3747d30eaccXXXXXXXXX", + "clientSecret": "2a8e682948eee0c580XXXXXXXXXXXXXXXXXXXXXX" + } + } + } + ```` + * environment variables: + ```` + HMD_GITHUB_CLIENTID=3747d30eaccXXXXXXXXX + HMD_GITHUB_CLIENTSECRET=2a8e682948eee0c580XXXXXXXXXXXXXXXXXXXXXX + ```` diff --git a/docs/guides/auth/gitlab-self-hosted.md b/docs/guides/auth/gitlab-self-hosted.md new file mode 100644 index 00000000..361ee958 --- /dev/null +++ b/docs/guides/auth/gitlab-self-hosted.md @@ -0,0 +1,30 @@ +# GitLab (self-hosted) +=== + +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: + + + +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. + + + + +6. In the `docker-compose.yml` add the following environment variables to `app:` `environment:` + +``` +- HMD_DOMAIN=your.hackmd.domain +- HMD_URL_ADDPORT=443 +- HMD_PROTOCOL_USESSL=true +- HMD_GITLAB_BASEURL=https://your.gitlab.domain +- HMD_GITLAB_CLIENTID=23462a34example99XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +- HMD_GITLAB_CLIENTSECRET=5532e9dexamplXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +``` + +7. Run `docker-compose up -d` to apply your settings. +8. Sign in to your HackMD using your GitLab ID: + + diff --git a/docs/guides/auth/saml-onelogin.md b/docs/guides/auth/saml-onelogin.md new file mode 100644 index 00000000..245876c5 --- /dev/null +++ b/docs/guides/auth/saml-onelogin.md @@ -0,0 +1,52 @@ +Authentication guide - SAML (OneLogin) +=== + +1. Sign-in or sign-up for an OneLogin account. (available free trial for 2 weeks) +2. Go to the administration page. +3. Select the **APPS** menu and click on the **Add Apps**. + + + +4. Find "SAML Test Connector (SP)" for template of settings and select it. + + + +5. Edit display name and icons for OneLogin dashboard as you want, and click **SAVE**. + + + +6. After that other tabs will appear, click the **Configuration**, and fill out the below items, and click **SAVE**. + * RelayState: The base URL of your hackmd, which is issuer. (last slash is not needed) + * ACS (Consumer) URL Validator: The callback URL of your hackmd. (serverurl + /auth/saml/callback) + * ACS (Consumer) URL: same as above. + * Login URL: login URL(SAML requester) of your hackmd. (serverurl + /auth/saml) + + + +7. The registration is completed. Next, click **SSO** and copy or download the items below. + * X.509 Certificate: Click **View Details** and **DOWNLOAD** or copy the content of certificate ....(A) + * SAML 2.0 Endpoint (HTTP): Copy the URL ....(B) + + + +8. In your hackmd 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 + { + "production": { + "saml": { + "idpSsoUrl": "https://*******.onelogin.com/trust/saml2/http-post/sso/******", + "idpCert": "/path/to/idp_cert.pem" + } + } + } + ```` + * environment variables + ```` + HMD_SAML_IDPSSOURL=https://*******.onelogin.com/trust/saml2/http-post/sso/****** + HMD_SAML_IDPCERT=/path/to/idp_cert.pem + ```` +10. Try sign-in with SAML from your hackmd sign-in button or OneLogin dashboard (like the screenshot below). + + diff --git a/docs/guides/auth/saml.md b/docs/guides/auth/saml.md new file mode 100644 index 00000000..9a516675 --- /dev/null +++ b/docs/guides/auth/saml.md @@ -0,0 +1,83 @@ +Authentication guide - SAML +=== + +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 configuraion, use this url to download metadata XML. + * {{your-serverurl}}/auth/saml/metadata + * _Note: If not accessable 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 HackMD 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. + * urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress (default) + * urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified + * config.json: + ````javascript + { + "production": { + "saml": { + /* omitted */ + "issuer": "myhackmd" + "identifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" + } + } + } + ```` + * environment variables + ```` + HMD_SAML_ISSUER=myhackmd + HMD_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 HackMD + * `attribute.username`: Attribute name of displaying user name on HackMD + * `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._ + * config.json: + ````javascript + { + "production": { + "saml": { + /* omitted */ + "attribute": { + "id": "sAMAccountName", + "username": "displayName", + "email": "mail" + } + } + } + } + ```` + * environment variables + ```` + HMD_SAML_ATTRIBUTE_ID=sAMAccountName + HMD_SAML_ATTRIBUTE_USERNAME=nickName + HMD_SAML_ATTRIBUTE_EMAIL=mail + ```` + +* If you want to controll 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 HackMD. Use vertical bar to separate for environment variables. + * `externalGroups`: Group names array for not allowed access to HackMD. Use vertical bar to separate for environment variables. + * _Note: Evaluates `externalGroups` first_ + * config.json: + ````javascript + { + "production": { + "saml": { + /* omitted */ + "groupAttribute": "memberOf", + "requiredGroups": [ "hackmd-users", "board-members" ], + "externalGroups": [ "temporary-staff" ] + } + } + } + ```` + * environment variables + ```` + HMD_SAML_GROUPATTRIBUTE=memberOf + HMD_SAML_REQUIREDGROUPS=hackmd-users|board-members + HMD_SAML_EXTERNALGROUPS=temporary-staff + ```` diff --git a/docs/guides/auth/twitter.md b/docs/guides/auth/twitter.md new file mode 100644 index 00000000..02309ca5 --- /dev/null +++ b/docs/guides/auth/twitter.md @@ -0,0 +1,42 @@ +Authentication guide - Twitter +=== + +1. Sign-in or sign-up for a Twitter account +2. Go to the Twitter Application management page [here](https://apps.twitter.com/) +3. Click on the **Create New App** button to create a new Twitter app: + + + +4. Fill out the create application form, check the developer agreement box, and click **Create Your Twitter Application** + + + +*Note: you may have to register your phone number with Twitter to create a Twitter application* + +To do this Click your profile icon --> Settings and privacy --> Mobile --> Select Country/region --> Enter phone number --> Click Continue + +5. After you receive confirmation that the Twitter application was created, click **Keys and Access Tokens** + + + +6. Obtain your Twitter Consumer Key and Consumer Secret + + + +7. Add your Consumer Key and Consumer Secret to your config.json file or pass them as environment variables: + * config.json: + ````javascript + { + "production": { + "twitter": { + "consumerKey": "esTCJFXXXXXXXXXXXXXXXXXXX", + "consumerSecret": "zpCs4tU86pRVXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" + } + } + } + ```` + * environment variables: + ```` + HMD_TWITTER_CONSUMERKEY=esTCJFXXXXXXXXXXXXXXXXXXX + HMD_TWITTER_CONSUMERSECRET=zpCs4tU86pRVXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + ```` |