authorify/doc/output/node_modules.authorify.authorization.js

Authorization and authentication system for REST server

Ext.data.JsonP.node_modules_authorify_authorization({"mixedInto":[],"subclasses":[],"requires":[],"parentMixins":[],"author":[{"tagname":"author","name":"Marcello Gesmundo","email":null}],"autodetected":{},"uses":[],"superclasses":[],"alternateClassNames":[],"mixins":[],"members":[{"owner":"node_modules.authorify.authorization","tagname":"method","meta":{},"name":"isInRole","id":"method-isInRole"},{"owner":"node_modules.authorify.authorization","tagname":"method","meta":{},"name":"isLoggedIn","id":"method-isLoggedIn"},{"owner":"node_modules.authorify.authorization","tagname":"method","meta":{},"name":"isSelf","id":"method-isSelf"},{"owner":"node_modules.authorify.authorization","tagname":"method","meta":{},"name":"isSelfOrInRole","id":"method-isSelfOrInRole"}],"tagname":"class","short_doc":"The authorization middleware. ...","meta":{},"name":"node_modules.authorify.authorization","component":false,"id":"class-node_modules.authorify.authorization","html":"<div><pre class=\"hierarchy\"><h4>Files</h4><div class='dependency'><a href='source/authorization.html#node_modules-authorify-authorization' target='_blank'>authorization.js</a></div></pre><div class='doc-contents'><p>The authorization middleware.</p>\n\n<h2>Example</h2>\n\n<pre><code> // dependencies\n var restify = require('restify');\n     authorify = require('authorify')(){\n       // add your options\n     },\n     sec = authorify.authorization;\n\n // create the server\n server = restify.createServer();\n\n // add all middlewares\n server.use(restify.queryParser({ mapParams: false }));\n server.use(restify.bodyParser());\n server.use(authorify.authentication);\n\n // define default handler\n server.get('/secure/roletest', sec.isSelfOrInRole(['user', 'guest']), function(err, res) {\n   console.log('ok');\n });\n\n // add your routes\n // ...\n\n // start the server\n server.listen(3000);\n</code></pre>\n\n<h1>License</h1>\n\n<p>Copyright (c) 2012-2014 Yoovant by Marcello Gesmundo. All rights reserved.</p>\n\n<p>This program is released under a GNU Affero General Public License version 3 or above, which in summary means:</p>\n\n<ul>\n<li>You <strong>can use</strong> this program for <strong>no cost</strong>.</li>\n<li>You <strong>can use</strong> this program for <strong>both personal and commercial reasons</strong>.</li>\n<li>You <strong>do not have to share your own program's code</strong> which uses this program.</li>\n<li>You <strong>have to share modifications</strong> (e.g bug-fixes) you've made to this program.</li>\n</ul>\n\n\n<p>For more convoluted language, see the LICENSE file.</p>\n</div><div class='members'><div class='members-section'><div class='definedBy'>Defined By</div><h3 class='members-title icon-method'>Methods</h3><div class='subsection'><div id='method-isInRole' class='member first-child not-inherited'><a href='#' class='side expandable'><span>&nbsp;</span></a><div class='title'><div class='meta'><span class='defined-in' rel='node_modules.authorify.authorization'>node_modules.authorify.authorization</span><br/><a href='source/authorization.html#node_modules-authorify-authorization-method-isInRole' target='_blank' class='view-source'>view source</a></div><a href='#!/api/node_modules.authorify.authorization-method-isInRole' class='name expandable'>isInRole</a>( <span class='pre'>roles, [conditions], [opts]</span> ) : String<span class=\"signature\"></span></div><div class='description'><div class='short'>Check if the current user belongs at least one of the role/roles specified. ...</div><div class='long'><p>Check if the current user belongs at least one of the role/roles specified. See more example about conditions\nand options in <a href=\"#!/api/node_modules.authorify.authorization-method-isLoggedIn\" rel=\"node_modules.authorify.authorization-method-isLoggedIn\" class=\"docClass\">isLoggedIn</a> handler.</p>\n\n<h2>Example</h2>\n\n<pre><code> server.get('/secure/roletest1', sec.isInRole('admin'), ok);\n server.get('/secure/roletest2', sec.isInRole(['user', 'guest']), ok);\n</code></pre>\n<h3 class=\"pa\">Parameters</h3><ul><li><span class='pre'>roles</span> : String/Array<div class='sub-desc'><p>A string or an array with one or more roles (at least one) to which\nthe current user should belong to</p>\n</div></li><li><span class='pre'>conditions</span> : String (optional)<div class='sub-desc'><p>A string with a test that will be executed before to check next condition</p>\n</div></li><li><span class='pre'>opts</span> : Object (optional)<div class='sub-desc'><p>Options to customize the behavior of the test</p>\n<ul><li><span class='pre'>nextOnError</span> : Boolean (optional)<div class='sub-desc'><p>When true and the test trows an error, it execute next()</p>\n<p>Defaults to: <code>false</code></p></div></li><li><span class='pre'>forbiddenOnFail</span> : Boolean (optional)<div class='sub-desc'><p>When true and the test fails (without error), it sends a 403 error</p>\n<p>Defaults to: <code>false</code></p></div></li></ul></div></li></ul><h3 class='pa'>Returns</h3><ul><li><span class='pre'>String</span><div class='sub-desc'><p>The result of the logged test.</p>\n\n<p>Values:</p>\n\n<ul>\n<li>'ok': if the authorization test are successful evaluated</li>\n<li>'ko': if the authorization test fails</li>\n<li>'specific error': a string with a detail about the error occurred in conditions evaluation (e.g.: missing param)</li>\n</ul>\n\n</div></li></ul></div></div></div><div id='method-isLoggedIn' class='member  not-inherited'><a href='#' class='side expandable'><span>&nbsp;</span></a><div class='title'><div class='meta'><span class='defined-in' rel='node_modules.authorify.authorization'>node_modules.authorify.authorization</span><br/><a href='source/authorization.html#node_modules-authorify-authorization-method-isLoggedIn' target='_blank' class='view-source'>view source</a></div><a href='#!/api/node_modules.authorify.authorization-method-isLoggedIn' class='name expandable'>isLoggedIn</a>( <span class='pre'>[conditions], [opts]</span> ) : String<span class=\"signature\"></span></div><div class='description'><div class='short'>Check if the user is logged in. ...</div><div class='long'><p>Check if the user is logged in.</p>\n\n<h2>Example</h2>\n\n<p>Create a server to use in every following example.</p>\n\n<pre><code>   // dependencies\n   var fs = require('fs'),\n       path = require('path'),\n       restify = require('restify'),\n       authorify = require('authorify')({\n         // add your config options\n       });\n   // create the server\n   server = restify.createServer();\n   // add middlewares\n   server.use(restify.queryParser({ mapParams: false }));\n   server.use(restify.bodyParser());\n   server.use(authorify.authentication);\n   // define handlers\n   var ok = function(req, res, next){\n     // define your response\n     res.send({ success: true, message: 'ok' });\n   };\n   var sec = authorify.authorization;\n</code></pre>\n\n<h2>Example 1</h2>\n\n<pre><code> server.get('/secure/loggedtest',\n           sec.isLoggedIn('param == 1'),\n           next);\n\n request|param == 1 |logged|response\n -------|-----------|------|--------\n GET    |true       |true  |next()\n GET    |true       |false |401\n GET    |false      |true  |next()\n GET    |false      |false |next()\n GET    |missing opt|true  |403\n GET    |missing opt|false |403\n</code></pre>\n\n<h2>Example 2</h2>\n\n<pre><code> server.get('/secure/loggedtest',\n           sec.isLoggedIn('param == 1', { forbiddenOnFail: true }),\n           next);\n\n request|param == 1 |logged|response\n -------|-----------|------|--------\n GET    |true       |true  |next()\n GET    |true       |false |401\n GET    |false      |true  |403\n GET    |false      |false |403\n GET    |missing opt|true  |403\n GET    |missing opt|false |403\n</code></pre>\n\n<h2>Example 3</h2>\n\n<pre><code> server.get('/secure/loggedtest',\n           sec.isLoggedIn('opt1 == 1', { nextOnError: true }),\n           next);\n\n request|param == 1 |logged|response\n -------|-----------|------|--------\n GET    |true       |true  |next()\n GET    |true       |false |401\n GET    |false      |true  |next()\n GET    |false      |false |next()\n GET    |missing opt|true  |next(err)\n GET    |missing opt|false |next(err)\n</code></pre>\n\n<h2>Example 4</h2>\n\n<pre><code> server.get('/secure/loggedtest',\n           sec.isLoggedIn('opt1 == 1', { forbiddenOnFail: true, nextOnError: true }),\n           next);\n\n request|param == 1 |logged|response\n -------|-----------|------|--------\n GET    |true       |true  |next()\n GET    |true       |false |401\n GET    |false      |true  |403\n GET    |false      |false |403\n GET    |missing opt|true  |next(err)\n GET    |missing opt|false |next(err)\n</code></pre>\n<h3 class=\"pa\">Parameters</h3><ul><li><span class='pre'>conditions</span> : String (optional)<div class='sub-desc'><p>A string with a test that will be executed before to check next condition</p>\n</div></li><li><span class='pre'>opts</span> : Object (optional)<div class='sub-desc'><p>Options to customize the behavior of the test</p>\n<ul><li><span class='pre'>nextOnError</span> : Boolean (optional)<div class='sub-desc'><p>When true and the test trows an error, it execute next()</p>\n<p>Defaults to: <code>false</code></p></div></li><li><span class='pre'>forbiddenOnFail</span> : Boolean (optional)<div class='sub-desc'><p>When true and the test fails (without error), it sends a 403 error</p>\n<p>Defaults to: <code>false</code></p></div></li></ul></div></li></ul><h3 class='pa'>Returns</h3><ul><li><span class='pre'>String</span><div class='sub-desc'><p>The result of the logged test.</p>\n\n<p>Values:</p>\n\n<ul>\n<li>'ok': if the authorization test are successful evaluated</li>\n<li>'ko': if the authorization test fails</li>\n<li>'specific error': a string with a detail about the error occurred in conditions evaluation (e.g.: missing param)</li>\n</ul>\n\n</div></li></ul></div></div></div><div id='method-isSelf' class='member  not-inherited'><a href='#' class='side expandable'><span>&nbsp;</span></a><div class='title'><div class='meta'><span class='defined-in' rel='node_modules.authorify.authorization'>node_modules.authorify.authorization</span><br/><a href='source/authorization.html#node_modules-authorify-authorization-method-isSelf' target='_blank' class='view-source'>view source</a></div><a href='#!/api/node_modules.authorify.authorization-method-isSelf' class='name expandable'>isSelf</a>( <span class='pre'>[conditions], [opts]</span> ) : String<span class=\"signature\"></span></div><div class='description'><div class='short'>Check if the user id specified as param is the same of the logged user. ...</div><div class='long'><p>Check if the user id specified as param is the same of the logged user. See more example about conditions\nand options in <a href=\"#!/api/node_modules.authorify.authorization-method-isLoggedIn\" rel=\"node_modules.authorify.authorization-method-isLoggedIn\" class=\"docClass\">isLoggedIn</a> handler.</p>\n\n<h2>Example</h2>\n\n<pre><code> server.get('/secure/user/:user', sec.isSelf(), ok);\n</code></pre>\n<h3 class=\"pa\">Parameters</h3><ul><li><span class='pre'>conditions</span> : String (optional)<div class='sub-desc'><p>A string with a test that will be executed before to check next condition</p>\n</div></li><li><span class='pre'>opts</span> : Object (optional)<div class='sub-desc'><p>Options to customize the behavior of the test</p>\n<ul><li><span class='pre'>nextOnError</span> : Boolean (optional)<div class='sub-desc'><p>When true and the test trows an error, it execute next()</p>\n<p>Defaults to: <code>false</code></p></div></li><li><span class='pre'>forbiddenOnFail</span> : Boolean (optional)<div class='sub-desc'><p>When true and the test fails (without error), it sends a 403 error</p>\n<p>Defaults to: <code>false</code></p></div></li></ul></div></li></ul><h3 class='pa'>Returns</h3><ul><li><span class='pre'>String</span><div class='sub-desc'><p>The result of the logged test.</p>\n\n<p>Values:</p>\n\n<ul>\n<li>'ok': if the authorization test are successful evaluated</li>\n<li>'ko': if the authorization test fails</li>\n<li>'specific error': a string with a detail about the error occurred in conditions evaluation (e.g.: missing param)</li>\n</ul>\n\n</div></li></ul></div></div></div><div id='method-isSelfOrInRole' class='member  not-inherited'><a href='#' class='side expandable'><span>&nbsp;</span></a><div class='title'><div class='meta'><span class='defined-in' rel='node_modules.authorify.authorization'>node_modules.authorify.authorization</span><br/><a href='source/authorization.html#node_modules-authorify-authorization-method-isSelfOrInRole' target='_blank' class='view-source'>view source</a></div><a href='#!/api/node_modules.authorify.authorization-method-isSelfOrInRole' class='name expandable'>isSelfOrInRole</a>( <span class='pre'>roles, [conditions], [opts]</span> ) : String<span class=\"signature\"></span></div><div class='description'><div class='short'>Check if the user id specified as param is the same of the logged user or the user belongs\nat least one of the role/r...</div><div class='long'><p>Check if the user id specified as param is the same of the logged user or the user belongs\nat least one of the role/roles specified. See more example about conditions and options in\n<a href=\"#!/api/node_modules.authorify.authorization-method-isLoggedIn\" rel=\"node_modules.authorify.authorization-method-isLoggedIn\" class=\"docClass\">isLoggedIn</a> handler.</p>\n\n<h2>Example</h2>\n\n<pre><code> server.get('/secure/selfrole/:user/somepath', sec.isSelfOrInRole(['admin', 'user']), ok);\n</code></pre>\n<h3 class=\"pa\">Parameters</h3><ul><li><span class='pre'>roles</span> : String/Array<div class='sub-desc'><p>A string or an array with one or more roles (at least one) to which\nthe current user should belong to</p>\n</div></li><li><span class='pre'>conditions</span> : String (optional)<div class='sub-desc'><p>A string with a test that will be executed before to check next condition</p>\n</div></li><li><span class='pre'>opts</span> : Object (optional)<div class='sub-desc'><p>Options to customize the behavior of the test</p>\n<ul><li><span class='pre'>nextOnError</span> : Boolean (optional)<div class='sub-desc'><p>When true and the test trows an error, it execute next()</p>\n<p>Defaults to: <code>false</code></p></div></li><li><span class='pre'>forbiddenOnFail</span> : Boolean (optional)<div class='sub-desc'><p>When true and the test fails (without error), it sends a 403 error</p>\n<p>Defaults to: <code>false</code></p></div></li></ul></div></li></ul><h3 class='pa'>Returns</h3><ul><li><span class='pre'>String</span><div class='sub-desc'><p>The result of the logged test.</p>\n\n<p>Values:</p>\n\n<ul>\n<li>'ok': if the authorization test are successful evaluated</li>\n<li>'ko': if the authorization test fails</li>\n<li>'specific error': a string with a detail about the error occurred in conditions evaluation (e.g.: missing param)</li>\n</ul>\n\n</div></li></ul></div></div></div></div></div></div></div>","aliases":{},"files":[{"href":"authorization.html#node_modules-authorify-authorization","filename":"authorization.js"}]});