IDENTITY PLUGIN V4

This plugin includes 3 parts:

1. Grunttask
2. Openrecord Plugin
3. Actionhero Plugin

The grunttask is for synchronising roles, role_entiteies and values. Values will be synchronized automatically if your define it in your openrecord model. (see: OpenRecord Plugin/Value Sync). The OpenRecord plugin enhances your model definition to also support permissions. Permissions will be applied to find, create, update and destroy. The actionhero plugin handles the OAuth2 handshake, user and sessions management, communication with other identity apps ans some more.

Config

after installing identity your config folder should contain a identity.js config file. Every identity client has an id and secret to authenticate the application. Additionally every application has multiple roles, entities and values. An identity user can have multiple roles and every role could have multiple entities attached to it.

E.g. you have an issue tracking application. There are multiple projects and you'd like to grant User X only access to certain projects. Project is the entity and every project in your application is a value.

      entities:{
        project:{
          name: 'Project',
          model: 'Project' //Define your OpenRecord model here to automatically sync all values
        }
      }

To attach Project A and B to User X, create a role "User" first and attach the entity Project to it

      roles: {      
        user:{
          name: 'User',
          entities: [{
            id: 'project',
            allow_multiple: true,
            allow_blank: false
          }]
        }
      }

Now you could grant User X permissions to Project A and B via the admin web interface of identity.

• be sure to enable the plugin within actionhero (config/api.js)
• you will need to add the identity package (npm install identity --save) to your package.json

Grunttask:

Roles Sync

`identity:sync`

Complete Value Resync

`identity:values:resync`

Helper

grunt.login(callback) gives you a login prompt + starts the actionhero server.

var done = this.async()
grunt.login(function(api, access_token, user){
  if(!access_token){
    return done(false);
  }
});

OpenRecord Plugin:

Model Permissions

    this.permission({
        role_name: true/false //global allow/deny
        role_name: {
            find: true/false, //allow/deny a specific operation
            find: function(){
                //in the permission scope
            },
            create: function(){
                return true/false //with custom funciton... only for create, update, destroy, modify
            }
                
            fields: {
                all : true/false //globall allow/deny
                field_name: true/false //allow/deny a specific field
                field_name: 'find' //allow only find
                field_name: ['find', 'create'] //allow find and create,
                field_name: function(){return true/false} //with custom function
            }
        }
    })

Value Sync

    this.identityValue('entity_name', function(){ //optional function to control which records should be synced
        return true/false (record scope)
    }); //in definition

Actionhero Plugin

OAuth

/api/oauth

User/Session management

/api/login, /api/logout, /api/profile, /api/user actions

Add user to connection

connection.user and connection.session

Session handling

connection.session is a object which will be saved into the actionhero cache.

Action Permissions

requireAuth: true/false, requireRole: 'admin' / ['admin', 'lead']

Identity proxy

the whole identity server is available via http://yourapp.com/api/identity/*. e.g. http://yourapp.com/api/identity/users and will only return values which belongs to the application

App comunication

api.identity.application('application_name'.get('action', {param:'value}, callback) api.identity.application('application_name'.post('action', {param:'value}, callback) api.identity.application('application_name'.put('action', {param:'value}, callback) api.identity.application('application_name'.delete('action', {param:'value}, callback)

SpecHelper

Global object test has the following methods: test.action(name[, params, connectionParams], callback) test.loginAs(username).action(name, params, callback) test.insufficientPermissions(callback)

e.g. to test for insufficient permissions:

  it('"projects:destroy" should fail', function(done){    
    test.loginAs('user').action('projects:destroy', {id: 1}, test.insufficientPermissions(done));
  });