You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by sp...@apache.org on 2020/12/24 19:17:14 UTC
[tinkerpop] branch master updated: Minor documentation
fixes/updates after merging authorization work CTR
This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
The following commit(s) were added to refs/heads/master by this push:
new 9ed40bb Minor documentation fixes/updates after merging authorization work CTR
9ed40bb is described below
commit 9ed40bb0b6913a68f240f48b54abdddbd362199b
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Thu Dec 24 14:16:43 2020 -0500
Minor documentation fixes/updates after merging authorization work CTR
---
docs/src/reference/gremlin-applications.asciidoc | 9 +++++++-
docs/src/reference/the-traversal.asciidoc | 5 +++--
docs/src/upgrade/release-3.5.x.asciidoc | 26 ++++++++++++++++++++++--
3 files changed, 35 insertions(+), 5 deletions(-)
diff --git a/docs/src/reference/gremlin-applications.asciidoc b/docs/src/reference/gremlin-applications.asciidoc
index 8d9efa4..411cd2f 100644
--- a/docs/src/reference/gremlin-applications.asciidoc
+++ b/docs/src/reference/gremlin-applications.asciidoc
@@ -1526,6 +1526,7 @@ export JAVA_OPTIONS="${JAVA_OPTIONS} ${KRB5_OPTION} ${JAAS_OPTION}"
[[authorization]]
==== Authorization
+
While authentication determines which clients can connect to Gremlin Server, authorization regulates which elements
of the exposed graphs a specific user is allowed to create, read, update or delete (CRUD). Authorization in Gremlin
Server can take place at two instances. Before execution a user request can be allowed or denied based on the
@@ -1540,7 +1541,12 @@ presence of operations such as:
During execution the applied traversal strategies influence the results and side-effects of a given query.
+IMPORTANT: Authorization is a feature of Gremlin Server, but is not implemented as an element of the server protocol
+and therefore Remote Graph Providers may not have this feature or may not implement it in this particular way. Please
+consult the documentation of the graph you are using to determine what authorization features it supports.
+
===== Mechanisms
+
Gremlin Server supports three mechanisms to configure authorization:
. With the `ScriptFileGremlinPlugin` a groovy script is configured that instantiates the `GraphTraversalSources` that
@@ -1592,7 +1598,7 @@ following a policy that takes into account both the authenticated user and the o
the most flexible and can support an almost unlimited number of authorization policies, it is somewhat complex to
implement. In particular, applying the `SubgraphStrategy` requires knowledge about the schema of the graph.
-The passive authoratization solution perhaps provides a middle ground to start implementing authorization. This
+The passive authorization solution perhaps provides a middle ground to start implementing authorization. This
solution assumes that the `SubgraphStrategy` is applied in the Gremlin Server initialization script, because compliance
with a subgraph restriction can only be determined during the actual execution of the gremlin traversal. Note that the
same graph can be reused with different `SubgraphStrategies`. Now, authorization policies can be defined in terms of
@@ -1612,6 +1618,7 @@ offered as <<gremlin-plugins, gremlin plugins>>.
[[authz-code-example]]
===== Code example
+
The two java classes below provide an example implementation of the `Authorizer` interface; they originate from
link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-server/src/test/java/org/apache/tinkerpop/gremlin/server/authz[Gremlin Server's test package].
If you copy the files into a project, build them into a jar and add the jar to Gremlin Server's CLASSPATH, you can use
diff --git a/docs/src/reference/the-traversal.asciidoc b/docs/src/reference/the-traversal.asciidoc
index 776981c..b037abb 100644
--- a/docs/src/reference/the-traversal.asciidoc
+++ b/docs/src/reference/the-traversal.asciidoc
@@ -3803,19 +3803,19 @@ following sections detail how traversal strategies are applied and defined and d
strategies that are generally useful to end-users.
=== Application
+
One can explicitly add or remove `TraversalStrategy` strategies on the `GraphTraversalSource` with the `withStrategies()`
and `withoutStrategies()` <<start-steps, start steps>>, see the <<readonlystrategy, ReadOnlyStrategy>> and the
<<barrier-step, barrier() step>> for examples. End users typically do this as part of issuing a gremlin traversal, either
on a locally opened graph or a remotely accessed graph. However, when configuring Gremlin Server, traversal strategies
can also be applied on exposed `GraphTraversalSource` instances and as part of an `Authorizer` implementation, see
link:https://tinkerpop.apache.org/docs/x.y.z/reference/#authorization[Gremlin Server Authorization].
-Therefore, one should keep the following in mind when modifiying the list of `TraversalStrategy` strategies:
+Therefore, one should keep the following in mind when modifying the list of `TraversalStrategy` strategies:
* A `TraversalStrategy` added to the traversal can be removed again later on. An example is the
`conf/gremlin-server-modern-readonly.yaml` file from the Gremlin Server distribution, which applies the `ReadOnlyStrategy`
to the `GraphTraversalSource` that remote clients can connect to. However, a remote client can remove it on its turn
by applying the `withoutStrategies()` step with the `ReadOnlyStrategy`.
-
* The traversal strategies assume that they are only applied once: no exception is raised or warning is logged when you
try it nevertheless. As a result, the behavior in case of multiple application of the same traversal strategy is
unspecified. For some, like the <<partitionstrategy, PartitionStrategy>> the first instance prevails. For others, like
@@ -3824,6 +3824,7 @@ implicitly as a result of a `with()` step, is an exception in that it actually m
`with()` steps.
=== Definition
+
A simple `OptimizationStrategy` is the `IdentityRemovalStrategy`.
[source,java]
diff --git a/docs/src/upgrade/release-3.5.x.asciidoc b/docs/src/upgrade/release-3.5.x.asciidoc
index a1190d1..e2d67fc 100644
--- a/docs/src/upgrade/release-3.5.x.asciidoc
+++ b/docs/src/upgrade/release-3.5.x.asciidoc
@@ -59,7 +59,7 @@ with Gremlin so as to avoid confusion in examples, documentations and mailing li
As of 3.5.0, attempting to use a traversal spawned from a "source" will result in an exception. Users will need to
modify their code if they use the unconventional syntax.
-link:https://issues.apache.org/jira/browse/TINKERPOP-2361[TINKERPOP-2361]
+See: link:https://issues.apache.org/jira/browse/TINKERPOP-2361[TINKERPOP-2361]
==== GraphSON and JsonBuilder
@@ -343,11 +343,22 @@ return these types of results and not have to work around them:
See: link:https://issues.apache.org/jira/browse/TINKERPOP-2395[TINKERPOP-2395]
-==== Gremlin Server
+==== Gremlin Server Audit Logging
+
The `authentication.enableAuditlog` configuration property is deprecated, but replaced by the `enableAuditLog` property
to also make it available to `Authorizer` implementations. With the new setting enabled, there are slight changes in the
formatting of audit log messages. In particular, the name of the authenticated user is included in every message.
+==== Gremlin Server Authorization
+
+While Gremlin Server has long had authentication options to determine if a user can connect to the server, it now also
+contains the ability to apply a level of authorization to better control what a particular authenticated user will
+have access to. Authorization is controlled by the new `Authorizer` interface, which can be implemented by users and
+graph providers to provide this custom functionality.
+
+See: link:https://issues.apache.org/jira/browse/TINKERPOP-2389[TINKERPOP-2389],
+link:https://tinkerpop.apache.org/docs/3.5.0/reference/#authorization[Reference Documentation]
+
==== Python 2.x Support
The gremlinpython module no longer supports Python 2.x. Users must use Python 3 going forward. For the most part, from
@@ -489,6 +500,17 @@ link:https://tinkerpop.apache.org/docs/3.5.0/upgrade/#_ssl_security[3.2.10 Upgra
==== Graph System Providers
+===== Server Authorization
+
+Gremlin Server now supports an extension model that enables authorization. Graph providers are not required to
+implement this functionality in any way, but it can be helpful for those graphs that wish to provide this functionality
+through Gremlin Server. Graphs Systems may still choose to rely on their own native authorization functionality if
+they so choose.
+
+See: link:https://issues.apache.org/jira/browse/TINKERPOP-2389[TINKERPOP-2389],
+link:https://tinkerpop.apache.org/docs/3.5.0/reference/#authorization[Reference Documentation],
+link:https://tinkerpop.apache.org/docs/3.5.0/dev/provider/#_authentication_and_authorization[Provider Documentation]
+
===== ScalarMapStep
`MapStep` had a single abstract method that needed to be implemented: