From fddd9f6b9c7f21e1c03f7877b021e4223f809e7f Mon Sep 17 00:00:00 2001 From: Tim van Dijen Date: Mon, 30 May 2022 22:43:17 +0200 Subject: [PATCH] Fix markdown --- README.md | 22 +++++++++++ docs/authorize.md | 99 +++++++++++++++++++++++++++++------------------ 2 files changed, 84 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 677d1db..3eae423 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,27 @@ +# Authorize + ![Build Status](https://github.com/simplesamlphp/simplesamlphp-module-authorize/workflows/CI/badge.svg?branch=master) [![Coverage Status](https://codecov.io/gh/simplesamlphp/simplesamlphp-module-authorize/branch/master/graph/badge.svg)](https://codecov.io/gh/simplesamlphp/simplesamlphp-module-authorize) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/simplesamlphp/simplesamlphp-module-authorize/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/simplesamlphp/simplesamlphp-module-authorize/?branch=master) [![Type Coverage](https://shepherd.dev/github/simplesamlphp/simplesamlphp-module-authorize/coverage.svg)](https://shepherd.dev/github/simplesamlphp/simplesamlphp-module-authorize) [![Psalm Level](https://shepherd.dev/github/simplesamlphp/simplesamlphp-module-authorize/level.svg)](https://shepherd.dev/github/simplesamlphp/simplesamlphp-module-authorize) + +## Install + +Install with composer + +```bash + vendor/bin/composer require simplesamlphp/simplesamlphp-module-authorize +``` + +## Configuration + +Next thing you need to do is to enable the module: in `config.php`, +search for the `module.enable` key and set `authorize` to true: + +```php + 'module.enable' => [ + 'authorize' => true, + … + ], +``` diff --git a/docs/authorize.md b/docs/authorize.md index d18964d..2ab5f1e 100644 --- a/docs/authorize.md +++ b/docs/authorize.md @@ -1,55 +1,71 @@ -authorize Module -================ - - +# authorize Module * Author: Ernesto Revilla , Yaco Sistemas, Ryan Panning * Package: SimpleSAMLphp -This module provides a user authorization filter based on attribute matching for those applications that do not cleanly separate authentication from authorization and set some default permissions for authenticated users. +This module provides a user authorization filter based on attribute matching +for those applications that do not cleanly separate authentication from +authorization and set some default permissions for authenticated users. `authorize:Authorize` : Authorize certain users based on attribute matching -`authorize:Authorize` ---------------------- +## `authorize:Authorize` -There are three configuration options that can be defined: `deny`, `regex`, and `reject_msg`. All other filter configuration options are considered attribute matching rules. +There are three configuration options that can be defined: `deny`, `regex`, +and `reject_msg`. All other filter configuration options are considered +attribute matching rules. Unauthorized users will be shown a 403 Forbidden page. -### `deny` ### -The default action of the filter is to authorize only if an attribute match is found (default allow). When set to TRUE, this option reverses that rule and authorizes the user unless an attribute match is found (default deny), causing an unauthorized action. +### `deny` + +The default action of the filter is to authorize only if an attribute match +is found (default allow). When set to TRUE, this option reverses that rule and +authorizes the user unless an attribute match is found (default deny), causing +an unauthorized action. + +**Note**: This option needs to be boolean (TRUE/FALSE) else it will be considered + an attribute matching rule. + +### `regex` + +Turn regex pattern matching on or off for the attribute values defined. For +backwards compatibility, this option defaults to TRUE, but can be turned off +by setting it to FALSE. -Note: This option needs to be boolean (TRUE/FALSE) else it will be considered an attribute matching rule. +**Note**: This option needs to be boolean (TRUE/FALSE) else it will be + considered an attribute matching rule. -### `regex` ### -Turn regex pattern matching on or off for the attribute values defined. For backwards compatibility, this option defaults to TRUE, but can be turned off by setting it to FALSE. +### `reject_msg` -Note: This option needs to be boolean (TRUE/FALSE) else it will be considered an attribute matching rule. +This option can be used to provide a localised, custom message to an +unauthorised user. For example: tailored instructions on how to fix the +authorisation issue, specific contact details, etc. -### `reject_msg` ### -This option can be used to provide a localised, custom message to an unauthorised user. For example: tailored instructions on how to fix the authorisation issue, specific contact details, etc. +It should be an array of key/value pairs, with the keys as the language code. +You can use HTML in the message. See below for an example. -It should be an array of key/value pairs, with the keys as the language code. You can use HTML in the message. See below for an example. +## Attribute Rules +Each additional filter configuration option is considered an attribute matching +rule. For each attribute, you can specify a string or array of strings to match. +If one of those attributes match one of the rules (OR operator), the user is +authorized/unauthorized (depending on the deny config option). -### Attribute Rules ### -Each additional filter configuration option is considered an attribute matching rule. For each attribute, you can specify a string or array of strings to match. If one of those attributes match one of the rules (OR operator), the user is authorized/unauthorized (depending on the deny config option). +**Note**: If regex is enabled, you must use the preg_match format, i.e. you have + to enclose it with a delimiter that does not appear inside the regex + (e.g. slash (/), at sign (@), number sign (#) or underscore (`_`)). -Note: If regex is enabled, you must use the preg_match format, i.e. you have to enclose it with a delimiter that does not appear inside the regex (e.g. slash (/), at sign (@), number sign (#) or underscore (`_`)). +### Problems -### Problems ### * Once you get the forbidden page, you can't logout at the IdP directly, (as far as I know), you have to close the browser. -### Examples ### +### Examples + To use this filter configure it in `config/config.php`. For unstructured attributes use `^` and `$` to anchor your regex as necessary: @@ -59,7 +75,10 @@ For unstructured attributes use `^` and `$` to anchor your regex as necessary: 'class' => 'authorize:Authorize', 'uid' => [ '/^.*@example.com$/', - // Use anchors to prevent matching 'wronguser1@example.edu.attacker.com' + /* + * Use anchors to prevent matching + * 'wronguser1@example.edu.attacker.com' + */ '/^(user1|user2|user3)@example.edu$/', ], 'schacUserStatus' => '@urn:mace:terena.org:userStatus:' . @@ -68,8 +87,9 @@ For unstructured attributes use `^` and `$` to anchor your regex as necessary: ] ``` - -An alternate way of using this filter is to deny certain users. Or even use multiple filters to create a simple ACL, by first allowing a group of users but then denying a "black list" of users. +An alternate way of using this filter is to deny certain users. Or even use +multiple filters to create a simple ACL, by first allowing a group of users but +then denying a "black list" of users. ```php 'authproc.sp' => [ @@ -84,7 +104,10 @@ An alternate way of using this filter is to deny certain users. Or even use mult ] ``` -The regex pattern matching can be turned off, allowing for exact attribute matching rules. This can be helpful in cases where you know what the value should be. An example of this is with the memberOf attribute or using the ldap:AttributeAddUsersGroups filter with the group attribute. +The regex pattern matching can be turned off, allowing for exact attribute +matching rules. This can be helpful in cases where you know what the value +should be. An example of this is with the memberOf attribute or using the +ldap:AttributeAddUsersGroups filter with the group attribute. Additionally, some helpful instructions are shown. @@ -98,11 +121,13 @@ Additionally, some helpful instructions are shown. 'CN=All Teachers,OU=Staff,DC=example,DC=edu', ], 'reject_msg' => [ - 'en' => 'This service is only available to students and teachers.' . - 'Please contact support.', - 'nl' => 'Deze dienst is alleen beschikbaar voor studenten en docenten.' . - 'Neem contact op met support.', - ] - ] -] + 'en' => 'This service is only available to students and' . + ' teachers. Please contact ' . + 'support.', + 'nl' => 'Deze dienst is alleen beschikbaar voor studenten en ' . + 'docenten. Neem contact op met ' . + 'support.', + ], + ], +], ```