Skip to content

Commit

Permalink
FEAT: Upgrade to new MTS and ITE integrations on new Azure platform (#66
Browse files Browse the repository at this point in the history 
)
  • Loading branch information
@madmatt
madmatt authored Mar 2, 2021
1 parent 88a2fba commit ffcfcc7
Show file tree
Hide file tree
Showing 2 changed files with 39 additions and 18 deletions.
24 changes: 19 additions & 5 deletions docs/en/configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,29 @@

## Configuration

### Environment variables and certificates

The following values need to be defined in your `.env` file for **all** environments. See the [SilverStripe documentation on environment management](https://docs.silverstripe.org/en/3.1/getting_started/environment_management/) for more information.

| **Environment Const** | **Example** | **Notes** |
| ------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `REALME_CERT_DIR` | /sites/realme-dev/secure/certs | Directory where all certificates will reside. All certificates should be placed here. Needs to be readable (but ideally not writeable) by the web server user. |
| `REALME_SIGNING_CERT_FILENAME` | mts_saml_sp.pem | Name of the SAML secure signing certificate for the required environment. For MTS, this is provided by RealMe, and is available on the RealMe developers site. |
| **Environment Const** | **Example** | **Notes** |
| ------------------------------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `REALME_CERT_DIR` | /sites/realme-dev/secure/certs | Directory where all certificates will reside. All certificates should be placed here. Needs to be readable (but ideally not writeable) by the web server user. |
| `REALME_SIGNING_CERT_FILENAME` | mts_saml_sp.pem | Name of the SAML secure signing certificate for the required environment (stored in `REALME_CERT_DIR`). For MTS, this is provided by RealMe, and is available on the RealMe developers site. |

It is important to note that the file referred to by `REALME_SIGNING_CERT_FILENAME` is expected to be in [PEM format](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail), containing both the private key and the certificate (and optionally any intermediary certificates). If your files are not structured this way it can be easily created by e.g. `cat yoursite.crt yoursite.ca-bundle yoursite.key > yoursite.pem` provided each file has the appropriate `-----BEGIN *-----` and `-----END *-----` headers & footers.

The `REALME_CERT_DIR` needs to contain the following files, depending on which environment you are integrating with:

#### For MTS
You must include `mts_saml_sp.pem` and either `mts_login_saml_idp.cer` or `mts_assert_saml_idp.cer` (depending on whether you are integration for logon or assert) from the MTS bundle available on the RealMe Developers website. Place both of these in your `REALME_CERT_DIR`.

#### For ITE
You must include your private key and signing certificate (PEM file) and then from the ITE integration bundle, take the `realme_signing.crt` file and rename it to `ite.signing.logon.realme.govt.nz.cer` (which is the Common Name on the certificate) and place this in your `REALME_CERT_DIR`.

It is important to note that the file referred to by `REALME_SIGNING_CERT_FILENAME` is expected to be in [PEM format](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail), containing both the private key and the certificate (and optionally any intermediary certificates). If your files are not structured this way it can be easily created by e.g. `cat yoursite.crt yoursite.ca-bundle yoursite.key > yoursite.pem` provided each file has the appropirate `-----BEGIN *-----` and `-----END *-----` headers & footers.
#### For Production
You must include your private key and signing certificate (PEM file) and then from the Production integration bundle, take the `<filename unknown>` file and rename it to `<tbc>` (which is the Common Name on the certificate) and place this in your `REALME_CERT_DIR`.

## YML configuration
In addition to these environment variables, YML configuration is required to specify some values that should be consistently applied across
environments. These are noted below.

Expand Down
33 changes: 20 additions & 13 deletions src/RealMeService.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -135,13 +135,15 @@ class RealMeService implements TemplateGlobalProvider
*/
private static $idp_entity_ids = array(
self::ENV_MTS => array(
self::TYPE_LOGIN => 'https://mts.realme.govt.nz/saml2',
self::TYPE_ASSERT => 'https://mts.realme.govt.nz/realmemts/realmeidp',
self::TYPE_LOGIN => 'https://mts.login.realme.govt.nz/4af8e0e0-497b-4f52-805c-00fa09b50c16/B2C_1A_DIA_RealMe_MTSLoginService',
self::TYPE_ASSERT => 'https://mts.login.realme.govt.nz/4af8e0e0-497b-4f52-805c-00fa09b50c16/B2C_1A_DIA_RealMe_MTSAssertionService',
),

self::ENV_ITE => array(
self::TYPE_LOGIN => 'https://www.ite.logon.realme.govt.nz/saml2',
self::TYPE_ASSERT => 'https://www.ite.account.realme.govt.nz/saml2/assertion',
self::TYPE_LOGIN => 'https://ite.login.realme.govt.nz/12c36372-4b2d-4865-b1d1-9599b0d37348/B2C_1A_DIA_RealMe_LoginService',
self::TYPE_ASSERT => 'https://ite.login.realme.govt.nz/12c36372-4b2d-4865-b1d1-9599b0d37348/B2C_1A_DIA_RealMe_AssertionService',
),

self::ENV_PROD => array(
self::TYPE_LOGIN => 'https://www.logon.realme.govt.nz/saml2',
self::TYPE_ASSERT => 'https://www.account.realme.govt.nz/saml2/assertion',
Expand All @@ -150,13 +152,15 @@ class RealMeService implements TemplateGlobalProvider

private static $idp_sso_service_urls = array(
self::ENV_MTS => array(
self::TYPE_LOGIN => 'https://mts.realme.govt.nz/logon-mts/mtsEntryPoint',
self::TYPE_ASSERT => 'https://mts.realme.govt.nz/realme-mts/validate/realme-mts-idp.xhtml'
self::TYPE_LOGIN => 'https://mts.login.realme.govt.nz/4af8e0e0-497b-4f52-805c-00fa09b50c16/B2C_1A_DIA_RealMe_MTSLoginService/samlp/sso/login',
self::TYPE_ASSERT => 'https://mts.login.realme.govt.nz/4af8e0e0-497b-4f52-805c-00fa09b50c16/B2C_1A_DIA_RealMe_MTSAssertionService/samlp/sso/login'
),

self::ENV_ITE => array(
self::TYPE_LOGIN => 'https://www.ite.logon.realme.govt.nz/sso/logon/metaAlias/logon/logonidp',
self::TYPE_ASSERT => 'https://www.ite.assert.realme.govt.nz/sso/SSORedirect/metaAlias/assertion/realmeidp'
self::TYPE_LOGIN => 'https://ite.login.realme.govt.nz/12c36372-4b2d-4865-b1d1-9599b0d37348/B2C_1A_DIA_RealMe_LoginService/samlp/sso/login',
self::TYPE_ASSERT => 'https://ite.login.realme.govt.nz/12c36372-4b2d-4865-b1d1-9599b0d37348/B2C_1A_DIA_RealMe_AssertionService/samlp/sso/login'
),

self::ENV_PROD => array(
self::TYPE_LOGIN => 'https://www.logon.realme.govt.nz/sso/logon/metaAlias/logon/logonidp',
self::TYPE_ASSERT => 'https://www.assert.realme.govt.nz/sso/SSORedirect/metaAlias/assertion/realmeidp'
Expand All @@ -165,20 +169,23 @@ class RealMeService implements TemplateGlobalProvider

/**
* @var array A list of certificate filenames for different RealMe environments and integration types. These files
* must be located in the directory specified by the REALME_CERT_DIR environment variable. These filenames are the
* same as the files that can be found in the RealMe Shared Workspace, within the 'Integration Bundle' ZIP files for
* the different environments (MTS, ITE and Production), so you just need to extract the specific certificate file
* that you need and make sure it's in place on the server in the REALME_CERT_DIR.
* must be located in the directory specified by the REALME_CERT_DIR environment variable. These filenames used to
* be the same as the files as found on the RealMe Developers website, within the 'Integration Bundle' ZIP files
* for the different environments (MTS, ITE and Production), however these filenames are now very generic so there
* is documentation in the README to ensure the filenames are configured correctly for the various environments.
*/
private static $idp_x509_cert_filenames = array(
self::ENV_MTS => array(
self::TYPE_LOGIN => 'mts_login_saml_idp.cer',
self::TYPE_ASSERT => 'mts_assert_saml_idp.cer'
),

// As of the 2021 Azure re-platforming, ITE certificates are the same - a single cert for both logon and assert
self::ENV_ITE => array(
self::TYPE_LOGIN => 'ite.signing.logon.realme.govt.nz.cer',
self::TYPE_ASSERT => 'ite.signing.account.realme.govt.nz.cer'
self::TYPE_ASSERT => 'ite.signing.logon.realme.govt.nz.cer'
),

self::ENV_PROD => array(
self::TYPE_LOGIN => 'signing.logon.realme.govt.nz.cer',
self::TYPE_ASSERT => 'signing.account.realme.govt.nz.cer'
Expand Down

0 comments on commit ffcfcc7

Please sign in to comment.