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:

endpoints

oauth2:

oidc:

code:

idToken:

certs:

keys:

mongo:

datastores:

hint:

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:

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