Added v3.3 doc updates

stevespringett · stevespringett · commit 0e1ded524956 · 2018-10-25T10:50:27.000-05:00
diff --git a/docs/_docs/getting-started/configuration.md b/docs/_docs/getting-started/configuration.md
@@ -50,23 +50,23 @@ alpine.worker.threads=0
 alpine.worker.thread.multiplier=4
 
 # Required
-# Defines the path to the data directory. This directory will hold logs,
-# keys, and any database or index files along with application-specific
-# files or directories.
+# Defines the path to the data directory. This directory will hold logs, keys,
+# and any database or index files along with application-specific files or 
+# directories.
 alpine.data.directory=~/.dependency-track
 
 # Required
-# Defines the interval (in seconds) to log general heath information.
-# If value equals 0, watchdog logging will be disabled.
+# Defines the interval (in seconds) to log general heath information. If value
+# equals 0, watchdog logging will be disabled.
 alpine.watchdog.logging.interval=0
 
 # Required
 # Defines the database mode of operation. Valid choices are:
 # 'server', 'embedded', and 'external'.
-# In server mode, the database will listen for connections from remote
-# hosts. In embedded mode, the system will be more secure and slightly
-# faster. External mode should be used when utilizing an external
-# database server (i.e. mysql, postgresql, etc).
+# In server mode, the database will listen for connections from remote hosts.
+# In embedded mode, the system will be more secure and slightly faster. 
+# External mode should be used when utilizing an external database server 
+# (i.e. mysql, postgresql, etc).
 alpine.database.mode=embedded
 
 # Optional
@@ -94,16 +94,15 @@ alpine.database.username=sa
 # alpine.database.password=
 
 # Optional
-# When authentication is enforced, API keys are required for automation,
-# and the user interface will prevent anonymous access by prompting for login
+# When authentication is enforced, API keys are required for automation, and
+# the user interface will prevent anonymous access by prompting for login
 # credentials.
 alpine.enforce.authentication=true
 
 # Optional
-# When authorization is enforced, team membership for both API keys and
-# user accounts are restricted to what the team itself has access to.
-# To enforce authorization, the enforce.authentication property (above)
-# must be true.
+# When authorization is enforced, team membership for both API keys and user
+# accounts are restricted to what the team itself has access to. To enforce 
+# authorization, the enforce.authentication property (above) must be true.
 alpine.enforce.authorization=true
 
 # Required
@@ -119,54 +118,100 @@ alpine.ldap.enabled=false
 
 # Optional
 # Specifies the LDAP server URL
+# Example (Microsoft Active Directory):
+#    alpine.ldap.server.url=ldap://ldap.example.com:3268
+#    alpine.ldap.server.url=ldaps://ldap.example.com:3269
+# Example (ApacheDS, Fedora 389 Directory, NetIQ/Novell eDirectory, etc):
+#    alpine.ldap.server.url=ldap://ldap.example.com:389
+#    alpine.ldap.server.url=ldaps://ldap.example.com:636
 alpine.ldap.server.url=ldap://ldap.example.com:389
 
-# Optional
-# Specifies the LDAP server domain. This is normally appended to the end of the
-# username to form the userPrincipalName
-alpine.ldap.domain=example.com
-
 # Optional
 # Specifies the base DN that all queries should search from
 alpine.ldap.basedn=dc=example,dc=com
 
 # Optional
-# Specifies the LDAP security authentication level to use. 
-# Its value is one of the following strings: "none", "simple", "strong".
-# If this property is empty or unspecified, the behaviour is determined by the service provider.
+# Specifies the LDAP security authentication level to use. Its value is one of
+# the following strings: "none", "simple", "strong". If this property is empty
+# or unspecified, the behaviour is determined by the service provider.
 alpine.ldap.security.auth=simple
 
 # Optional
-# If anonymous access is not permitted, specify a username with limited
-# access to the directory. Just enough to perform searches.
+# If anonymous access is not permitted, specify a username with limited access
+# to the directory, just enough to perform searches. This should be the fully
+# qualified DN of the user.
 alpine.ldap.bind.username=
 
 # Optional
-# If anonymous access is not permitted, specify a password for the
-# username used to bind.
+# If anonymous access is not permitted, specify a password for the username
+# used to bind.
 alpine.ldap.bind.password=
 
 # Optional
