oada-ref-auth

Table of Contents

• oada-ref-auth-js
  • Live Example
  • OADA Authorization and Authentication Specs
  • Installation Instructions
    • 1. Get the code
    • 2. Install the Dependences
    • 3. Generate/Install SSL Certificates
      • Reverse Proxy
      • Trusted CA SSL Certificate in node
      • Generating a Self-Signed Certificate
        • Generate a Certificate Authority Certificate (ca.crt)
        • Create a Server Private Key (server.key)
        • Create a Server Certificate (server.crt)
        • Save Private Key, CA Certificate, and Certificate
    • 4. Generate/Install JWT Signing Certificates
      • With OpenSSL
      • With OpenSSH
    • 5. Configure the Implementation
    • 6. Start it up
  • Adding New Database Abstraction Layer

oada-ref-auth-js

Live Example

A live example of this project can be found on https://provider.oada-dev.com and https://identity.oada-dev.com. A useful tool to interact with these is located at https://client.oada-dev.com.

The minimal examples from @OADA/oada-id-client-js project can also be easily be modified to interact with this server.

OADA Authorization and Authentication Specs

See specifications of OADA's Authentication and Authorization can be found here.

Installation Instructions

Installing the reference OADA authorization and authentication server is relatively easily. The basic process is: 1. Download the code, 2. Run npm install, 3. Generate SSL certificates, 4. Generate JWT signing certificates, 5. Edit config.js, 6. Start it. Below are more detailed instructions:

1. Get the code

The easiest way to get the code is directly with git from github.com:

$ git clone https://github.com/OADA/oada-ref-auth-js

2. Install the Dependences

$ cd oada-ref-auth-js
$ npm install

3. Generate/Install SSL Certificates

OADA requires that all Authorization and Authentication flows happen over SSL. There are three main options:

Reverse Proxy

Most reverse proxies can handle laying SSL on top of a standard HTTP session transparently. As a result the node only needs to support standard HTTP. Nginx is an example of such a reverse proxy option.

Trusted CA SSL Certificate in node

Node.js is capable of supporting SSL directly if provided a valid private key, certificate, and CA certificate. If you choose this option then those three files need to be sourced from a trusted CA of your choosing and stored in a secure location that is accessible by the node process. Configuring oada-ref-auth-js to locate the files are the subject of a later step.

Generating a Self-Signed Certificate

Self-signed certificates are not OADA compliant and will cause your user's user-agent to popup a warning. However, they are very useful when developing and testing. If you choose this method you need to generate a private key, certificate, and CA certificate using the below, or your preferred, method and store them in a secure location that is accessible by the node process. Configuring oada-ref-auth-js to locate the files are the subject of a later step.

The below directions are adapted from a greengeckodesign.com blog post.

Generate a Certificate Authority Certificate (ca.crt)

$ openssl genrsa -des3 -out ca.key 2048
$ openssl req -new -key ca.key -out ca.csr
$ openssl x509 -req -days 365 -in ca.csr -out ca.crt -signkey ca.key

Create a Server Private Key (server.key)

$ openssl genrsa -des3 -out server-passphrase.key 2048

Create a Server Certificate (server.crt)

$ openssl req -new -key server-passphrase.key -out server.csr
$ openssl rsa -in server-passphrase.key -out server.key
$ openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

Save Private Key, CA Certificate, and Certificate

$ cp server.key safe/and/secure/location
$ cp server.crt safe/and/secure/location
$ cp ca.crt safe/and/secure/location

4. Generate/Install JWT Signing Certificates

OpenID Connect and OADA's client secrets both use RSA signed JWTs and therefore oada-ref-auth-js requires at least one RSA private. The key, in PEM form, can be generated using the below instructions or any method of your choosing. Store these files in a secure location is is accessible by the node process. The keys files name will be used as the key's ID (kid). The kid is exposed publicly. Configuring oada-ref-auth-js to locate the files are the subject of a later step.

With OpenSSL

$ openssl genrsa -out <kid>.pem 2048
$ cp <kid>.pem safe/and/secure/location

With OpenSSH

$ ssh-keygen -t rsa -b 2048 -m PEM -f <kid>.pem
$ cp <kid>.pem safe/and/secure/location

5. Configure the Implementation

oada-ref-auth-js is configured by a single file config.js. It is recommended that you copy this file to some safe and secure location outside of the the repository so that upgrading oada-ref-auth-js is merely a mater doing a git pull.

Currently the configuration options are:

server:

