@koopjs/auth-direct-file

Koop-Auth-Direct-File

A authentication module for implementing direct authentication from client to Koop server with a file-based user-store

Authentication pattern

The authentication module implemented here uses a direct authentication pattern; it receives user credentials (username/password) from a client and authenticates those credentials against an identity/user-store. Requests with valid credentials are issued an access-token (a string of encoded-data); The access token is encoded with the use of a secret known only to the Koop server. The access-token expires and becomes invalid after a certain period (default of 60 minutes).

The issued access-token should be attached to all subsequent service requests by the client. When the server receives a request, it will check for the presence of an access-token and reject any requests that are missing such token. If the token is present, the server attempts to decode it with its stored secret. Failure to decode results in a request rejection. Once decoded, the server checks the token's expiration-date and rejects any token with a date that is out of range. If the token is not expired, the request for the desired resource proceeds.

Example of Koop authentication implementation

The server.js file provides an example of securing a provider's resources. Start by requiring the authentication module. Pass it a secret and the file path of your user-store.

let auth = require('@koopjs/auth-direct-file')('pass-in-your-secret', `${__dirname}/user-store.json`)
koop.register(auth)

Then require and register your providers.

const provider = require('./')
koop.register(provider)

The authentication module will configure and add its authorize, authenticate, and authenticationSpecification functions to the provider's model prototype. Output services will leverage these functions to secure the service endpoints and properly route requests to authenticate.

Finally, create a JSON file store. This should be an array of objects with properties username and password. Set an environment variable USER_STORE with the path of the file relative to the root of the repository (e.g, USER_STORE=./user-store.json)

Authentication API

(secret, options) ⇒ Object

• configure the authentication module with secret use for token encoding/decoding

Param	Type	Description
secret	string	secret for encoding/decoding tokens
userStoreFilePath	string	path to the JSON file containing the array of username/password objects
options	object	options object
options.tokenExpirationMinutes	integer	minutes until token expires (default 60)
options.useHttp	boolean	pass the useHttp boolean flag as part of the authenticationSpecification function result

Special considerations for use with koop-output-geoservices

koop-output-geoservices assumes that token-services occur over HTTPS. For development purposes you may wish to allow authentication to occur of HTTP. This can be done two different ways. You can add the useHttp option when configuring the module, which will be passed on in the result of authenticationSpecification() calls.

let auth = require('@koopjs/auth-direct-file')('pass-in-your-secret', `${__dirname}/user-store.json`, { useHttp: true })
koop.register(auth)

Alternatively, you can set an environment variable KOOP_AUTH_HTTP=true. Either of these approaches inform koop-output-geoservices to use http as the protocol of the tokenServicesUrl.

Notes on use with ArcGIS Online and ArcGIS Portal

This authorization plugin has been tested with ArcGIS Online and ArcGIS Portal. For versions of Portal earlier than 10.6, you may need to import the root of your certificate into Portal's trust store. We have observed the inability to store credentials for a secured Koop service on Portal instances that have not yet imported the root SSL certificate (of the Koop instance) into the trust-store.

How to setup an app: Step by step guide

On this guide we will show you how to setup a new app with a secured provider. We will be using Koop-CLI.

# Install Koop-CLI if needed
npm install -g @koopjs/cli

# Create a new Koop app
koop new app demo-app
cd demo-app

# Add this Auth plugin
koop add provider @koopjs/auth-direct-file

# Create a file with all valid credentials
echo \[\\n\\t{ \"username\": \"admin\", \"password\": \"admin\" }\\n\] > src/user-store.json

# Open src/plugins.js and replace:
# This line: const authDirectFile = require('@koopjs/auth-direct-file')
# For this line: const authDirectFile = require('@koopjs/auth-direct-file')('123456', `${__dirname}/user-store.json`, { useHttp: true });

# Install any provider
koop add provider koop-provider-carto

# Run the koop server
koop serve

# Try to access server (it will fail <- require an access token)
http://localhost:8080/koop-provider-carto/rest/services/common-data/twitter_t3chfest_reduced/FeatureServer/0

# Generate token using any of the credentials you placed at src/user-store.json
http://localhost:8080/koop-provider-carto/tokens?username=rich&password=rich

# Now retry to access service but adding the generated token
http://localhost:8080/koop-provider-carto/rest/services/common-data/twitter_t3chfest_reduced/FeatureServer/0?token=GENERATED_TOKEN

# That's it! you are done!