Skip to content

Commit

Permalink
Merge pull request #141 from humanmade/113-documentation-linting-issues
Browse files Browse the repository at this point in the history 
Reformat docs files after linting
  • Loading branch information
@mikelittle
mikelittle authored Jul 15, 2024
2 parents 520e023 + 68009e0 commit df3fcd2
Show file tree
Hide file tree
Showing 5 changed files with 119 additions and 97 deletions.
2 changes: 1 addition & 1 deletion .travis.yml
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Import Travis configuration from dev-tools repo
version: ~> 1.0
import:
- source: humanmade/altis-dev-tools:travis/module.yml@4accc74
- 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.
15 changes: 10 additions & 5 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,24 @@
# 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:

* [SAML 2.0](./saml-2-0.md)

## 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.
83 changes: 47 additions & 36 deletions docs/saml-2-0/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,73 +1,84 @@
# 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 `<site-url>` should be replaced with your application's primary site URL:
In your IdP you can provide the following endpoint URLs to configure SSO, where `<site-url>` should be replaced with your
application's primary site URL:

- Single Logout Service (SLS): `https://<site-url>/sso/sls`
- Assertion Consumer Service (ACS): `https://<site-url>/sso/verify`

**Note:**: `<site-url>` will default to your primary network URL rather than the current site's URL. For per site mode use the following filter:
**Note:**: `<site-url>` 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 );
```

## 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
}
}
}
}
}
}
```

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://<site-url>/sso/metadata`.
When you have an IdP Metadata XML file you also retrieve the Service Provider Metadata XML from the
URL `https://<site-url>/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.<env-type>` 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.
63 changes: 33 additions & 30 deletions docs/saml-2-0/mapping.md
View file
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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
*
Expand All @@ -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 them based on other user data instead.

The `wpsimplesaml_match_user` filter allows you to implement your own user matching code:

Expand All @@ -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.
53 changes: 28 additions & 25 deletions docs/saml-2-0/roles.md
View file
Original file line number Diff line number Diff line change
@@ -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 hard coded, or use information from your IdP such as the ActiveDirectory role claim.

The `wpsimplesaml_map_role` filter receives the following parameters:

Expand Down Expand Up @@ -62,23 +65,23 @@ 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 );
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.
Expand All @@ -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 [];
}
}
```

0 comments on commit df3fcd2

Please sign in to comment.