From b334f89cae1a246c8ea2906cba9c7b145e780835 Mon Sep 17 00:00:00 2001 From: Mike Little Date: Wed, 3 Jul 2024 15:51:11 +0100 Subject: [PATCH 1/4] Reformat docs files after linting This changes all the docs files to be formatted correctly after linting. The main changes are line length, spaces instead of tabs, and addition of alt text for images. --- docs/README.md | 15 ++++--- docs/saml-2-0/README.md | 85 +++++++++++++++++++++++----------------- docs/saml-2-0/mapping.md | 63 +++++++++++++++-------------- docs/saml-2-0/roles.md | 51 ++++++++++++------------ 4 files changed, 119 insertions(+), 95 deletions(-) diff --git a/docs/README.md b/docs/README.md index e6c2f8a..6e8fc5c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,12 +1,16 @@ # Single Sign On -![](./assets/banner-sso.png) +![SSO Header](./assets/banner-sso.png) -The SSO module allows you to delegate the authorization and user management of your site to an external service. This is not uncommon in organizations where user management is handled by a central server. +The SSO module allows you to delegate the authorization and user management of your site to an external service. This is not +uncommon in organizations where user management is handled by a central server. -The SSO module provides built in support for popular authorization protocols. The implementation of the authorization client all work in mostly the same way. The SSO provider is used to authenticate a user, typically via a web redirect. Once the user has authenticated, they are redirected back to the Altis application, where their user record is imported into the CMS. +The SSO module provides built in support for popular authorization protocols. The implementation of the authorization client all +work in mostly the same way. The SSO provider is used to authenticate a user, typically via a web redirect. Once the user has +authenticated, they are redirected back to the Altis application, where their user record is imported into the CMS. -Once the CMS has a user record in the database, the user's session is authorized and logged in to that account. Any user operations from that point on are treating as regular CMS user operations, against the local "mirrored" user record. +Once the CMS has a user record in the database, the user's session is authorized and logged in to that account. Any user operations +from that point on are treating as regular CMS user operations, against the local "mirrored" user record. Supported authorization providers are: @@ -14,6 +18,7 @@ Supported authorization providers are: ## Hiding native login -If you're using a single sign-on provider, you may wish to hide the regular WordPress username and password options from the login screen. This can be configured via setting the `modules.sso.hide_native` configuration option to `true` +If you're using a single sign-on provider, you may wish to hide the regular WordPress username and password options from the login +screen. This can be configured via setting the `modules.sso.hide_native` configuration option to `true` Note: This will only disable the visual display of the login form. Username and password authentication cannot be disabled. diff --git a/docs/saml-2-0/README.md b/docs/saml-2-0/README.md index 95873c4..ba13225 100644 --- a/docs/saml-2-0/README.md +++ b/docs/saml-2-0/README.md @@ -1,15 +1,18 @@ # SAML 2.0 -The SSO module includes support for SAML 2.0 as a Service Provider (SP). To enable SAML 2.0, you must define the `saml` setting in the Altis configuration. You'll need a copy of your SAML Identity Provider (IdP) metadata XML too. +The SSO module includes support for SAML 2.0 as a Service Provider (SP). To enable SAML 2.0, you must define the `saml` setting in +the Altis configuration. You'll need a copy of your SAML Identity Provider (IdP) metadata XML too. ## Service Provider Endpoints -In your IdP you can provide the following endpoint URLs to configure SSO, where `` should be replaced with your application's primary site URL: +In your IdP you can provide the following endpoint URLs to configure SSO, where `` should be replaced with your +application's primary site URL: - Single Logout Service (SLS): `https:///sso/sls` - Assertion Consumer Service (ACS): `https:///sso/verify` -**Note:**: `` will default to your primary network URL rather than the current site's URL. For per site mode use the following filter: +**Note:**: `` will default to your primary network URL rather than the current site's URL. For per site mode use the +following filter: ```php add_filter( 'wpsimplesaml_network_activated', '__return_false', 100 ); @@ -17,57 +20,67 @@ add_filter( 'wpsimplesaml_network_activated', '__return_false', 100 ); ## Identity Provider Metadata XML -To enable SAML 2.0 support, add the IdP metadata XML files to your project's `.config/sso/` directory (you may need to create the directory first). +To enable SAML 2.0 support, add the IdP metadata XML files to your project's `.config/sso/` directory (you may need to create the +directory first). -By default, Altis looks for `.config/sso/saml-idp-metadata-%ENVIRONMENT%.xml` where `%ENVIRONMENT%` is one of `local`, `development`, `staging`, or `production`, and falls back to `.config/sso/saml-idp-metadata.xml`. Make sure there are no XML formatting errors or leading whitespace. +By default, Altis looks for `.config/sso/saml-idp-metadata-%ENVIRONMENT%.xml` where `%ENVIRONMENT%` is one +of `local`, `development`, `staging`, or `production`, and falls back to `.config/sso/saml-idp-metadata.xml`. Make sure there are no +XML formatting errors or leading whitespace. Lastly define the following option in your Altis configuration: - ```json { - "extra": { - "altis": { - "modules": { - "sso": { - "saml": { - "required": true | false, - } - } - } - } - } + "extra": { + "altis": { + "modules": { + "sso": { + "saml": { + "required": true + | + false + } + } + } + } + } } ``` -The `required` setting defines whether authentication via the SAML 2.0 IdP _must_ be used to login, or if it should be optional. When set to `true`, all users attempting to login to the site will be redirected to the SAML IdP for authorization. When setting this to `false`, an "SSO Login" link will be added to the login page, where users can optionally authorize with the SAML IdP. +The `required` setting defines whether authentication via the SAML 2.0 IdP _must_ be used to login, or if it should be optional. +When set to `true`, all users attempting to login to the site will be redirected to the SAML IdP for authorization. When setting +this to `false`, an "SSO Login" link will be added to the login page, where users can optionally authorize with the SAML IdP. -When you have an IdP Metadata XML file you also retrieve the Service Provider Metadata XML from the URL `https:///sso/metadata`. +When you have an IdP Metadata XML file you also retrieve the Service Provider Metadata XML from the +URL `https:///sso/metadata`. ### Custom IdP Metadata XML File Paths -The SAML IdP Metadata XML file location can be overridden by the `sso.saml.metadata_file` config setting, which is a path relative to your project root. The setting doesn't need to be overridden if the files are in the expected location with the expected naming conventions. The config setting is provided as an option if your IdP Metadata XML is not added to the code base manually. +The SAML IdP Metadata XML file location can be overridden by the `sso.saml.metadata_file` config setting, which is a path relative +to your project root. The setting doesn't need to be overridden if the files are in the expected location with the expected naming +conventions. The config setting is provided as an option if your IdP Metadata XML is not added to the code base manually. You can also override the settings on a per environment basis using the `environments.` config path, for example: ```json { - "extra": { - "altis": { - "environments": { - "development": { - "modules": { - "sso": { - "saml": { - "metadata_file": ".config/sso/custom-dev-idp-metadata.xml" - } - } - } - } - } - } - } + "extra": { + "altis": { + "environments": { + "development": { + "modules": { + "sso": { + "saml": { + "metadata_file": ".config/sso/custom-dev-idp-metadata.xml" + } + } + } + } + } + } + } } ``` -For further details on SAML 2.0, [see the docs for wp-simple-saml plugin](https://github.com/humanmade/wp-simple-saml) that powers this feature. +For further details on SAML 2.0, [see the docs for wp-simple-saml plugin](https://github.com/humanmade/wp-simple-saml) that powers +this feature. diff --git a/docs/saml-2-0/mapping.md b/docs/saml-2-0/mapping.md index 93ffd10..48dcbb2 100644 --- a/docs/saml-2-0/mapping.md +++ b/docs/saml-2-0/mapping.md @@ -1,10 +1,10 @@ # Mapping Data -The SAML SSO functionality includes out-of-the-box functionality for mapping data from your identity provider (IdP) to WordPress-native data. +The SAML SSO functionality includes out-of-the-box functionality for mapping data from your identity provider (IdP) to +WordPress-native data. This mapping can be customized and extended to match the way your IdP stores data. - ## User details By default, the following fields are mapped: @@ -14,28 +14,32 @@ By default, the following fields are mapped: * `first_name`: `firstName` SAML attribute * `last_name`: `lastName` SAML attribute -This can be filtered via the `wpsimplesaml_attribute_mapping` filter, which receives an associative array mapping user properties to SAML attribute name. (Note: only these four fields are supported.) +This can be filtered via the `wpsimplesaml_attribute_mapping` filter, which receives an associative array mapping user properties to +SAML attribute name. (Note: only these four fields are supported.) -For example, for Active Directory (AD), you may want to use the [AD claims](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/technical-reference/the-role-of-claims) instead: +For example, for Active Directory (AD), you may want to use +the [AD claims](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/technical-reference/the-role-of-claims) instead: ```php add_filter( 'wpsimplesaml_attribute_mapping', function() { - return [ - 'user_email' => 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress', - 'first_name' => 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname', - 'last_name' => 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname', - 'user_login' => 'http://schemas.microsoft.com/identity/claims/displayname', - ]; + return [ + 'user_email' => 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress', + 'first_name' => 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname', + 'last_name' => 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname', + 'user_login' => 'http://schemas.microsoft.com/identity/claims/displayname', + ]; } ); ``` ### Advanced user details -Aside from the direct mapping of these, you can also filter the final data before it is sent to WordPress, via the `wpsimplesaml_user_data` filter. +Aside from the direct mapping of these, you can also filter the final data before it is sent to WordPress, via +the `wpsimplesaml_user_data` filter. -This filter receives the full user data being passed to `wp_insert_user`. You can use it to apply any other customization (including adding metadata) to this user data. You'll also receive the SAML attributes. +This filter receives the full user data being passed to `wp_insert_user`. You can use it to apply any other customization (including +adding metadata) to this user data. You'll also receive the SAML attributes. -``` +```php /** * Filters user data before insertion to the database * @@ -45,10 +49,10 @@ This filter receives the full user data being passed to `wp_insert_user`. You ca apply_filters( 'wpsimplesaml_user_data', $user_data, $attributes ); ``` - ## Unique user matching -By default, when SAML SSO attempts to find an existing user, it'll look for any user with a matching email address (as returned from your mapping code). You may want to change this to deduplicate based on other user data instead. +By default, when SAML SSO attempts to find an existing user, it'll look for any user with a matching email address (as returned from +your mapping code). You may want to change this to deduplicate based on other user data instead. The `wpsimplesaml_match_user` filter allows you to implement your own user matching code: @@ -68,24 +72,23 @@ For example, if you have multiple corporate domains and need to deduplicate them ```php // Treat all users from corporate domains as equal. add_filter( 'wpsimplesaml_match_user', function ( $user, $email ) { - $email_parts = explode( '@', $email ); - $domains = [ - 'example.com', - 'example.org', - 'example.net', - ]; - foreach ( $aliases as $alias ) { - $aliased_user = get_user_by( 'email', $email_parts[0] . '@' . $alias ); - if ( $aliased_user ) { - return $aliased_user; - } - } - - return $user; + $email_parts = explode( '@', $email ); + $domains = [ + 'example.com', + 'example.org', + 'example.net', + ]; + foreach ( $aliases as $alias ) { + $aliased_user = get_user_by( 'email', $email_parts[0] . '@' . $alias ); + if ( $aliased_user ) { + return $aliased_user; + } + } + + return $user; }, 10, 2 ); ``` - ## Role mapping Roles can also be mapped; see the [user roles](./roles.md) documentation for more details. diff --git a/docs/saml-2-0/roles.md b/docs/saml-2-0/roles.md index 322805a..395c252 100644 --- a/docs/saml-2-0/roles.md +++ b/docs/saml-2-0/roles.md @@ -1,28 +1,31 @@ # User Roles -SAML SSO contains default functionality to handle roles for users created via SSO, but in many cases you may want more complex behaviour. +SAML SSO contains default functionality to handle roles for users created via SSO, but in many cases you may want more complex +behaviour. A variety of filters are provided to help map the data across from your identity provider (IdP). - ## Automatic default role -By default, when users log in, they'll receive the default role for your site, matching WordPress' behaviour for open registration sites. (Typically, this is `subscriber`.) +By default, when users log in, they'll receive the default role for your site, matching WordPress' behaviour for open registration +sites. (Typically, this is `subscriber`.) -For large multisites or complex use cases, this may not be desirable, as you may want to assign roles manually instead. This setting can be changed by returning false from the `wpsimplesaml_add_users_to_site` filter. +For large multisites or complex use cases, this may not be desirable, as you may want to assign roles manually instead. This setting +can be changed by returning false from the `wpsimplesaml_add_users_to_site` filter. ```php add_filter( 'wpsimplesaml_add_users_to_site', '__return_false' ); ``` -This filter receives the enabled boolean as the filterable value, and additionally receives the `WP_User` object as the second parameter, allowing you to change behaviour based on the specific user. - +This filter receives the enabled boolean as the filterable value, and additionally receives the `WP_User` object as the second +parameter, allowing you to change behaviour based on the specific user. ## Mapping roles from your IdP By default, roles aren't synchronized from your IdP, allowing you to manually assign them in WordPress instead. -In cases where you want to synchronize these roles, you can use the `wpsimplesaml_map_role` filter to determine the user's role. This could be hardcoded, or use information from your IdP such as the ActiveDirectory role claim. +In cases where you want to synchronize these roles, you can use the `wpsimplesaml_map_role` filter to determine the user's role. +This could be hardcoded, or use information from your IdP such as the ActiveDirectory role claim. The `wpsimplesaml_map_role` filter receives the following parameters: @@ -67,18 +70,18 @@ For example, you could hardcode this to make all users editors instead of the de ```php add_filter( 'wpsimplesaml_manage_roles', '__return_true', 11 ); add_filter( 'wpsimplesaml_map_role', function ( $role ) { - return [ - 'editor', - ]; + return [ + 'editor', + ]; } ); ``` - ### Mapping from Active Directory role claim When connecting to an Active Directory (AD) SAML IdP, you may wish to use roles stored in the IdP. -These are exposed via the `http://schemas.microsoft.com/ws/2008/06/identity/claims/role` claim in SAML, and can be mapped from the SAML attributes in your custom code. +These are exposed via the `http://schemas.microsoft.com/ws/2008/06/identity/claims/role` claim in SAML, and can be mapped from the +SAML attributes in your custom code. ```php // Map AD user group membership to WordPress roles. @@ -94,21 +97,21 @@ add_filter( 'wpsimplesaml_manage_roles', '__return_true', 11 ); * @return string|array Updated user role. */ function map_user_role( $default_role, array $attributes ) { - $role_key = 'http://schemas.microsoft.com/ws/2008/06/identity/claims/role'; + $role_key = 'http://schemas.microsoft.com/ws/2008/06/identity/claims/role'; - switch ( $attributes[ $role_key ][0] ?? null ) { - case 'gg_rol_EX-PROD-Admins': - return 'administrator'; + switch ( $attributes[ $role_key ][0] ?? null ) { + case 'gg_rol_EX-PROD-Admins': + return 'administrator'; - case 'gg_rol_EX-PROD-Editors': - return 'editor'; + case 'gg_rol_EX-PROD-Editors': + return 'editor'; - case 'gg_rol_EX-PROD-ReadOnly': - return 'subscriber'; + case 'gg_rol_EX-PROD-ReadOnly': + return 'subscriber'; - default: - // Give no roles by default. - return []; - } + default: + // Give no roles by default. + return []; + } } ``` From b98d4e36ef981eeab717f71b0235788342eeae73 Mon Sep 17 00:00:00 2001 From: Mike Little Date: Wed, 3 Jul 2024 16:10:38 +0100 Subject: [PATCH 2/4] Correct json format . --- docs/saml-2-0/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/saml-2-0/README.md b/docs/saml-2-0/README.md index ba13225..9fb591d 100644 --- a/docs/saml-2-0/README.md +++ b/docs/saml-2-0/README.md @@ -37,8 +37,6 @@ Lastly define the following option in your Altis configuration: "sso": { "saml": { "required": true - | - false } } } From 7d88dc52c6177661da6e85a1bc3c9770d9d3c7d4 Mon Sep 17 00:00:00 2001 From: Mike Little Date: Wed, 3 Jul 2024 17:22:03 +0100 Subject: [PATCH 3/4] Spelling and grammar fixes. --- docs/saml-2-0/mapping.md | 2 +- docs/saml-2-0/roles.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/saml-2-0/mapping.md b/docs/saml-2-0/mapping.md index 48dcbb2..39942ca 100644 --- a/docs/saml-2-0/mapping.md +++ b/docs/saml-2-0/mapping.md @@ -52,7 +52,7 @@ apply_filters( 'wpsimplesaml_user_data', $user_data, $attributes ); ## Unique user matching By default, when SAML SSO attempts to find an existing user, it'll look for any user with a matching email address (as returned from -your mapping code). You may want to change this to deduplicate based on other user data instead. +your mapping code). You may want to change this to deduplicate them based on other user data instead. The `wpsimplesaml_match_user` filter allows you to implement your own user matching code: diff --git a/docs/saml-2-0/roles.md b/docs/saml-2-0/roles.md index 395c252..babc9ff 100644 --- a/docs/saml-2-0/roles.md +++ b/docs/saml-2-0/roles.md @@ -17,7 +17,7 @@ can be changed by returning false from the `wpsimplesaml_add_users_to_site` filt add_filter( 'wpsimplesaml_add_users_to_site', '__return_false' ); ``` -This filter receives the enabled boolean as the filterable value, and additionally receives the `WP_User` object as the second +This filter receives the enabled Boolean as the filterable value, and additionally receives the `WP_User` object as the second parameter, allowing you to change behaviour based on the specific user. ## Mapping roles from your IdP @@ -25,7 +25,7 @@ parameter, allowing you to change behaviour based on the specific user. By default, roles aren't synchronized from your IdP, allowing you to manually assign them in WordPress instead. In cases where you want to synchronize these roles, you can use the `wpsimplesaml_map_role` filter to determine the user's role. -This could be hardcoded, or use information from your IdP such as the ActiveDirectory role claim. +This could be hard coded, or use information from your IdP such as the ActiveDirectory role claim. The `wpsimplesaml_map_role` filter receives the following parameters: @@ -65,7 +65,7 @@ You'll also need to enable mapping via the `wpsimplesaml_manage_roles` filter: add_filter( 'wpsimplesaml_manage_roles', '__return_true', 11 ); ``` -For example, you could hardcode this to make all users editors instead of the default role: +For example, you could hard code this to make all users editors instead of the default role: ```php add_filter( 'wpsimplesaml_manage_roles', '__return_true', 11 ); From 338b96571719a6b5724d68ccc65001ee9c0f3561 Mon Sep 17 00:00:00 2001 From: Mike Little Date: Mon, 15 Jul 2024 11:53:44 +0100 Subject: [PATCH 4/4] Update travis modules reference --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index ed3df12..268926b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,7 +1,7 @@ # Import Travis configuration from dev-tools repo version: ~> 1.0 import: - - source: humanmade/altis-dev-tools:travis/module.yml@f1fd9a5 + - source: humanmade/altis-dev-tools:travis/module.yml@0bfa112a mode: deep_merge_append # Add your custom config below, which will merge with the default module config from the section above.