Documentation

Install

$ npm install -g anvil-connect

Generate a Deployment Repository

Run the following command in an empty directory.

$ nv init

This will create a deployment repository that looks something like this:

├── .git
├── .gitignore
├── .modulusignore
├── config.development.json
├── config.production.json
├── keys
│   ├── private.pem
│   └── public.pem
├── package.json
├── public
├── server.js
└── views
    ├── authorize.jade
    ├── signin.jade
    └── signup.jade

Anvil Connect aims to be easily customizable. Using a deployment repository allows you to serve your own static assets, customize views (HTML templates), manage dependencies and keep your configuration under version control.

Install Dependencies

$ npm install

Initialize Database

Edit the config file for the environment you're preparing (development or production). To initialize your development database, run:

$ nv migrate

To initialize a production database, run:

$ NODE_ENV=production nv migrate

This will create default clients, roles, scopes and permissions necessary to operate the authorization server.

Default Clients

Default Roles

Default Scopes

Create an admin user

The CLI will prompt you for your name, email and password. If you have an accessible .gitconfig file, default values with be provided. Just enter a new password and you'll be in business.

$ nv signup

[?] Enter your full name: Christian Smith
[?] Enter your email: smith@anvil.io
[?] Create a new password: **********

{ name: 'Christian Smith',
  email: 'smith@anvil.io',
  _id: '7560e558-d6fa-45c9-ad88-37f11777aac5',
  created: 1402546195408,
  modified: 1402546195408 }

To assign the authority role to your new user, run:

$ nv assign smith@anvil.io authority

Run Anvil Connect

Run the authorization server in development mode:

# Any of the following are equivalent
$ nv serve
$ node server.js
$ npm start

To run the server in production, set NODE_ENV:

# Any of the following are equivalent
$ nv serve --production
$ node server.js -e production
$ NODE_ENV=production node server.js

Configure

• Config Files
• Initialize Database
• Client Registration Settings
• User Roles and Scope
• Assigning User Roles
• Logging

Customize

CLI

The nv command aims to provide control over every aspect of your server. You can use it by installing Anvil Connect globally via npm:

# Install CLI
$ npm install -g anvil-connect

Once you've generated a deployment repository and initialized a database for your environment, the following commands are useful for operating the server.

# View Configured OpenID Provider Metadata
$ nv config

# CRUD for users, clients, roles, and scopes               
$ nv ls <user|client|role|scope>
$ nv get <user|client|role|scope> <_id|email>
$ nv add <user|client|role|scope> <json>
$ nv update <user|client|role|scope> <_id|email> <json>
$ nv rm <user|client|role|scope> <_id|email>

# RBAC management
$ nv assign <email> <role>
$ nv revoke <email> <role>
$ nv permit <role> <scope>
$ nv forbid <role> <scope>

# Copy authorization URI for a registered client to the clipboard
# (for developer convenience)
$ nv uri

HTTP API

• Discovery
• Dynamic Client Registration
• Authentication and Authorization
  • Authorization Code Flow
  • Implicit Flow
  • Hybrid Flow
  • Refreshing Tokens
• UserInfo
• Access Token Verification

Client Libraries

Hypothetically, any compliant OpenID Connect client library should work with Anvil Connect. If you can't find one for your language or framework, you can fall back on the HTTP API. Over time we would like to provide official client libraries for as many environments as possible. If you've verified or written a library and want to see it listed here, please email smith at anvil dot io.

Officially supported libraries

• JavaScript
  • AngularJS | ^Example
  • Node.js | ^Example

Interoperable libraries

• JavaScript
  • Passport | ^Example

Contribute

• Developing