-
-
Notifications
You must be signed in to change notification settings - Fork 10
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
4 changed files
with
230 additions
and
70 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,13 +1,132 @@ | ||
| [](https://travis-ci.org/monken/node-pbac) | ||
| [](https://npmjs.org/package/pbac) [](https://npmjs.org/package/jsdox) [](https://travis-ci.org/monken/node-pbac) | ||
|
|
||
| # node-pbac | ||
| # Policy Based Access Control | ||
|
|
||
| **AWS IAM Policy compatible evaluation engine** | ||
|
|
||
| Use the power and flexibility of the AWS IAM Policy syntax in your own application to manage access control. For more details on AWS IAM Policies have a look at https://docs.aws.amazon.com/IAM/latest/UserGuide/policies_overview.html. | ||
|
|
||
| **Note:** The policy elements `Principal`, `NotPrincipal`, `NotResource` and conditions `ArnEquals`, `ArnNotEquals`, `ArnLike`, `ArnNotLike` are not supported at the moment. | ||
|
|
||
| ## Installation | ||
|
|
||
| ``` | ||
| npm install pbac | ||
| ``` | ||
|
|
||
|
|
||
| <!-- START doctoc --> | ||
| <!-- END doctoc --> | ||
|
|
||
| ## Synopsis | ||
|
|
||
| ```javascript | ||
| var PBAC = require('pbac'); | ||
|
|
||
| var policies = [{ | ||
| "Version": "2012-10-17", | ||
| "Statement": [{ | ||
| "Sid": "OptionalDescription", | ||
| "Effect": "Allow", | ||
| "Action": [ | ||
| "iam:CreateUser", | ||
| "iam:UpdateUser", | ||
| "iam:DeleteUser" | ||
| ], | ||
| "Resource": [ | ||
| "arn:aws:iam:::user/${req:UserName}" | ||
| ], | ||
| "Condition": { | ||
| "IpAddress": { | ||
| "req:IpAddress": "10.0.20.0/24" | ||
| } | ||
| } | ||
| }] | ||
| }]; | ||
|
|
||
| var pbac = new PBAC(policies); | ||
|
|
||
| // returns true | ||
| pbac.evaluate({ | ||
| action: 'iam:CreateUser', | ||
| resource: 'arn:aws:iam:::user/testuser', | ||
| variables: { | ||
| req: { | ||
| IpAddress: '10.0.20.51', | ||
| UserName: 'testuser', | ||
| } | ||
| } | ||
| }); | ||
| ``` | ||
|
|
||
| ## Constructor | ||
|
|
||
| ```javascript | ||
| var pbac = new PBAC(policies, [options]); | ||
| ``` | ||
|
|
||
| Constructs a policy evaluator. | ||
|
|
||
| ### Properties | ||
|
|
||
|
|
||
| * **`policies`** (Array|Object) | ||
| Either an array of policies or a single policy document. Have a look at https://docs.aws.amazon.com/IAM/latest/UserGuide/AccessPolicyLanguage_ElementDescriptions.html for a description of the policy syntax. | ||
| * **`options`** (Object) | ||
| * `schema` (Object) | ||
| JSON schema that describes the policies. Defaults to the contents of `schema.json` that ships with this module. | ||
| * `validateSchema` (Boolean) | ||
| Validate the schema when the object is constructed. This can be disabled in a production environment if it can be assumed that the schema is valid to improve performance when constructing new objects. | ||
| * `validatePolicies` (Boolean) | ||
| Policies passed to the constructor will be validated against the `schema`. Defaults to `true`. Can be disabled to improve performance if the policies can be assumed to be valid. | ||
| * `conditions` (Object) | ||
| Object of conditions that are supported in the `Conditions` attribute of policies. Defaults to `conditions.js` in this module. If conditions are passed to the constructor they will be merged with the conditions of the `conditions.js` module (with `conditions.js` taking precedence). | ||
|
|
||
|
|
||
| ## Methods | ||
|
|
||
|
|
||
| ### evaluate(params) | ||
|
|
||
| Tests an object against the policies and determines if the object passes. | ||
| The method will first try to find a policy with an explicit `Deny` for the combination of | ||
| `resource`, `action` and `condition` (matching policy). If such policy exists, `evaulate` returns false. | ||
| If there is no explicit deny the method will look for a matching policy with an explicit `Allow`. | ||
| `evaulate` will return `true` if such a policy is found. If no matching can be found at all, | ||
| `evaluate` will return `false`. Please find a more thorough explanation of this process at https://docs.aws.amazon.com/IAM/latest/UserGuide/AccessPolicyLanguage_EvaluationLogic.html. | ||
|
|
||
| ```javascript | ||
| pbac.evaluate({ | ||
| action: 'iam:CreateUser', | ||
| resource: 'arn:aws:iam:::user/testuser', | ||
| variables: { | ||
| req: { | ||
| IpAddress: '10.0.20.51', | ||
| UserName: 'testuser', | ||
| } | ||
| } | ||
| }); | ||
| ``` | ||
|
|
||
| **Parameters** | ||
|
|
||
| * **`params`** (Object) | ||
| * `action` (String) - Action to validate | ||
| * `resource` (String) - Resource to validate | ||
| * `variables` (Object) - Nested object of variables for interpolation of policy variables. See [Variables](). | ||
|
|
||
| **Returns**: `boolean`, Returns `true` if `params` passes the policies, `false` otherwise | ||
|
|
||
| ### validate(policy) | ||
|
|
||
| Validates one or many policies against the schema provided in the constructor. | ||
| Will throw an error if validation fails. | ||
|
|
||
| **Parameters** | ||
|
|
||
| * **`policy`** (Array|Object) | ||
| Array of policies or a single policy object | ||
|
|
||
| **Returns**: `boolean`, Returns `true` if the policies are valid | ||
|
|
||
| * * * | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.