mirrors/overleaf-toolkit
1
0
Fork 0
mirror of https://github.com/overleaf/toolkit.git synced 2025-04-19 23:38:06 +02:00
Code Activity

Added LDAP and SAML instructions and example instructions

Browse source
This commit is contained in:
Miguel Serrano 2020-12-10 18:03:01 +01:00
parent 530fed2fee
commit 9d9766a8ec
3 changed files with 314 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

2
doc/README.md
View file

@ -34,6 +34,8 @@ documentation on the [Overleaf Wiki](https://github.com/overleaf/overleaf/wiki)
- [Getting Server Pro](./getting-server-pro.md)
- [Sandboxed Compiles](./sandboxed-compiles.md)
- [LDAP integration](./ldap.md)
- [SAML integration](./saml.md)
## Upgrades

137
doc/ldap.md Normal file
View file

@ -0,0 +1,137 @@
# LDAP
Available in Overleaf Server Pro is the ability to use a LDAP server to manage users. It is also possible to use with Active Directory systems.
LDAP is configured via [`variables.env`](./configuration.md)
## Environment Variables
- `SHARELATEX_LDAP_URL` =
Url of the LDAP server,
E.g. 'ldaps://ldap.example.com:636'
- `SHARELATEX_LDAP_EMAIL_ATT` =
The email attribute the LDAP server will return, defaults to 'mail'
- `SHARELATEX_LDAP_NAME_ATT` =
The property name holding the name of the user which is used in the application
- `SHARELATEX_LDAP_LAST_NAME_ATT` =
If your LDAP server has a first and last name then this can be used in conjuction with `SHARELATEX_LDAP_NAME_ATT`
- `SHARELATEX_LDAP_PLACEHOLDER` =
The placeholder for the login form, defaults to 'Username'
- `SHARELATEX_LDAP_UPDATE_USER_DETAILS_ON_LOGIN` =
If set to 'true', will update the user first_name and last_name field on each login, and turn off the user-details form on /user/settings page.
Otherwise, details will be fetched only on first login.
- `SHARELATEX_LDAP_BIND_DN` =
Optional, e.g. 'uid=myapp,ou=users,o=example.com'.
- `SHARELATEX_LDAP_BIND_CREDENTIALS` =
Password for bindDn.
- `SHARELATEX_LDAP_BIND_PROPERTY` =
Optional, default 'dn'. Property of user to bind against client
e.g. 'name', 'email'
- `SHARELATEX_LDAP_SEARCH_BASE` =
The base DN from which to search for users by username.
E.g. 'ou=users,o=example.com'
- `SHARELATEX_LDAP_SEARCH_FILTER` =
LDAP search filter with which to find a user by username, e.g.
'(uid={{username}})'. Use the literal '{{username}}' to have the
given username be interpolated in for the LDAP search.
- `SHARELATEX_LDAP_SEARCH_SCOPE` =
Optional, default 'sub'. Scope of the search, one of 'base',
'one', or 'sub'.
- `SHARELATEX_LDAP_SEARCH_ATTRIBUTES` =
Optional, default all. Json array of attributes to fetch from LDAP server.
- `SHARELATEX_LDAP_GROUP_DN_PROPERTY` =
Optional, default 'dn'. The property of user object to use in
'{{dn}}' interpolation of groupSearchFilter.
- `SHARELATEX_LDAP_GROUP_SEARCH_BASE` =
Optional. The base DN from which to search for groups. If defined,
also groupSearchFilter must be defined for the search to work.
- `SHARELATEX_LDAP_GROUP_SEARCH_SCOPE` =
Optional, default 'sub'.
- `SHARELATEX_LDAP_GROUP_SEARCH_FILTER` =
Optional. LDAP search filter for groups. The following literals are
interpolated from the found user object: '{{dn}}' the property
configured with groupDnProperty. Optionally you can also assign a function instead,
which passes a user object, from this a dynamic groupsearchfilter can be retrieved.
- `SHARELATEX_LDAP_GROUP_SEARCH_ATTRIBUTES` =
Optional, default all. Json array of attributes to fetch from LDAP server.
- `SHARELATEX_LDAP_CACHE` =
Optional, default 'false'. If 'true', then up to 100 credentials at a
time will be cached for 5 minutes.
- `SHARELATEX_LDAP_TIMEOUT` =
Optional, default Infinity. How long the client should let
operations live for before timing out.
- `SHARELATEX_LDAP_CONNECT_TIMEOUT` =
Optional, default is up to the OS. How long the client should wait
before timing out on TCP connections.
- `SHARELATEX_LDAP_TLS_OPTS_CA_PATH` =
A JSON array of paths to the CA file for TLS, must be accessible to the docker container.
E.g. `-env SHARELATEX_LDAP_TLS_OPTS_CA_PATH='["/var/one.pem", "/var/two.pem"]' `
- `SHARELATEX_LDAP_TLS_OPTS_REJECT_UNAUTH` =
If 'true', the server certificate is verified against the list of supplied CAs.
## Example
At Overleaf, we test the LDAP integration against a [test openldap server](https://github.com/rroemhild/docker-test-openldap). The following is an example of a working configuration:
```
# added to variables.env
SHARELATEX_TEMPLATES_USER_ID=578773160210479700917ee5
SHARELATEX_NEW_PROJECT_TEMPLATE_LINKS=[ {"name":"All Templates","url":"/templates/all"}, {"name":"All Categories","url":"/templates"}, {"name":"reports","url":"/templates/reports"}, {"name":"External","url":"https://somewhere.com/templates/reports"} ]
SHARELATEX_LDAP_URL=ldap://ldap:389
SHARELATEX_LDAP_SEARCH_BASE=ou=people,dc=planetexpress,dc=com
SHARELATEX_LDAP_SEARCH_FILTER=(uid={{username}})
SHARELATEX_LDAP_BIND_DN=cn=admin,dc=planetexpress,dc=com
SHARELATEX_LDAP_BIND_CREDENTIALS=GoodNewsEveryone
SHARELATEX_LDAP_EMAIL_ATT=mail
SHARELATEX_LDAP_NAME_ATT=cn
SHARELATEX_LDAP_LAST_NAME_ATT=sn
SHARELATEX_LDAP_UPDATE_USER_DETAILS_ON_LOGIN=true
```
The `openldap` needs to run in the same network as the `sharelatex` container (which by default would be `overleaf_default`), so we'll proceed with the following steps:
- Run `docker network create overleaf_default` (will possibly fail due to a `network with name overleaf_default already exists` error, that's ok).
- Start `openldap` container with `docker run --network=overleaf_default --name=ldap rroemhild/test-openldap`
- Edit `variables.env` to add the LDAP Environment Variables as listed above.
- Restart Server Pro
You should be able to login using `fry` as both username and password.
### Testing, Config & Debugging
After bootstrapping Server Pro for the first time, an existing LDAP user must be given admin permissions visiting `/launchpad` page (or [via CLI](./quick-start-guide.md), but in this case ignoring password confirmation).
LDAP users will appear in Overleaf Admin Panel once they log in first time with their initial credentials.
As LDAP is heavily configurable and flexible by nature it can be a good starting point to have a working example with ldapsearch or even used by another application.
```sh
ldapsearch -H ldap://ad.mydomain.com:389 -x -D ENUMuser@mydomain.com -w ENUMpass -b ou=people,dc=mydomain,dc=com "CN=\*ENUMuser\*" mail
```
## Internals
Internally, Overleaf LDAP uses the [passport-ldapauth](https://github.com/vesse/passport-ldapauth) library. Most of these configuration options are passed through to the `server` config object which is used to configure `passport-ldapauth`. If you are having issues configuring LDAP, it is worth reading the README for `passport-ldapauth` to get a feel for the configuration it expects.

175
doc/saml.md Normal file
View file

@ -0,0 +1,175 @@
# Overleaf SAML
Available in Overleaf Server Pro is the ability to use a SAML server to manage users.
In Overleaf Server Pro, the SAML auth module is configured via environment variables.
## Configuration
- `SHARELATEX_SAML_IDENTITY_SERVICE_NAME`
* Display name for the Identity service, used on the login page
- `SHARELATEX_SAML_EMAIL_FIELD`
* Name of the Email field in user profile, default to 'nameID'.
Alias: `SHARELATEX_SAML_EMAIL_FIELD_NAME`
- `SHARELATEX_SAML_FIRST_NAME_FIELD`
* Name of the firstName field in user profile, default to 'givenName'
- `SHARELATEX_SAML_LAST_NAME_FIELD`
* Name of the lastName field in user profile, default to 'lastName'
- `SHARELATEX_SAML_UPDATE_USER_DETAILS_ON_LOGIN`
* If set to `true`, will update the user first_name and last_name field on each login,
and turn off the user-details form on `/user/settings` page.
- `SHARELATEX_SAML_ENTRYPOINT`
* Entrypoint url for the SAML Identity Service
- `SHARELATEX_SAML_CALLBACK_URL`
* Callback URL for Overleaf service. Should be the full URL of the `/saml/callback` path.
Example: `http://sharelatex.example.com/saml/callback`
- `SHARELATEX_SAML_ISSUER`
* The Issuer name
- `SHARELATEX_SAML_CERT`
* (optional) Identity Provider certificate, used to validate incoming SAML messages.
Example: `MIICizCCAfQCCQCY8tKaMc0BMjANBgkqh ... W==`
See [full documentation](https://github.com/bergie/passport-saml/blob/master/README.md#security-and-signatures)
- `SHARELATEX_SAML_PRIVATE_CERT`
* (optional) Path to a private key in pem format, used to sign auth requests sent by passport-saml
Example: `/some/path/cert.pm`
See [full documentation](https://github.com/bergie/passport-saml/blob/master/README.md#security-and-signatures)
- `SHARELATEX_SAML_DECRYPTION_PVK`
* Optional private key that will be used to attempt to decrypt any encrypted assertions that are received
- `SHARELATEX_SAML_SIGNATURE_ALGORITHM`
* Optionally set the signature algorithm for signing requests,
valid values are 'sha1' (default) or 'sha256'
- `SHARELATEX_SAML_ADDITIONAL_PARAMS`
* JSON dictionary of additional query params to add to all requests
- `SHARELATEX_SAML_ADDITIONAL_AUTHORIZE_PARAMS`
* JSON dictionary of additional query params to add to 'authorize' requests
Example: ` {"some_key": "some_value"} `
- `SHARELATEX_SAML_IDENTIFIER_FORMAT`
* if present, name identifier format to request from identity provider (default: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)
- `SHARELATEX_SAML_ACCEPTED_CLOCK_SKEW_MS`
* Time in milliseconds of skew that is acceptable between client and server when checking OnBefore and NotOnOrAfter assertion
condition validity timestamps. Setting to -1 will disable checking these conditions entirely. Default is 0.
- `SHARELATEX_SAML_ATTRIBUTE_CONSUMING_SERVICE_INDEX`
* optional `AttributeConsumingServiceIndex` attribute to add to AuthnRequest to instruct the IDP which attribute set to attach
to the response ([link](http://blog.aniljohn.com/2014/01/data-minimization-front-channel-saml-attribute-requests.html))
- `SHARELATEX_SAML_AUTHN_CONTEXT`
* if present, name identifier format to request auth context
(default: `urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport`)
- `SHARELATEX_SAML_FORCE_AUTHN `
* if `true`, the initial SAML request from the service provider specifies that the IdP should force re-authentication of the user,
even if they possess a valid session.
- `SHARELATEX_SAML_DISABLE_REQUESTED_AUTHN_CONTEXT `
* if `true`, do not request a specific auth context
- `SHARELATEX_SAML_SKIP_REQUEST_COMPRESSION `
* if set to `true`, the SAML request from the service provider won't be compressed.
- `SHARELATEX_SAML_AUTHN_REQUEST_BINDING`
* if set to `HTTP-POST`, will request authentication from IDP via HTTP POST binding, otherwise defaults to HTTP Redirect
- `SHARELATEX_SAML_VALIDATE_IN_RESPONSE_TO`
* if truthy, then InResponseTo will be validated from incoming SAML responses
- `SHARELATEX_SAML_REQUEST_ID_EXPIRATION_PERIOD_MS`
* Defines the expiration time when a Request ID generated for a SAML request will not be valid if seen
in a SAML response in the `InResponseTo` field. Default is 8 hours.
- `SHARELATEX_SAML_CACHE_PROVIDER`
* Defines the implementation for a cache provider used to store request Ids generated in SAML requests as
part of `InResponseTo` validation. Default is a built-in in-memory cache provider.
See [link](https://github.com/bergie/passport-saml/blob/master/README.md)
- `SHARELATEX_SAML_LOGOUT_URL`
* base address to call with logout requests (default: `entryPoint`)
- `SHARELATEX_SAML_LOGOUT_CALLBACK_URL`
* The value with which to populate the `Location` attribute in the `SingleLogoutService` elements in the generated service provider metadata.
- `SHARELATEX_SAML_ADDITIONAL_LOGOUT_PARAMS`
* JSON dictionary of additional query params to add to 'logout' requests
## Using Http Post
Note, if `SHARELATEX_SAML_AUTHN_REQUEST_BINDING` is set to `HTTP-POST`, then `SHARELATEX_SAML_SKIP_REQUEST_COMPRESSION` must also be set to `true`.
## Configuration Example
At Overleaf, we test the SAML integration against a SAML test server. The following is an example of a working configuration:
```
# added to variables.env
SHARELATEX_SAML_ENTRYPOINT=http://localhost:8081/simplesaml/saml2/idp/SSOService.php
SHARELATEX_SAML_CALLBACK_URL=http://saml/saml/callback
SHARELATEX_SAML_ISSUER=sharelatex-test-saml
SHARELATEX_SAML_IDENTITY_SERVICE_NAME=SAML Test Server
SHARELATEX_SAML_EMAIL_FIELD=email
SHARELATEX_SAML_FIRST_NAME_FIELD=givenName
SHARELATEX_SAML_LAST_NAME_FIELD=sn
SHARELATEX_SAML_UPDATE_USER_DETAILS_ON_LOGIN=true
```
The `sharelatex/saml-test` image needs to run in the same network as the `sharelatex` container (which by default would be `overleaf_default`), so we'll proceed with the following steps:
- Run `docker network create overleaf_default` (will possibly fail due to a `network with name overleaf_default already exists` error, that's ok).
- Start `saml-test` container with some environment parameters:
```
docker run --network=overleaf_default --name=saml \
--publish='8081:80' \
--env SAML_BASE_URL_PATH='http://localhost:8081/simplesaml/' \
--env SAML_TEST_SP_ENTITY_ID='sharelatex-test-saml' \
--env SAML_TEST_SP_LOCATION='http://localhost/saml/callback' \
sharelatex/saml-test
```
- Edit `variables.env` to add the SAML Environment Variables as listed above.
- Restart Server Pro.
You should be able to login using `sally` as username and `sall123` as password.
## Metadata for the Identity Provider
The Identity Provider will need to be configured to recognize the Overleaf server as a "Service Provider". Consult the documentation for your SAML server for instructions on how to do this.
Here is an example of appropriate Service Provider metadata, note the `AssertionConsumerService.Location`, `EntityDescriptor.entityID` and `EntityDescriptor.ID` properties, and set as appropriate.
```
<?xml version="1.0"?>
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
entityID="sharelatex-saml"
ID="sharelatex_saml">
<SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
<AssertionConsumerService index="1"
isDefault="true"
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Location="http://sharelatex-host/saml/callback" />
</SPSSODescriptor>
</EntityDescriptor>
```
## Internals
Internally, the [passport-saml](https://github.com/bergie/passport-saml) module is used, and these config values are passed along to `passport-saml`.