class RealMeService implements TemplateGlobalProvider (View source)

Traits

Provides extensions to this object to integrate it with standard config API methods.

A class that can be instantiated or replaced via DI

Constants

ENV_MTS

Current RealMe supported environments.

ENV_ITE

ENV_PROD

TYPE_LOGIN

SAML binding types

TYPE_ASSERT

AUTHN_LOW_STRENGTH

the valid AuthN context values for each supported RealMe environment.

AUTHN_MOD_STRENTH

AUTHN_MOD_MOBILE_SMS

AUTHN_MOD_TOKEN_SID

ERR_TIMEOUT

Realme SAML2 error status constants

ERR_INTERNAL_ERROR

ERR_AUTHN_FAILED

SAML2 Error constants used for business logic and switching error messages

ERR_UNKNOWN_PRINCIPAL

ERR_NO_AVAILABLE_IDP

ERR_NO_PASSIVE

ERR_NO_AUTHN_CONTEXT

ERR_REQUEST_UNSUPPORTED

ERR_REQUEST_DENIED

ERR_UNSUPPORTED_BINDING

Config options

sync_with_local_member_database bool
user_data User|null
realme_env string
allowed_realme_environments array
integration_type string
allowed_realme_integration_types
sp_entity_ids array
idp_entity_ids array
idp_sso_service_urls
idp_x509_cert_filenames array
authn_contexts array
allowed_authn_context_list
metadata_assertion_service_domains array
realme_error_message_overrides array
metadata_organisation_name string|null
metadata_organisation_display_name string|null
metadata_organisation_url string|null
metadata_contact_support_company string|null
metadata_contact_support_firstnames string|null
metadata_contact_support_surname string|null

Properties

Methods

public static 
config()

Get a configuration accessor for this class. Short hand for Config::inst()->get($this->class, .....).

public
mixed
uninherited(string $name)

Gets the uninherited value for the given config option

public static 
create(mixed ...$args)

An implementation of the factory method, allows you to create an instance of a class

public static 
singleton(string $class = null)

Creates a class instance by the "singleton" design pattern.

public static 
array
protected static 
getRequest()

No description

public static 
user_data()

Return the user data which was saved to session from the first RealMe auth.

public
getUserData()

No description

public static 
current_realme_user()

Calls available user data and checks for validity

public static 
currentRealMeUser()

A helpful static method that follows SilverStripe naming for Member::currentUser();

public
bool|null
enforceLogin(HTTPRequest $request, string $backUrl = null)

Enforce login via RealMe. This can be used in controllers to force users to be authenticated via RealMe (not necessarily logged in as a Member), in the form of:

Session::set('RealMeBackURL', '/path/to/the/controller/method');
if($service->enforceLogin()) {
    // User has a valid RealMe account, $service->getAuthData() will return you their details
} else {
    // Something went wrong processing their details, show an error
}

public
bool
isAuthenticated()

Checks data stored in Session to see if the user is authenticated.

public
User|null
getAuthData()

Returns a RealMeUser object if one can be built from the RealMe session data.

public
void
clearLogin(HTTPRequest $request)

Clear the RealMe credentials from Session, called during Security->logout() overrides

public
getLastError()

No description

public
string
getBackURL(HTTPRequest $request)

No description

public
getErrorBackURL(HTTPRequest $request)

No description

public
string|null
getCertDir(string $subdir = null)

No description

public
string|null
getAuthnContextForEnvironment(string $env)

Returns the appropriate AuthN Context, given the environment passed in. The AuthNContext may be different per environment, and should be one of the strings as defined in the static self::$authn_contexts at the top of this class.

public
string|null
getSigningCertPath()

Returns the full path to the SAML signing certificate file, used by SimpleSAMLphp to sign all messages sent to RealMe.

public
getIdPCertPath()

No description

public
getSPCertContent($contentType = 'certificate')

No description

public
getIdPCertContent()

