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

Replaced copied text with links to the wiki

Browse source
This commit is contained in:
Miguel Serrano 2020-12-10 18:38:43 +01:00
parent bceb780d32
commit 69d1d42993
2 changed files with 5 additions and 238 deletions
Download patch file Download diff file Expand all files Collapse all files

105
doc/ldap.md
View file

@ -2,94 +2,9 @@
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)
LDAP is configured in the Toolkit 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.
The [Developer wiki](https://github.com/overleaf/overleaf/wiki/Server-Pro:-LDAP-Config) contains further documentation on the available Environment Variables and other configuration elements.
## Example
@ -119,19 +34,3 @@ The `openldap` needs to run in the same network as the `sharelatex` container (w
- 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.

138
doc/saml.md
View file

@ -2,116 +2,11 @@
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.
SAML is configured in the Toolkit via [`variables.env`](./configuration.md).
## Configuration
The [Developer wiki](https://github.com/overleaf/overleaf/wiki/Server-Pro:-SAML-Config) contains further documentation on the available Environment Variables and other configuration elements.
- `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
## Example
At Overleaf, we test the SAML integration against a SAML test server. The following is an example of a working configuration:
@ -146,30 +41,3 @@ docker run --network=overleaf_default --name=saml \
- 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`.