-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #141 from humanmade/113-documentation-linting-issues
Reformat docs files after linting
- Loading branch information
Showing
5 changed files
with
119 additions
and
97 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
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. |
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,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. |
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,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. |
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