docs: auth (#227)

* docs: auth

On-behalf-of: @SAP a.shcherbatiuk@sap.com
Signed-off-by: Artem Shcherbatiuk <vertex451@gmail.com>
---------

Signed-off-by: Artem Shcherbatiuk <vertex451@gmail.com>

Author: vertex451

README.md

@@ -13,6 +13,10 @@ This repository contains two main components:
 - [Listener](./docs/listener.md): watches a cluster and stores its openAPI spec in a directory.
 - [Gateway](./docs/gateway.md): exposes the openAPI spec as a GraphQL endpoints.
 
+## Authorization
+
+All information about authorization can be found in the [authorization](./docs/authorization.md) section.
+
 ## Quickstart
 
 If you want to get started quickly, you can follow the [quickstart guide](./docs/quickstart.md).

cmd/root.go

@@ -51,7 +51,7 @@ func initConfig() {
 	v.SetDefault("openapi-definitions-path", "./bin/definitions")
 	v.SetDefault("enable-kcp", true)
 	v.SetDefault("local-development", false)
-	v.SetDefault("authenticate-schema-requests", false)
+	v.SetDefault("introspection-authentication", false)
 
 	// Listener
 	v.SetDefault("listener-apiexport-workspace", ":root")

common/config/config.go

@@ -1,10 +1,10 @@
 package config
 
 type Config struct {
-	OpenApiDefinitionsPath     string `mapstructure:"openapi-definitions-path"`
-	EnableKcp                  bool   `mapstructure:"enable-kcp"`
-	LocalDevelopment           bool   `mapstructure:"local-development"`
-	AuthenticateSchemaRequests bool   `mapstructure:"authenticate-schema-requests"`
+	OpenApiDefinitionsPath      string `mapstructure:"openapi-definitions-path"`
+	EnableKcp                   bool   `mapstructure:"enable-kcp"`
+	LocalDevelopment            bool   `mapstructure:"local-development"`
+	IntrospectionAuthentication bool   `mapstructure:"introspection-authentication"`
 
 	Listener struct {
 		// Listener fields will be added here

docs/authorization.md

@@ -0,0 +1,34 @@
+# Authorization
+
+All requests must contain an `Authorization` header with a valid Bearer token by default:
+```shell
+{
+    "Authorization": $YOUR_TOKEN
+}
+```
+You can disable authorization by setting the following environment variable:
+```shell
+export LOCAL_DEVELOPMENT=true
+```
+This is useful for local development and testing purposes.
+
+## Introspection authentication
+
+By default, introspection requests (i.e. the requests that are made to fetch the GraphQL schema) are **not** protected by authorization.
+
+You can protect those requests by setting the following environment variable:
+```shell
+export INTROSPECTION_AUTHENTICATION=true
+```
+
+### Error fetching schema
+
+When GraphiQL page is loaded, it makes a request to fetch the GraphQL schema and there is no way to add the `Authorization` header to that request.
+
+We have this [issue](https://github.com/openmfp/kubernetes-graphql-gateway/issues/217) open to fix this.
+
+But for now, you can use the following workaround:
+1. Open the GraphiQL page in your browser.
+2. Add the `Authorization` header in the `Headers` section of the GraphiQL user interface like so:
+3. Press `Re-fetch GraphQL schema` button in the left sidebar(third button from the top).
+4. Now the GraphQL schema should be fetched, and you can use the GraphiQL interface as usual.

docs/quickstart.md

@@ -24,6 +24,8 @@ export ENABLE_KCP=false
 # you must point to the config of the cluster you want to run against
 export KUBECONFIG=YOUR_KUBECONFIG_PATH
 ```
+
+
 ## Running the Listener
 
 Make sure you have done steps from the [setup section](#setup-the-environment).

gateway/manager/handler.go

@@ -136,7 +136,7 @@ func (s *Service) handleAuth(w http.ResponseWriter, r *http.Request, token strin
 			return false
 		}
 
-		if s.AppCfg.AuthenticateSchemaRequests {
+		if s.AppCfg.IntrospectionAuthentication {
 			if s.isIntrospectionQuery(r) {
 				ok, err := s.validateToken(r.Context(), token)
 				if err != nil {

tests/gateway_test/suite_test.go

@@ -93,7 +93,7 @@ func (suite *CommonTestSuite) SetupTest() {
 
 	suite.appCfg.LocalDevelopment = suite.LocalDevelopment
 	suite.appCfg.Gateway.Cors.Enabled = true
-	suite.appCfg.AuthenticateSchemaRequests = suite.AuthenticateSchemaRequests
+	suite.appCfg.IntrospectionAuthentication = suite.AuthenticateSchemaRequests
 
 	suite.log, err = logger.New(logger.DefaultConfig())
 	require.NoError(suite.T(), err)