Merge pull request #633 from nakaeeee/saml-auth

Support SAML authentication
This commit is contained in:
Christoph (Sheogorath) Kern 2017-12-04 18:57:57 +01:00 committed by GitHub
commit 0957f5963b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
19 changed files with 306 additions and 4 deletions

View file

@ -172,6 +172,16 @@ There are some configs you need to change in the files below
| HMD_LDAP_SEARCHATTRIBUTES | no example | LDAP attributes to search with |
| HMD_LDAP_TLS_CA | `server-cert.pem, root.pem` | Root CA for LDAP TLS in PEM format (use comma to separate) |
| HMD_LDAP_PROVIDERNAME | `My institution` | Optional name to be displayed at login form indicating the LDAP provider |
| HMD_SAML_IDPSSOURL | `https://idp.example.com/sso` | authentication endpoint of IdP. for details, see [guide](docs/guides/auth.md#saml-onelogin). |
| HMD_SAML_IDPCERT | `/path/to/cert.pem` | certificate file path of IdP in PEM format |
| HMD_SAML_ISSUER | no example | identity of the service provider (optional, default: serverurl)" |
| HMD_SAML_IDENTIFIERFORMAT | no example | name identifier format (optional, default: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`) |
| HMD_SAML_GROUPATTRIBUTE | `memberOf` | attribute name for group list (optional) |
| HMD_SAML_REQUIREDGROUPS | `Hackmd-users` | group names that allowed (use vertical bar to separate) (optional) |
| HMD_SAML_EXTERNALGROUPS | `Temporary-staff` | group names that not allowed (use vertical bar to separate) (optional) |
| HMD_SAML_ATTRIBUTE_ID | `sAMAccountName` | attribute map for `id` (optional, default: NameID of SAML response) |
| HMD_SAML_ATTRIBUTE_USERNAME | `mailNickname` | attribute map for `username` (optional, default: NameID of SAML response) |
| HMD_SAML_ATTRIBUTE_EMAIL | `mail` | attribute map for `email` (optional, default: NameID of SAML response if `HMD_SAML_IDENTIFIERFORMAT` is default) |
| HMD_IMGUR_CLIENTID | no example | Imgur API client id |
| HMD_EMAIL | `true` or `false` | set to allow email signin |
| HMD_ALLOW_PDF_EXPORT | `true` or `false` | Enable or disable PDF exports |
@ -234,7 +244,7 @@ There are some configs you need to change in the files below
| service | settings location | description |
| ------- | --------- | ----------- |
| facebook, twitter, github, gitlab, mattermost, dropbox, google, ldap | environment variables or `config.json` | for signin |
| facebook, twitter, github, gitlab, mattermost, dropbox, google, ldap, saml | environment variables or `config.json` | for signin |
| imgur, s3 | environment variables or `config.json` | for image upload |
| google drive(`google/apiKey`, `google/clientID`), dropbox(`dropbox/appKey`) | `config.json` | for export and import |
@ -249,6 +259,7 @@ There are some configs you need to change in the files below
| mattermost | `/auth/mattermost/callback` |
| dropbox | `/auth/dropbox/callback` |
| google | `/auth/google/callback` |
| saml | `/auth/saml/callback` |
# Developer Notes

View file

@ -75,6 +75,20 @@
"changeme": "See https://nodejs.org/api/tls.html#tls_tls_connect_options_callback"
}
},
"saml": {
"idpSsoUrl": "change: authentication endpoint of IdP",
"idpCert": "change: certificate file path of IdP in PEM format",
"issuer": "change or delete: identity of the service provider (default: serverurl)",
"identifierFormat": "change or delete: name identifier format (default: 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress')",
"groupAttribute": "change or delete: attribute name for group list (ex: memberOf)",
"requiredGroups": [ "change or delete: group names that allowed" ],
"externalGroups": [ "change or delete: group names that not allowed" ],
"attribute": {
"id": "change or delete this: attribute map for `id` (default: NameID)",
"username": "change or delete this: attribute map for `username` (default: NameID)",
"email": "change or delete this: attribute map for `email` (default: NameID)"
}
},
"imgur": {
"clientID": "change this"
},

View file

@ -75,3 +75,138 @@ To do this Click your profile icon --> Settings and privacy --> Mobile --> Sele
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**.
![onelogin-add-app](images/auth/onelogin-add-app.png)
4. Find "SAML Test Connector (SP)" for template of settings and select it.
![onelogin-select-template](images/auth/onelogin-select-template.png)
5. Edit display name and icons for OneLogin dashboard as you want, and click **SAVE**.
![onelogin-edit-app-name](images/auth/onelogin-edit-app-name.png)
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)
![onelogin-edit-sp-metadata](images/auth/onelogin-edit-sp-metadata.png)
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)
![onelogin-copy-idp-metadata](images/auth/onelogin-copy-idp-metadata.png)
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).
![onelogin-use-dashboard](images/auth/onelogin-use-dashboard.png)
### 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 `idfentifierFormat` 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
````

Binary file not shown.

After

Width:  |  Height:  |  Size: 40 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 234 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 120 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 180 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 72 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 27 KiB

View file

@ -98,6 +98,20 @@ module.exports = {
searchAttributes: undefined,
tlsca: undefined
},
saml: {
idpSsoUrl: undefined,
idpCert: undefined,
issuer: undefined,
identifierFormat: 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
groupAttribute: undefined,
externalGroups: [],
requiredGroups: [],
attribute: {
id: undefined,
username: undefined,
email: undefined
}
},
email: true,
allowemailregister: true,
allowpdfexport: true

View file

@ -73,6 +73,20 @@ module.exports = {
searchAttributes: process.env.HMD_LDAP_SEARCHATTRIBUTES,
tlsca: process.env.HMD_LDAP_TLS_CA
},
saml: {
idpSsoUrl: process.env.HMD_SAML_IDPSSOURL,
idpCert: process.env.HMD_SAML_IDPCERT,
issuer: process.env.HMD_SAML_ISSUER,
identifierFormat: process.env.HMD_SAML_IDENTIFIERFORMAT,
groupAttribute: process.env.HMD_SAML_GROUPATTRIBUTE,
externalGroups: process.env.HMD_SAML_EXTERNALGROUPS ? process.env.HMD_SAML_EXTERNALGROUPS.split('|') : [],
requiredGroups: process.env.HMD_SAML_REQUIREDGROUPS ? process.env.HMD_SAML_REQUIREDGROUPS.split('|') : [],
attribute: {
id: process.env.HMD_SAML_ATTRIBUTE_ID,
username: process.env.HMD_SAML_ATTRIBUTE_USERNAME,
email: process.env.HMD_SAML_ATTRIBUTE_EMAIL
}
},
email: toBooleanConfig(process.env.HMD_EMAIL),
allowemailregister: toBooleanConfig(process.env.HMD_ALLOW_EMAIL_REGISTER),
allowpdfexport: toBooleanConfig(process.env.HMD_ALLOW_PDF_EXPORT)

View file

@ -92,6 +92,7 @@ config.isGitHubEnable = config.github.clientID && config.github.clientSecret
config.isGitLabEnable = config.gitlab.clientID && config.gitlab.clientSecret
config.isMattermostEnable = config.mattermost.clientID && config.mattermost.clientSecret
config.isLDAPEnable = config.ldap.url
config.isSAMLEnable = config.saml.idpSsoUrl
config.isPDFExportEnable = config.allowpdfexport
// generate correct path

View file

@ -143,6 +143,15 @@ module.exports = function (sequelize, DataTypes) {
photo = letterAvatars(profile.username)
}
break
case 'saml':
if (profile.emails[0]) {
photo = 'https://www.gravatar.com/avatar/' + md5(profile.emails[0])
if (bigger) photo += '?s=400'
else photo += '?s=96'
} else {
photo = letterAvatars(profile.username)
}
break
}
return photo
},

View file

@ -68,6 +68,7 @@ function showIndex (req, res, next) {
dropbox: config.isDropboxEnable,
google: config.isGoogleEnable,
ldap: config.isLDAPEnable,
saml: config.isSAMLEnable,
email: config.isEmailEnable,
allowemailregister: config.allowemailregister,
allowpdfexport: config.allowpdfexport,
@ -100,6 +101,7 @@ function responseHackMD (res, note) {
dropbox: config.isDropboxEnable,
google: config.isGoogleEnable,
ldap: config.isLDAPEnable,
saml: config.isSAMLEnable,
email: config.isEmailEnable,
allowemailregister: config.allowemailregister,
allowpdfexport: config.allowpdfexport

View file

@ -37,6 +37,7 @@ if (config.isMattermostEnable) authRouter.use(require('./mattermost'))
if (config.isDropboxEnable) authRouter.use(require('./dropbox'))
if (config.isGoogleEnable) authRouter.use(require('./google'))
if (config.isLDAPEnable) authRouter.use(require('./ldap'))
if (config.isSAMLEnable) authRouter.use(require('./saml'))
if (config.isEmailEnable) authRouter.use(require('./email'))
// logout

View file

@ -0,0 +1,95 @@
'use strict'
const Router = require('express').Router
const passport = require('passport')
const SamlStrategy = require('passport-saml').Strategy
const config = require('../../../config')
const models = require('../../../models')
const logger = require('../../../logger')
const {urlencodedParser} = require('../../utils')
const fs = require('fs')
const intersection = function (array1, array2) { return array1.filter((n) => array2.includes(n)) }
let samlAuth = module.exports = Router()
passport.use(new SamlStrategy({
callbackUrl: config.serverurl + '/auth/saml/callback',
entryPoint: config.saml.idpSsoUrl,
issuer: config.saml.issuer || config.serverurl,
cert: fs.readFileSync(config.saml.idpCert, 'utf-8'),
identifierFormat: config.saml.identifierFormat
}, function (user, done) {
// check authorization if needed
if (config.saml.externalGroups && config.saml.grouptAttribute) {
var externalGroups = intersection(config.saml.externalGroups, user[config.saml.groupAttribute])
if (externalGroups.length > 0) {
logger.error('saml permission denied: ' + externalGroups.join(', '))
return done('Permission denied', null)
}
}
if (config.saml.requiredGroups && config.saml.grouptAttribute) {
if (intersection(config.saml.requiredGroups, user[config.saml.groupAttribute]).length === 0) {
logger.error('saml permission denied')
return done('Permission denied', null)
}
}
// user creation
var uuid = user[config.saml.attribute.id] || user.nameID
var profile = {
provider: 'saml',
id: 'SAML-' + uuid,
username: user[config.saml.attribute.username] || user.nameID,
emails: user[config.saml.attribute.email] ? [user[config.saml.attribute.email]] : []
}
if (profile.emails.length === 0 && config.saml.identifierFormat === 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress') {
profile.emails.push(user.nameID)
}
var stringifiedProfile = JSON.stringify(profile)
models.User.findOrCreate({
where: {
profileid: profile.id.toString()
},
defaults: {
profile: stringifiedProfile
}
}).spread(function (user, created) {
if (user) {
var needSave = false
if (user.profile !== stringifiedProfile) {
user.profile = stringifiedProfile
needSave = true
}
if (needSave) {
user.save().then(function () {
if (config.debug) { logger.debug('user login: ' + user.id) }
return done(null, user)
})
} else {
if (config.debug) { logger.debug('user login: ' + user.id) }
return done(null, user)
}
}
}).catch(function (err) {
logger.error('saml auth failed: ' + err)
return done(err, null)
})
}))
samlAuth.get('/auth/saml',
passport.authenticate('saml', {
successReturnToOrRedirect: config.serverurl + '/',
failureRedirect: config.serverurl + '/'
})
)
samlAuth.post('/auth/saml/callback', urlencodedParser,
passport.authenticate('saml', {
successReturnToOrRedirect: config.serverurl + '/',
failureRedirect: config.serverurl + '/'
})
)
samlAuth.get('/auth/saml/metadata', function (req, res) {
res.type('application/xml')
res.send(passport._strategy('saml').generateServiceProviderMetadata())
})

View file

@ -94,6 +94,7 @@
"passport-local": "^1.0.0",
"passport-oauth2": "^1.4.0",
"passport-twitter": "^1.0.4",
"passport-saml": "^0.31.0",
"passport.socketio": "^3.7.0",
"pdfobject": "^2.0.201604172",
"pg": "^6.1.2",

View file

@ -15,7 +15,7 @@
<% if(allowAnonymous) { %>
<a type="button" href="<%- url %>/new" class="btn btn-sm btn-primary"><i class="fa fa-plus"></i> <%= __('New guest note') %></a>
<% } %>
<% if(facebook || twitter || github || gitlab || mattermost || dropbox || google || ldap || email) { %>
<% if(facebook || twitter || github || gitlab || mattermost || dropbox || google || ldap || saml || email) { %>
<button class="btn btn-sm btn-success ui-signin" data-toggle="modal" data-target=".signin-modal"><%= __('Sign In') %></button>
<% } %>
</div>
@ -48,7 +48,7 @@
<% if (errorMessage && errorMessage.length > 0) { %>
<div class="alert alert-danger" style="max-width: 400px; margin: 0 auto;"><%= errorMessage %></div>
<% } %>
<% if(facebook || twitter || github || gitlab || mattermost || dropbox || google || ldap || email) { %>
<% if(facebook || twitter || github || gitlab || mattermost || dropbox || google || ldap || saml || email) { %>
<span class="ui-signin">
<br>
<a type="button" class="btn btn-lg btn-success ui-signin" data-toggle="modal" data-target=".signin-modal" style="min-width: 200px;"><%= __('Sign In') %></a>

View file

@ -43,7 +43,12 @@
<i class="fa fa-google"></i> <%= __('Sign in via %s', 'Google') %>
</a>
<% } %>
<% if((facebook || twitter || github || gitlab || mattermost || dropbox || google) && ldap) { %>
<% if(saml) { %>
<a href="<%- url %>/auth/saml" class="btn btn-lg btn-block btn-social btn-success">
<i class="fa fa-users"></i> <%= __('Sign in via %s', 'SAML') %>
</a>
<% } %>
<% if((facebook || twitter || github || gitlab || mattermost || dropbox || google || saml) && ldap) { %>
<hr>
<% }%>
<% if(ldap) { %>