Merge pull request #177 from arangodb-helper/feature/auth-header-token

Added authentication helpers

Author: ewoutp

auth.go

@@ -0,0 +1,97 @@
+//
+// DISCLAIMER
+//
+// Copyright 2018 ArangoDB GmbH, Cologne, Germany
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// Copyright holder is ArangoDB GmbH, Cologne, Germany
+//
+// Author Ewout Prangsma
+//
+
+package main
+
+import (
+	"fmt"
+	"io/ioutil"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	service "github.com/arangodb-helper/arangodb/service"
+)
+
+var (
+	cmdAuth = &cobra.Command{
+		Use:   "auth",
+		Short: "ArangoDB authentication helper commands",
+		Run:   cmdShowUsage,
+	}
+	cmdAuthHeader = &cobra.Command{
+		Use:   "header",
+		Short: "Create a full HTTP Authorization header for accessing an ArangoDB server",
+		Run:   cmdAuthHeaderRun,
+	}
+	cmdAuthToken = &cobra.Command{
+		Use:   "token",
+		Short: "Create a JWT authentication token for accessing an ArangoDB server",
+		Run:   cmdAuthTokenRun,
+	}
+	authOptions struct {
+		jwtSecretFile string
+		user          string
+	}
+)
+
+func init() {
+	cmdMain.AddCommand(cmdAuth)
+	cmdAuth.AddCommand(cmdAuthHeader)
+	cmdAuth.AddCommand(cmdAuthToken)
+
+	pf := cmdAuth.PersistentFlags()
+	pf.StringVar(&authOptions.jwtSecretFile, "auth.jwt-secret", "", "name of a plain text file containing a JWT secret used for server authentication")
+	pf.StringVar(&authOptions.user, "auth.user", "", "name of a user to authenticate as. If empty, 'super-user' authentication is used")
+}
+
+// mustAuthCreateJWTToken creates a the JWT token based on authentication options.
+// On error the process is exited with a non-zero exit code.
+func mustAuthCreateJWTToken() string {
+	authOptions.jwtSecretFile = mustExpand(authOptions.jwtSecretFile)
+
+	if authOptions.jwtSecretFile == "" {
+		log.Fatal().Msg("A JWT secret file is required. Set --auth.jwt-secret option.")
+	}
+	content, err := ioutil.ReadFile(authOptions.jwtSecretFile)
+	if err != nil {
+		log.Fatal().Err(err).Msgf("Failed to read JWT secret file '%s'", authOptions.jwtSecretFile)
+	}
+	jwtSecret := strings.TrimSpace(string(content))
+	token, err := service.CreateJwtToken(jwtSecret, authOptions.user)
+	if err != nil {
+		log.Fatal().Err(err).Msg("Failed to create JWT token")
+	}
+	return token
+}
+
+// cmdAuthHeaderRun prints a JWT authorization header on stdout and exits.
+func cmdAuthHeaderRun(cmd *cobra.Command, args []string) {
+	token := mustAuthCreateJWTToken()
+	fmt.Printf("%s: %s%s\n", service.AuthorizationHeader, service.BearerPrefix, token)
+}
+
+// cmdAuthTokenRun prints a JWT authorization token on stdout and exits.
+func cmdAuthTokenRun(cmd *cobra.Command, args []string) {
+	token := mustAuthCreateJWTToken()
+	fmt.Println(token)
+}

docs/Manual/Programs/Starter/Options.md

@@ -94,12 +94,15 @@ and pass it through the `--auth.jwt-secret-path` option.
 For example:
 
 ```bash
-echo "MakeThisSecretMuchStronger" > jwtSecret
+arangodb create jwt-secret --secret=jwtSecret
 arangodb --auth.jwt-secret=./jwtSecret
 ```
 
 All starters used in the cluster must have the same JWT secret.
 
+To use a JWT secret to access the database, use `arangodb auth header`.
+See [Using authentication tokens](./Security.md#using-authentication-tokens) for details.
+
 ## SSL options
 
 The arango starter by default creates a cluster that uses no unencrypted connections (no SSL).

docs/Manual/Programs/Starter/Security.md

@@ -99,3 +99,34 @@ arangodb create jwt-secret \
 ```
 
 Make sure to protect and store the generated file (`my-secret.jwt`) in a safe place.
+
+## Using authentication tokens
+
+ArangoDB deployments that require authentication can be accessed through standard user+password
+pairs or using a JWT to get "super-user" access.
+
+This super-user access is needed to communicate directly with the agency or with any server
+in the deployment.
+Note that uses super-user access for normal database access is NOT advised.
+
+To create a JWT from the JWT secret file specified using the `--auth.jwt-secret` option,
+use the following command:
+
+```bash
+arangodb auth token --auth.jwt-secret=<secret-file>
+```
+
+To create a complete HTTP Authorization header that can be passed directly to tools like `curl`,
+use the following command:
+
+```bash
+arangodb auth header --auth.jwt-secret=<secret-file>
+```
+
+Using `curl` with this command looks like this:
+
+```bash
+curl -v -H "$(arangodb auth header --auth.jwt-secret=<secret-file>)" http://<database-ip>:8529/_api/version
+```
+
+Note the double quotes around `$(...)`.

service/authentication.go

@@ -28,27 +28,50 @@ import (
 	jwt "github.com/dgrijalva/jwt-go"
 )
 
-// addJwtHeader calculates a JWT authorization header based on the given secret
-// and adds it to the given request.
-// If the secret is empty, nothing is done.
-func addJwtHeader(req *http.Request, jwtSecret string) error {
+const (
+	AuthorizationHeader = "Authorization"
+	BearerPrefix        = "bearer "
+)
+
+// CreateJwtToken calculates a JWT authorization token based on the given secret.
+// If the secret is empty, an empty token is returned.
+func CreateJwtToken(jwtSecret, user string) (string, error) {
 	if jwtSecret == "" {
-		return nil
+		return "", nil
 	}
 	// Create a new token object, specifying signing method and the claims
 	// you would like it to contain.
-	token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
+	claims := jwt.MapClaims{
 		"iss":       "arangodb",
 		"server_id": "foo",
-	})
+	}
+	if user != "" {
+		claims["preferred_username"] = user
+	}
+	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
 
 	// Sign and get the complete encoded token as a string using the secret
 	signedToken, err := token.SignedString([]byte(jwtSecret))
+	if err != nil {
+		return "", maskAny(err)
+	}
+
+	return signedToken, nil
+}
+
+// addJwtHeader calculates a JWT authorization header based on the given secret
+// and adds it to the given request.
+// If the secret is empty, nothing is done.
+func addJwtHeader(req *http.Request, jwtSecret string) error {
+	if jwtSecret == "" {
+		return nil
+	}
+	signedToken, err := CreateJwtToken(jwtSecret, "")
 	if err != nil {
 		return maskAny(err)
 	}
 
-	req.Header.Set("Authorization", "bearer "+signedToken)
+	req.Header.Set(AuthorizationHeader, BearerPrefix+signedToken)
 	return nil
 }
 
@@ -60,6 +83,6 @@ func addBearerTokenHeader(req *http.Request, bearerToken string) error {
 		return nil
 	}
 
-	req.Header.Set("Authorization", "bearer "+bearerToken)
+	req.Header.Set(AuthorizationHeader, BearerPrefix+bearerToken)
 	return nil
 }