Skip to content

Commit e9f3be9

Browse files
rsill-neo4jrsill-neo4j
authored
Merge pull request #168 from neo4j/updates-for-security-section
Updates for the security section
2 parents 95bb90b + 4a408be commit e9f3be9

File tree

7 files changed

+198
-127
lines changed

7 files changed

+198
-127
lines changed

‎modules/ROOT/pages/directives/index.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,10 +40,10 @@ a| Required to differentiate interfaces that are used for relationship propertie
4040
| xref::/security/authorization.adoc[`@authorization`]
4141
| Specifies authorization rules for queries and mutations on the type.
4242

43-
| xref::/security/configuration.adoc#authentication-and-authorization-jwt[`@jwt`]
43+
| xref::/security/configuration.adoc#_the_jwt_directive[`@jwt`]
4444
| Configures the JWT authentication and authorization filters to include additional JWT claims.
4545

46-
| xref::/security/configuration.adoc#_nested_claims[`@jwtClaim`]
46+
| xref::/security/configuration.adoc#_the_jwtclaim_directive[`@jwtClaim`]
4747
| Used in combination with `@jwt`.
4848
Configures the JWT authentication and authorization filters to include an additional JWT claim which is either nested or using special characters not supported by GraphQL.
4949

‎modules/ROOT/pages/security/authentication.adoc

Lines changed: 67 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,67 @@
11
= Authentication
22
:description: This page describes how to set up authentication features in the Neo4j GraphQL Library.
33

4-
Explicit authentication, configured using the `@authentication` directive, is only ever evaluated
5-
during Cypher translation time, and unauthenticated requests with queries requiring authentication
6-
will never reach the database.
4+
The GraphQL Library offers the `@authentication` directive to configure authentication for certain operations and for different parts of your schema.
75

8-
== Configuration
6+
[IMPORTANT]
7+
====
8+
Explicit authentication, configured with the `@authentication` directive, is only ever evaluated during Cypher translation time.
9+
Unauthenticated requests with queries requiring authentication never reach the database.
10+
====
911

10-
Authentication can be configured for an entire type, for example, the type `User`:
12+
== Operations
13+
14+
Authentication can be configured to only be validated on certain operations:
15+
16+
* `CREATE`
17+
* `READ`
18+
* `AGGREGATE`
19+
* `UPDATE`
20+
* `DELETE`
21+
* `CREATE_RELATIONSHIP`
22+
* `DELETE_RELATIONSHIP`
23+
* `SUBSCRIBE`
24+
25+
For instance, to only require authentication for the update or deletion of a user:
26+
27+
[source, graphql, indent=0]
28+
----
29+
type User @authentication(operations: [UPDATE, DELETE]) {
30+
id: ID!
31+
name: String!
32+
password: String!
33+
}
34+
----
35+
36+
[NOTE]
37+
====
38+
In case there is no `operations` argument with a list of operations, the GraphQL Library treats the authentication configuration as if the full list of operations had been provided.
39+
====
40+
41+
== Scope
42+
43+
=== Global authentication
44+
45+
Authentication can be applied to the entire schema.
46+
This ensures authentication is checked for every matching request.
47+
48+
Extend the schema:
49+
50+
[source, graphql, indent=0]
51+
----
52+
extend schema @authentication
53+
----
54+
55+
The `operations` and `jwt` arguments can also be used when the directive is applied to a schema extension, for example:
56+
57+
[source, graphql, indent=0]
58+
----
59+
extend schema @authentication(operations: [UPDATE, DELETE], jwt: { roles_INCLUDES: "admin" })
60+
----
61+
62+
=== Authentication for types
63+
64+
Authentication can be configured for an entire type:
1165

1266
[source, graphql, indent=0]
1367
----
@@ -18,7 +72,7 @@ type User @authentication {
1872
}
1973
----
2074

21-
Authentication will thus be validated when any of the following operations are _attempted_:
75+
With this configuration, authentication is validated when any of the following operations are _attempted_:
2276

2377
* *Create*: `createUsers` mutation, `create`, or `connectOrCreate` nested operation via a related type.
2478
* *Read*: `users`, `usersConnection`, `usersAggregate` query, or access via related type.
@@ -28,7 +82,10 @@ Authentication will thus be validated when any of the following operations are _
2882
* *Delete relationship*: `disconnect` nested operation via a related type.
2983
* *Subscribe*: all subscription operations related to type `User`.
3084

31-
Additionally, the directive can be configured on a per-field basis, for example:
85+
86+
=== Authentication for fields
87+
88+
Authentication can be configured on a per-field basis, for example:
3289

3390
[source, graphql, indent=0]
3491
----
@@ -39,37 +96,13 @@ type User {
3996
}
4097
----
4198

42-
This will only be evaluated in the following circumstances:
99+
This is only evaluated under the following circumstances:
43100

44101
* The `password` field is set on either `create` or `update`.
45102
* The `password` field is present in a selection set.
46103

47-
=== Operations
48-
49-
Authentication can be configured to only be validated on certain operations:
50-
51-
* `CREATE`
52-
* `READ`
53-
* `AGGREGATE`
54-
* `UPDATE`
55-
* `DELETE`
56-
* `CREATE_RELATIONSHIP`
57-
* `DELETE_RELATIONSHIP`
58-
* `SUBSCRIBE`
59-
60-
61-
For instance, to only require authentication for the update or deletion of a user:
62-
63-
[source, graphql, indent=0]
64-
----
65-
type User @authentication(operations: [UPDATE, DELETE]) {
66-
id: ID!
67-
name: String!
68-
password: String!
69-
}
70-
----
71104

72-
=== Additional verification
105+
== Additional verification
73106

74107
Additional checks against JWT claims can be performed together with authentication.
75108
For instance, if it was a requirement that only users with the `admin` role can delete users:
@@ -81,18 +114,4 @@ type User @authentication(operations: [DELETE], jwt: { roles_INCLUDES: "admin" }
81114
name: String!
82115
password: String!
83116
}
84-
----
85-
86-
== Global authentication
87-
88-
Additionally, authentication can be applied to the entire schema.
89-
This ensures authentication is checked for every matching request.
90-
91-
This is done via extending the schema:
92-
93-
[source, graphql, indent=0]
94-
----
95-
extend schema @authentication
96-
----
97-
98-
The `operations` and `jwt` arguments can also be used when the directive is applied to a schema extension.
117+
----

‎modules/ROOT/pages/security/authorization.adoc

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,11 @@ type Post @authorization(filter: [
6666
}
6767
----
6868

69+
[NOTE]
70+
====
71+
In case there is no `operations` argument with a list of operations, the GraphQL Library treats the authorization configuration as if the full list of operations had been provided.
72+
====
73+
6974

7075
=== Validating
7176

@@ -115,6 +120,11 @@ type Post @authorization(validate: [
115120
}
116121
----
117122

123+
[NOTE]
124+
====
125+
In case there is no `operations` argument with a list of operations, the GraphQL Library treats the authorization configuration as if the full list of operations had been provided.
126+
====
127+
118128

119129
== Authorization without authentication
120130

0 commit comments

Comments
 (0)