-# Specifies how to map the user identifier entered by the user to that passed through to LDAP.
-# If is configured to a non-empty value, the substring %s in this value will be replaced
-# with the entered username.
-# The recommended format of this value depends on your LDAP server(Active Directory, OpenLDAP, etc.).
-# Examples:
-#	 alpine.ldap.auth.username.format=%s
-#	 alpine.ldap.auth.username.format=%s@example.com
-#	 alpine.ldap.auth.username.format=uid=%s,ou=People,dc=example,dc=com
-#	 alpine.ldap.auth.username.format=userPrincipalName=%s,ou=People,dc=example,dc=com
-alpine.ldap.auth.username.format=
+# Specifies if the username entered during login needs to be formatted prior
+# to asserting credentials against the directory. For Active Directory, the
+# userPrincipal attribute typically ends with the domain, whereas the
+# samAccountName attribute and other directory server implementations do not.
+# The %s variable will be substitued with the username asserted during login.
+# Example (Microsoft Active Directory):
+#    alpine.ldap.auth.username.format=%s@example.com
+# Example (ApacheDS, Fedora 389 Directory, NetIQ/Novell eDirectory, etc):
+#    alpine.ldap.auth.username.format=%s
+alpine.ldap.auth.username.format=%s@example.com
 
 # Optional
-# Specifies the Attribute that all queries should use
-# The default attribute is userPrincipalName
+# Specifies the Attribute that identifies a users ID
+# Example (Microsoft Active Directory):
+#    alpine.ldap.attribute.name=userPrincipalName
+# Example (ApacheDS, Fedora 389 Directory, NetIQ/Novell eDirectory, etc):
+#    alpine.ldap.attribute.name=uid
 alpine.ldap.attribute.name=userPrincipalName
 
 # Optional
 # Specifies the LDAP attribute used to store a users email address
 alpine.ldap.attribute.mail=mail
 
+# Optional
+# Specifies the LDAP search filter used to retrieve all groups from the
+# directory.
+# Example (Microsoft Active Directory):
+#    alpine.ldap.groups.filter=(&(objectClass=group)(objectCategory=Group))
+# Example (ApacheDS, Fedora 389 Directory, NetIQ/Novell eDirectory, etc):
+#    alpine.ldap.groups.filter=(&(objectClass=groupOfUniqueNames))
+alpine.ldap.groups.filter=(&(objectClass=group)(objectCategory=Group))
+
+# Optional
+# Specifies the LDAP search filter to use to query a user and retrieve a list
+# of groups the user is a member of. The {USER_DN} variable will be substituted
+# with the actual value of the users DN at runtime.
+# Example (Microsoft Active Directory):
+#    alpine.ldap.user.groups.filter=(&(objectClass=group)(objectCategory=Group)(member={USER_DN}))
+# Example (Microsoft Active Directory - with nested group support):
+#    alpine.ldap.user.groups.filter=(member:1.2.840.113556.1.4.1941:={USER_DN})
+# Example (ApacheDS, Fedora 389 Directory, NetIQ/Novell eDirectory, etc):
+#    alpine.ldap.user.groups.filter=(&(objectClass=groupOfUniqueNames)(uniqueMember={USER_DN}))
+alpine.ldap.user.groups.filter=(member:1.2.840.113556.1.4.1941:={USER_DN})
+
+# Optional
+# Specifies if mapped LDAP accounts are automatically created upon successful
+# authentication. When a user logs in with valid credentials but an account has
+# not been previously provisioned, an authentication failure will be returned.
+# This allows admins to control specifically which ldap users can access the
+# system and which users cannot. When this value is set to true, a local ldap
+# user will be created and mapped to the ldap account automatically. This
+# automatic provisioning only affects authentication, not authorization.
+alpine.ldap.user.provisioning=false
+
+# Optional
+# This option will ensure that team memberships for LDAP users are dynamic and
+# synchronized with membership of LDAP groups. When a team is mapped to an LDAP
+# group, all local LDAP users will automatically be assigned to the team if
+# they are a member of the group the team is mapped to. If the user is later
+# removed from the LDAP group, they will also be removed from the team. This
+# option provides the ability to dynamically control user permissions via an
+# external directory.
+alpine.ldap.team.synchronization=false
+
 # Optional
 # HTTP proxy. If the address is set, then the port must be set too.
 # alpine.http.proxy.address=proxy.example.com