No description

public
string|null
getCertificateContents(string $certPath, string $contentType = 'certificate')

Returns the content of the SAML signing certificate. This is used by getAuth() and by RealMeSetupTask to produce metadata XML files.

public
string|null
getAssertionConsumerServiceUrlForEnvironment(string $env)

No description

public
string|null
getMetadataOrganisationName()

No description

public
string|null
public
string|null
getMetadataOrganisationUrl()

No description

public
string[]
getMetadataContactSupport()

No description

public
array
getAllowedRealMeEnvironments()

The list of RealMe environments that can be used. By default, we allow mts, ite and production.

public
array
getAllowedAuthNContextList()

The list of valid realme AuthNContexts

public
string|null
getSPEntityID()

Returns the appropriate entity ID for RealMe, given the environment passed in. The entity ID may be different per environment, and should be a full URL, including privacy realm and application name. For example, this may be: https://www.agency.govt.nz/privacy-realm-name/application-name

public
Auth
getAuth(HTTPRequest $request = null)

Returns the internal Auth object against which visitors are authenticated.

public
string
getNameIdFormat()

No description

Details

static Config_ForClass config()

Get a configuration accessor for this class. Short hand for Config::inst()->get($this->class, .....).

Return Value

Config_ForClass

mixed uninherited(string $name)

Gets the uninherited value for the given config option

Parameters

string $name

Return Value

mixed

static Injectable create(mixed ...$args)

An implementation of the factory method, allows you to create an instance of a class

This method will defer class substitution to the Injector API, which can be customised via the Config API to declare substitution classes.

This can be called in one of two ways - either calling via the class directly, or calling on Object and passing the class name as the first parameter. The following are equivalent: $list = DataList::create(SiteTree::class); $list = SiteTree::get();

Parameters

mixed ...$args

Return Value

Injectable

static Injectable singleton(string $class = null)

Creates a class instance by the "singleton" design pattern.

It will always return the same instance for this class, which can be used for performance reasons and as a simple way to access instance methods which don't rely on instance data (e.g. the custom SilverStripe static handling).

Parameters

string $class

Optional classname to create, if the called class should not be used

Return Value

Injectable

The singleton instance

static array get_template_global_variables()

No description

Return Value

array

Returns an array of items. Each key => value pair is one of three forms:

  • template name (no key)
  • template name => method name
  • template name => [], where the array can contain these key => value pairs
    • "method" => method name
    • "casting" => casting class to use (i.e., Varchar, HTMLFragment, etc)

static protected HTTPRequest|null getRequest()

No description

Return Value

HTTPRequest|null

static User user_data()

Return the user data which was saved to session from the first RealMe auth.

Note: Does not check authenticity or expiry of this data

Return Value

User

getUserData()

No description

static User current_realme_user()

Calls available user data and checks for validity

Return Value

User

static User currentRealMeUser()

A helpful static method that follows SilverStripe naming for Member::currentUser();

Return Value

User

bool|null enforceLogin(HTTPRequest $request, string $backUrl = null)

Enforce login via RealMe. This can be used in controllers to force users to be authenticated via RealMe (not necessarily logged in as a Member), in the form of:

Session::set('RealMeBackURL', '/path/to/the/controller/method');
if($service->enforceLogin()) {
    // User has a valid RealMe account, $service->getAuthData() will return you their details
} else {
    // Something went wrong processing their details, show an error
}

In cases where people are not authenticated with RealMe, this method will redirect them directly to RealMe.

However, generally you want this to be an explicit process, so you should look at instead using the standard RealMeAuthenticator.