Key	Example Value	Description
jsonSpaces	2	0 to uglify output JSON, otherwise, it is the number of spaces a tab should be represented with in pretty print mode. Applies to all output JSON
sessionSecret	Xka*32F@*!15	The secret used with the session hash table
passwordSalt	$2a$10$l64QftVz6.7KR5BXNc29IO	Salt for bcrypt when hashing passwords
port	443	The port in which the server should listen on
mode	http or https	If HTTP or HTTPS should be used (OADA compliance requires HTTPS)
domain	provider.example.com	The domain in which this server is running under
publicUri	https://provider.example.com:8443/oada	The full base URI in which the server is running under as seen by the outside world. This option is particularly useful for when this server is operating behind a reverse proxy or similar environment. If the desired publicUri is that of the one constructed by the above port, mode, and domain settings then this parameter can be omitted.

endpoints

Key	Example Value	Description
authorize	/auth	The desired path after root for the OAuth 2.0 authorization endpoint
token	/token	The desired path after root for the OAuth 2.0 token endpoint
decision	/decision	The desired path after root for the OAuth 2.0 "grant screen"
register	/register	The desired path after root for the OAuth 2.0
Dynamic Client Registartion
login	/login	The desired path after root for the OAuth 2.0 "login screen"
logout	/logout	The desired path after root to logout of the current session
certs	/certs	The desired path after root for the JWT RSA public keys
userinfo	/userinfo	The desired path after root for the OpenID Connect Userinfo endpoint

oauth2:

Key	Example Value	Description
enable	true	Enable the OAuth 2.0 portions of the reference implementation

oidc:

Key	Example Value	Description
enable	true	Enable the OpenID Connect portions of the reference implementation

code:

Key	Example Value	Description
length	25	The length of the random code in the OAuth 2.0 code flow
expiresIn	10	The length of time in seconds the the code in the OAuth 2.0 code flow is valid for

idToken:

Key	Example Value	Description
expiresIn	3600	The length of time in seconds the idToken for OpenID Connect is valid for
signKid	kjcScjc32dwJXXLJDs3r124sa1	The kid for the private key in with JWTs should be signed with

certs:

Key	Example Value	Description
key	fs.readFileSync(path.join(__dirname, 'certs/ssl/server.key'))	The PEM string for the server's SSL private key. Only needed when httpMode = false
cert	fs.readFileSync(path.join(__dirname, 'certs/ssl/server.crt'))	The PEM string for the server's SSL certificate. Only needed when httpMode = false
ca	fs.readFileSync(path.join(__dirname, 'certs/ssl/ca.crt'))	The PEM string for the CA's SSL certificate. Only needed when httpMode = false
requestCrt	true	A boolean indicating whether a server should request a certificate from a connecting client. Only applies to server connections.
rejectUnauthorized	false	A boolean indicating whether a server should automatically reject clients with invalid certificates. Only applies to servers with requestCert enabled.

keys:

Key	Example Value	Description
signPems	path.join(__dirname, 'certs/sign/')	The path to the JWT signing PEMs

mongo:

Key	Example Value	Description
connectionString	localhost/oada-ref-auth	The mongodb connection string. Only needed for mongodb is in use

datastores:

Key	Example Value	Description
users	./db/flat/users	The path to the database abstraction used to store users. Current options: ./db/flat/users (in-memory) or ./db/mongo/users (mongodb)
clients	./db/flat/clients	The path to the database abstraction used to store clients. Current options: ./db/flat/clients (in-memory) or ./db/mongo/clients (mongodb)
tokens	./db/flat/tokens	The path to the database abstraction used to store tokens. Current options: ./db/flat/tokens (in-memory) or ./db/mongo/tokens (mongodb)
codes	./db/flat/codes	The path to the database abstraction used to store users. Current options: ./db/flat/codes (in-memory) or ./db/mongo/codes (mongodb)

hint:

Key	Example Value	Description
username	frank	The "hint" for the username on the login screen. Used to for demonstration
password	pass	The "hint" for the password on the login screen. Used to for demonstration

6. Start it up

oada-ref-auth-js has a single optional parameter which is the path to the desired configuration file. If it is not given then it is assumed the config.js in the root of the oada-ref-auth-js repository is the desired configuration file.

$ node index.js path/to/config.js

or

$ node index.js

Adding New Database Abstraction Layer

New database abstraction layers can be easily added to the project. The easiest way is to copy ./db/flat or ./db/mongo to ./db/<new-layers-name> and then edit the clients.js, users.js, codes.js and tokens.js files to use the new database.

Here is a table of functions should be edited for each file:

File	Functions Name
clients.js	findById
users.js	findById, findByUsernamePassword
codes.js	findByCode, save
tokens.js	findByToken, save

The datastores section of the configuration file needs to be updated to use the new abstraction layer.