Skip to content

Latest commit

 

History

History
187 lines (132 loc) · 5.63 KB

README.md

File metadata and controls

187 lines (132 loc) · 5.63 KB
Raw

Identity Atheneum

Build Status Coverage Status Slack

Easy to use data storage and authorization service for developers.

Full documentation can be found here,

Installation

System Requirements

  • UNIX based operating system (Linux/macOS)
  • Redis 2/3/4 (cannot be password protected)
  • MongoDB 3.6+ (cannot be passsword protected)
  • Node.js 8.x

Install Dependencies

First clone the repository and install all dependencies.

# clone the repository
git clone https://github.com/junthehacker/Identity-Atheneum.git
# cd into the repo
cd Identity-Atheneum
# install node dependencies
npm install

Build

We must run a build script before we can actually run the service.

npm run flow:build

Above command will build everything within /src and output into /lib.

Configuration

Before running the service, you must have a valid configuration file, located at /config.yml.

  • port: Port you wish to run the service on.
  • host_root: The root URL of the service, for example: https://sample.com (do not include trailing /).
  • app_secret: A random string, used to encrypt sessions.
  • redis:
    • host: Redis server host
    • port: Redis server port
  • mongo:
    • url: MongoDB connection url, for example mongodb://localhost/27017/ia (make sure you include the db name)
  • master_key: A random password, used for administrative access.
  • identity_providers: A list of IdP configurations, please see IdP Configurations for more detail.

Run

To run the service, use the following command

node ./lib

You should see something similar to the following

Local IdP local_provider initialized.
/idps/local_provider mounted.
SAML IdP testshib initialized.
/idps/testshib mounted.

========================================
 ___      ________         
|\  \    |\   __  \        
\ \  \   \ \  \|\  \       
 \ \  \   \ \   __  \      
  \ \  \ __\ \  \ \  \ ___    Build 1
   \ \__\\__\ \__\ \__\\__\   1.0
    \|__\|__|\|__|\|__\|__|   Dandelion

Congratulations! The service is running.

IdP Configurations

You must have a list of IdPs to make the service useful, there are a few to choose from.

Local

A local identity provider, it stores username and password within MongoDB.

You can only have one local identity provider.

Sample Configuration

identity_providers:
  # ...
  - type: local
    name: local_provider
    display_name: Local Identity Provider
  • type: Should always be local
  • name: Unique name for IdP, this is used to generate login URLs.
  • display_name: Name shown on main login page.

SAML 2.0

SAML 2.0 IdP, if you are using Shibboleth, use this one.

To configure SAML IdP, you must have a key/certificate pair, you can use the following command to generate a pair:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout mykey.key -out certificate.crt

Sample Configuration

identity_providers:
  # ...
  - type: saml
    name: testshib
    display_name: TestShib
    config:
      callback_url: http://localhost:3000/idps/testshib/login
      entry_point: https://idp.testshib.org/idp/profile/SAML2/Redirect/SSO
      identifier_format: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
      issuer: my_issuer
      public_cert: keys/certificate.crt
      private_key: keys/mykey.key
      signature_algo: sha256
  • type: Should always be saml
  • name: Unique name for IdP, this is used to generate login URLs.
  • display_name: Name shown on main login page.
  • config:
    • callback_url: This should always be <host_root>/idps/<name>/login
    • entry_point: SAML 2.0 entry URL
    • identifier_format: User identifier format, make sure your IdP support the format you chose. If not sure, use unspecified.
    • issuer: Just a name, you can use anything you like
    • public_cert: Path to your public certificate
    • private_key: Path to your private key
    • signature_algo: What algorithm to use when signing requests.

SAML MetaData

It is useful to have a xml metadata file when registering with your IdP. To obtain this file, first make sure you have everything configured, then run the service and go to following URL.

<host_root>/idps/<name>/metadata

CLI

I.A. comes with a command line tool. You can find it under /cli directory.

It is a Node.js app, you can run it by first npm install, then node index.js.

Integration

I have a I.A. development instance setup on my personal server, the location is: https://ia.junthehacker.com

Register Your App

Before you start developing, you must register your application.

Obtain a Developer Account

Login to Developer Dashboard

Create New Registration

  • Click Create New Registration to create a new app.
  • Give your app a name, can be anything.
  • Assertion Endpoint is the url we will send the bearer token to, for example https://myapp.com/ia/login.