A return value of bool false indicates that there was a failure during the authentication process (perhaps a communication issue, or a failure to decode the response correctly. You should handle this like you would any other unexpected authentication error. You can use getLastError() to see if a human-readable error message exists for display to the user.

Parameters

HTTPRequest $request
string $backUrl

Return Value

bool|null

true if the user is correctly authenticated, false if there was an error with login

Exceptions

Error

bool isAuthenticated()

Checks data stored in Session to see if the user is authenticated.

Return Value

bool

true if the user is authenticated via RealMe and we can trust ->getUserData()

User|null getAuthData()

Returns a RealMeUser object if one can be built from the RealMe session data.

Return Value

User|null

Exceptions

Error
Exception

void clearLogin(HTTPRequest $request)

Clear the RealMe credentials from Session, called during Security->logout() overrides

Parameters

HTTPRequest $request

Return Value

void

getLastError()

No description

string getBackURL(HTTPRequest $request)

No description

Parameters

HTTPRequest $request

Return Value

string

A BackURL as specified originally when accessing /Security/login, for use after authentication

getErrorBackURL(HTTPRequest $request)

No description

Parameters

HTTPRequest $request

string|null getCertDir(string $subdir = null)

No description

Parameters

string $subdir

A sub-directory where certificates may be stored for a specific case

Return Value

string|null

Either the directory where certificates are stored, or null if undefined

string|null getAuthnContextForEnvironment(string $env)

Returns the appropriate AuthN Context, given the environment passed in. The AuthNContext may be different per environment, and should be one of the strings as defined in the static self::$authn_contexts at the top of this class.

Parameters

string $env

The environment to return the AuthNContext for. Must be one of the RealMe environment names

Return Value

string|null

Returns the AuthNContext for the given $env, or null if no context exists

string|null getSigningCertPath()

Returns the full path to the SAML signing certificate file, used by SimpleSAMLphp to sign all messages sent to RealMe.

Return Value

string|null

Either the full path to the SAML signing certificate file, or null if it doesn't exist

getIdPCertPath()

No description

getSPCertContent($contentType = 'certificate')

No description

Parameters

$contentType

getIdPCertContent()

No description

string|null getCertificateContents(string $certPath, string $contentType = 'certificate')

Returns the content of the SAML signing certificate. This is used by getAuth() and by RealMeSetupTask to produce metadata XML files.

Parameters

string $certPath

The filesystem path to where the certificate is stored on the filesystem

string $contentType

Either 'certificate' or 'key', depending on which part of the file to return

Return Value

string|null

The content of the signing certificate

string|null getAssertionConsumerServiceUrlForEnvironment(string $env)

No description

Parameters

string $env

The environment to return the entity ID for. Must be one of the RealMe environment names

Return Value

string|null

Either the assertion consumer service location, or null if information doesn't exist

string|null getMetadataOrganisationName()

No description

Return Value

string|null

The organisation name to be used in metadata XML output, or null if none exists

string|null getMetadataOrganisationDisplayName()

No description

Return Value

string|null

The organisation display name to be used in metadata XML output, or null if none exists

string|null getMetadataOrganisationUrl()

No description

Return Value

string|null

The organisation website URL to be used in metadata XML output, or null if none exists

string[] getMetadataContactSupport()

No description

Return Value

string[]

The support contact details to be used in metadata XML output, with null values if they don't exist

array getAllowedRealMeEnvironments()

The list of RealMe environments that can be used. By default, we allow mts, ite and production.

Return Value

array

array getAllowedAuthNContextList()

The list of valid realme AuthNContexts

Return Value

array

string|null getSPEntityID()

Returns the appropriate entity ID for RealMe, given the environment passed in. The entity ID may be different per environment, and should be a full URL, including privacy realm and application name. For example, this may be: https://www.agency.govt.nz/privacy-realm-name/application-name

Return Value

string|null

Returns the entity ID for the current environment, or null if no entity ID exists

Auth getAuth(HTTPRequest $request = null)

Returns the internal Auth object against which visitors are authenticated.

Parameters

HTTPRequest $request

Return Value

Auth

string getNameIdFormat()

No description

Return Value

string

the required NameIDFormat to be included in metadata XML, based on the requested integration type