diff --git a/docs/_docs/getting-started/ldap-configuration.md b/docs/_docs/getting-started/ldap-configuration.md
@@ -0,0 +1,74 @@
+---
+title: LDAP Configuration
+category: Getting Started
+chapter: 1
+order: 8
+---
+
+Dependency-Track has been tested with multiple LDAP servers. The following are
+some example configurations that are known to work with the default schema of
+each server implementation.
+
+#### Microsoft Active Directory Example
+
+```ini
+alpine.ldap.enabled=true
+alpine.ldap.server.url=ldap://ldap.example.com:3268
+alpine.ldap.basedn=dc=example,dc=com
+alpine.ldap.security.auth=simple
+alpine.ldap.auth.username.format=%s@example.com
+alpine.ldap.bind.username=cn=ServiceAccount,cn=Users,dc=example,dc=com
+alpine.ldap.bind.password=mypassword
+alpine.ldap.attribute.name=userPrincipalName
+alpine.ldap.attribute.mail=mail
+alpine.ldap.groups.filter=(&(objectClass=group)(objectCategory=Group))
+alpine.ldap.user.groups.filter=(member:1.2.840.113556.1.4.1941:={USER_DN})
+```
+
+#### ApacheDS Example
+
+```ini
+alpine.ldap.enabled=true
+alpine.ldap.server.url=ldap://ldap.example.com:389
+alpine.ldap.basedn=dc=example,dc=com
+alpine.ldap.security.auth=simple
+alpine.ldap.auth.username.format=%s
+alpine.ldap.bind.username=uid=ServiceAccount,ou=system
+alpine.ldap.bind.password=mypassword
+alpine.ldap.attribute.name=cn
+alpine.ldap.attribute.mail=mail
+alpine.ldap.groups.filter=(&(objectClass=groupOfUniqueNames))
+alpine.ldap.user.groups.filter=(&(objectClass=groupOfUniqueNames)(uniqueMember={USER_DN}))
+```
+
+#### Fedora 389 Directory Example
+
+```ini
+alpine.ldap.enabled=true
+alpine.ldap.server.url=ldap://ldap.example.com:389
+alpine.ldap.basedn=dc=example,dc=com
+alpine.ldap.security.auth=simple
+alpine.ldap.auth.username.format=%s
+alpine.ldap.bind.username=cn=directory manager
+alpine.ldap.bind.password=mypassword
+alpine.ldap.attribute.name=uid
+alpine.ldap.attribute.mail=mail
+alpine.ldap.groups.filter=(&(objectClass=groupOfUniqueNames))
+alpine.ldap.user.groups.filter=(&(objectClass=groupOfUniqueNames)(uniqueMember={USER_DN}))
+```
+
+#### NetIQ/Novell eDirectory Example
+
+```ini
+alpine.ldap.enabled=true
+alpine.ldap.server.url=ldaps://ldap.example.com:636
+alpine.ldap.basedn=o=example
+alpine.ldap.security.auth=simple
+alpine.ldap.auth.username.format=%s
+alpine.ldap.bind.username=cn=ServiceAccount,o=example
+alpine.ldap.bind.password=mypassword
+alpine.ldap.attribute.name=uid
+alpine.ldap.attribute.mail=mail
+alpine.ldap.groups.filter=(&(objectClass=groupOfUniqueNames))
+alpine.ldap.user.groups.filter=(&(objectClass=groupOfUniqueNames)(uniqueMember={USER_DN}))
+```
diff --git a/docs/_posts/2018-10-25-v3.3.0.md b/docs/_posts/2018-10-25-v3.3.0.md
@@ -0,0 +1,57 @@
+---
+title: v3.3.0
+type: major
+---
+
+**Features:**
+
+* The ability to manually upload a CycloneDX or SPDX BoM from the user interface
+* Optional automated provisioning of LDAP users
+* Optional synchronization of team membership based on a users LDAP group membership
+* Added API that provides component metadata from a project in CycloneDX format
+* Added ability to track the progress of work performed when a BoM is uploaded
+* Added tracking of audited and unaudited metrics
+* Added ability to add new project version and optionally clone source metadata
+* Added ability to search by tag name when displaying projects
+* Added checksum generation when publishing a release (backported to 3.2.2)
+* The NSP Advisory API has been removed and replaced with the NPM Public Advisory API (backported to v3.2.1)
+
+**Fixes:**
+
+* Fixed numerous LDAP compatibility issues
+* Added additional logging when BoM upload is not in a supported format
+
+**Upgrade Notes:**
+
+This release of Dependency-Track supports a wide range of LDAP implementations and has been tested with 
+Active Directory, ApacheDS, Fedora 389 Directory, and NetIQ/Novell eDirectory. In order to ensure compatibility,
+some existing LDAP configuration properties have been changed.
+
+
+```ini
+# This property has been removed
+alpine.ldap.domain
+```
+
+```ini
+# This property now refers to the users DN
+alpine.ldap.bind.username
+```
+
+```ini
+# Format now applies only to the value of alpine.ldap.attribute.name. 
+# Examples have been modified. A users DN is no longer a valid format.
+alpine.ldap.auth.username.format
+```
+
+```ini
+# New properties
+alpine.ldap.groups.filter
+alpine.ldap.user.groups.filter
+alpine.ldap.user.provisioning
+alpine.ldap.team.synchronization
+```
+
+**See Also:**
+* [Configuration]({{ site.baseurl }}{% link _docs/getting-started/configuration.md %}) (updated)
+* [LDAP Configuration]({{ site.baseurl }}{% link _docs/getting-started/ldap-configuration.md %}) (examples)
