Gh-479: Document GafferPop User Authorisation (#480)

* Document gremlin server user auth

* update gremlin docs with current features

docs/administration-guide/gaffer-deployment/gremlin.md

@@ -154,3 +154,42 @@ uk.gov.gchq.gaffer.tinkerpop.gremlinplugin.GafferPopGremlinPlugin: {}
 !!! tip
     See the [Tinkerpop docs](https://tinkerpop.apache.org/docs/current/reference/#gremlin-server)
     for more information on Gremlin server configuration.
+
+##### User Authentication
+
+Full user authentication is possible with the Gremlin server using the framework
+provided by standard Tinkerpop. The GafferPop implementation provides a
+functional `Authoriser` class that will handle passing the authenticated user to
+the underlying Gaffer graph.
+
+To activate user auth with the Gremlin server you must provide the classes you
+wish to use in the Gremlin server's YAML file like so:
+
+```yaml
+# This should be a deployment specific class
+authentication: {
+  authenticator: uk.gov.gchq.gaffer.tinkerpop.server.auth.ExampleGafferPopAuthenticator
+}
+# This class is necessary for correctly forwarding the user to Gaffer
+authorization: {
+  authorizer: uk.gov.gchq.gaffer.tinkerpop.server.auth.GafferPopAuthoriser
+}
+```
+
+The `authorizer` should always be the `GafferPopAuthoriser` as this is what
+handles denying invalid queries for GafferPop and passing the user on to the
+Gaffer graph for fine grained security.
+
+!!! note
+    The `GafferPopAuthoriser` will deny attempts to set the user ID via a
+    `with("userId", <id>)` step in the Gremlin query.
+
+The `authenticator` should be a class specific to the auth mechanism for your
+deployment e.g. LDAP. An example class `ExampleGafferPopAuthenticator` is
+provided as a start point but does not do any actual authenticating so should
+**not** be used in production.
+
+!!! tip
+    Tinkerpop provides some implementaions of `Authenticators` for standard
+    mechanisms such as [Kerberos](https://tinkerpop.apache.org/javadocs/current/full/org/apache/tinkerpop/gremlin/server/auth/Krb5Authenticator.html).
+    Please see the [Tinkerpop documentation](https://tinkerpop.apache.org/docs/current/reference/#security) for more info.

docs/user-guide/query/gremlin/gremlin-limits.md

@@ -6,28 +6,26 @@ but some features may also be yet to be implemented.
 
 Current TinkerPop features not present in the GafferPop implementation:
 
-- Property index for allowing unseeded queries.
-- Using a Gaffer user for authentication. Access control and authorisations are not supported
-as these are based on users.
-- Removal of entities/edges or properties - base Gaffer currently does not
+- Property index for allowing unseeded queries (unseeded queries run a `GetAllElements`).
+- Gaffer graphs are readonly to Gremlin queries.
   support this.
 - TinkerPop Graph Computer is not supported.
-- Graph Variables can't be updated - there is limited support for this in base
-  Gaffer as usually requires shutting down and restarting the Graph.
 - TinkerPop Transactions are not supported.
+- TinkerPop Lambdas are not supported.
 
 Current known limitations or bugs:
 
+- Proper user authentication is only available if using a Gremlin server to
+  connect to the graph.
+- Performance compared to standard Gaffer `OperationChain`s will likely be
+  slower as multiple Gaffer `Operations` may utilised to perform one Gremlin
+  step.
 - The entity group `id` is reserved for an empty group containing only the
   vertex ID, this is currently used as a workaround for other limitations.
 - When you get the in or out Vertex directly off an Edge it will not contain any
   actual properties or be in correct group/label - it just returns a vertex in
   the `id` group. This is due to Gaffer allowing multiple entities to be
   associated with the source and destination vertices of an Edge.
-- Limited support for updating properties, this has partial support via Gaffer's
-  ingest aggregation mechanism.
-- Performance compared to standard Gaffer OperationChains is hampered due to
-  a custom `TraversalStratergy` not being implemented.
 - The ID of an Edge follows a specific format that is made up of its source and
   destination IDs like `[source, dest]`. To use this in a seeded query you must
   format it like `g.E("[source, dest]")` or a list like

docs/user-guide/query/gremlin/gremlin.md

@@ -251,3 +251,22 @@ a table of how different parts are mapped is as follows:
 | Entity | Vertex |
 | Edge | Edge |
 | Edge ID | A list with the source and destination of the Edge e.g. `[dest, source]` |
+
+## Custom Features
+
+The GafferPop implementation provides some extra features on top of the
+standard Tinkerpop framework that you can utilise in your queries. These
+are likely specific to how a Gaffer graph operates and may not be available
+in other graph technologies that support Gremlin queries.
+
+### Adding Options to Queries
+
+In standard Gremlin syntax it is possible to add additional key value variables
+into a query via a [`with()` step](https://tinkerpop.apache.org/docs/current/reference/#with-step).
+This feature is utilised to allow some custom properties to be passed in
+for Gaffer specific options:
+
+| Key | Example | Description |
+| --- | --- | --- |
+| `operationOptions` | `g.with("operationOptions", "gaffer.federatedstore.operation.graphIds:graphA").V()` | Allows passing options to the underlying Gaffer Operations, this is the same as the `options` field on a standard JSON query. |
+| `getAllElementsLimit` | `g.with("getAllElementsLimit", 100).V()` | Limits the amount of elements returned if performing an unseeded query e.g. a `GetAllElements` operation. |