WindowsLiveLogin Class Reference

List of all members.

Public Member Functions

• __construct ($appid=null, $secret=null, $securityalgorithm=null)

  Initialize the WindowsLiveLogin module with the application ID, secret key and security algorithm.
  

• decodeToken ($token)

  Decode the given token.
  

• getAppId ()

  Returns the application ID.
  

• getAppLoginUrl ($siteid=null, $ip=null, $js=null)

  Returns the URL needed to retrieve the application security token.
  

• getAppRetCode ()

  Returns a string that can be passed to the GetTrustedParams function as the 'retcode' parameter.
  

• getAppSecurityToken ($siteid=null, $ip=null)

  Retrieves the application security token for application verification from the application login URL.
  

• getAppVerifier ($ip=null)

  Generates an Application Verifier token.
  

• getBaseUrl ()

  Get the base URL to use for the Windows Live Login server.
  

• getClearCookieResponse ()

  When a user signs out of Windows Live or a Windows Live application, a best-effort attempt is made at signing out the user from all other Windows Live applications the user might be logged in to.
  

• getLoginUrl ($context=null)

  Returns the sign-in URL to use for Windows Live Login.
  

• getLogoutUrl ()

  Returns the sign-out URL to use for Windows Live Login.
  

• getSecureUrl ()

  Get the secure (HTTPS) URL to use for the Windows Live Login server.
  

• getSecurityAlgorithm ()

  Get the version of the security algorithm being used.
  

• getTrustedLoginUrl ()

  Returns the trusted sign-in URL to use for Windows Live Login.
  

• getTrustedLogoutUrl ()

  Returns the trusted sign-out URL to use for Windows Live Login.
  

• getTrustedParams ($user, $retcode=null)

  Returns a table of key-value pairs that must be posted to the login URL for trusted login.
  

• getTrustedToken ($user)

  Returns the trusted login token in the format needed by the trusted login gadget.
  

• processLogin ($query)

  Processes the login response from Windows Live Login.
  

• processToken ($token, $context=null)

  Decodes and validates a Web Authentication token.
  

• setAppId ($appid)

  Use this method to set your application ID if you did not provide one at initialization time.
  

• setBaseUrl ($baseurl)

  Set the base URL to use for the Windows Live Login server.
  

• setDebug ($debug)

  Stub implementation for logging errors.
  

• setSecret ($secret)

  You can use this method to set your secret key if one was not provided at initialization time.
  

• setSecureUrl ($secureurl)

  Set the secure (HTTPS) URL to use for the Windows Live Login server.
  

• setSecurityAlgorithm ($securityalgorithm)

  Set the version of the security algorithm being used.
  

• signToken ($token)

  Creates a signature for the given string by using the signature key.
  

• validateToken ($token)

  Extracts the signature from the token and validates it.
  

Static Public Member Functions

• static initFromXml ($settingsFile)

  Initialize the WindowsLiveLogin module from a settings file.
  

Private Member Functions

• debug ($string)

  Stub implementation for logging errors.
  

• derive ($secret, $prefix)

  Derive the key, given the secret key and prefix as described in the SDK documentation.
  

• e64 ($input)

  Base64-encode and URL-escape a string.
  

• fatal ($string)

  Stub implementation for handling a fatal error.
  

• fetch ($url)

  Fetch the contents given a URL.
  

• getTimestamp ()

  Generates a timestamp suitable for the application verifier token.
  

• parse ($input)

  Helper method to parse query string and return a table representation of the key and value pairs.
  

• parseSettings ($settingsFile)
• u64 ($input)

  URL-unescape and Base64-decode a string.
  

Private Attributes

• $_appid
• $_baseurl
• $_cryptkey
• $_debug = false
• $_secureurl
• $_securityalgorithm
• $_signkey

---

Constructor & Destructor Documentation

WindowsLiveLogin::__construct	(	$	appid = null,
		$	secret = null,
		$	securityalgorithm = null
	)

Initialize the WindowsLiveLogin module with the application ID, secret key and security algorithm.

We recommend that you employ strong measures to protect the secret key. The secret key should never be exposed to the Web or other users.

Be aware that if you do not supply these settings at initialization time, you may need to set the application ID, secret key and security algorithm using the appropriate setters.

---

Member Function Documentation

WindowsLiveLogin::debug

(

$

string

)

[private]

Stub implementation for logging errors.

By default, this function does nothing if the debug flag has not been set with setDebug. Otherwise, errors are logged using the PHP error_log function.

References $string, and _debug().

WindowsLiveLogin::decodeToken

(

$

token

)

Decode the given token.

Returns null on failure.

First, the string is URL unescaped and base64 decoded. Second, the IV is extracted from the first 16 bytes the string. Finally, the string is decrypted by using the encryption key.

References $len, $mode, $token, and debug().

WindowsLiveLogin::derive	(	$	secret,
		$	prefix
	)			[private]

Derive the key, given the secret key and prefix as described in the SDK documentation.

References $key, $prefix, and debug().

WindowsLiveLogin::e64

(

$

input

)

[private]

Base64-encode and URL-escape a string.

References $input.

WindowsLiveLogin::fatal

(

$

string

)

[private]

Stub implementation for handling a fatal error.

References $string, and debug().

WindowsLiveLogin::fetch

(

$

url

)

[private]

Fetch the contents given a URL.

References $contents, $handle, $url, and debug().

WindowsLiveLogin::getAppId

(

)

Returns the application ID.

WindowsLiveLogin::getAppLoginUrl	(	$	siteid = null,
		$	ip = null,
		$	js = null
	)

Returns the URL needed to retrieve the application security token.

By default, the application security token will be generated for the Windows Live site; a specific Site ID can optionally be specified in 'siteid'. The IP address can also optionally be included in 'ip'.

If 'js' is false, then JavaScript Output Notation (JSON) output is returned:

{"token":"<value>"}

Otherwise, a JavaScript response is returned. It is assumed that WLIDResultCallback is a custom function implemented to handle the token value:

WLIDResultCallback("<tokenvalue>");

References $ip, $js, and $url.

WindowsLiveLogin::getAppRetCode

(

)

Returns a string that can be passed to the GetTrustedParams function as the 'retcode' parameter.

If this is specified as the 'retcode', then the app will be used as return URL after it finishes trusted login.

WindowsLiveLogin::getAppSecurityToken	(	$	siteid = null,
		$	ip = null
	)

Retrieves the application security token for application verification from the application login URL.

By default, the application security token will be generated for the Windows Live site; a specific Site ID can optionally be specified in 'siteid'. The IP address can also optionally be included in 'ip'.

Implementation note: The application security token is downloaded from the application login URL in JSON format {"token":"<value>"}, so we need to extract

from the string and return it as seen here.

References $body, $ip, $matches, count, debug(), and fetch().

WindowsLiveLogin::getAppVerifier

(

$

ip = null

)

Generates an Application Verifier token.

An IP address can be included in the token.

References $ip, and $token.

WindowsLiveLogin::getBaseUrl

(

)

Get the base URL to use for the Windows Live Login server.

You should not have to use this. Furthermore, we recommend that you use the Sign In control instead of the URL methods provided here.

WindowsLiveLogin::getClearCookieResponse

(

)

When a user signs out of Windows Live or a Windows Live application, a best-effort attempt is made at signing out the user from all other Windows Live applications the user might be logged in to.

This is done by calling the handler page for each application with 'action' set to 'clearcookie' in the query string. The application handler is then responsible for clearing any cookies or data associated with the login. After successfully logging out the user, the handler should return a GIF (any GIF) as response to the action=clearcookie query.

This function returns an appropriate content type and body response that the application handler can return to signify a successful sign-out from the application.

References $content, and $type.

WindowsLiveLogin::getLoginUrl

(

$

context = null

)

Returns the sign-in URL to use for Windows Live Login.

We recommend that you use the Sign In control instead.

Parameters:

context

If you specify it, context will be returned as-is in the login response for site-specific use.

References $context, and $url.

WindowsLiveLogin::getLogoutUrl

(

)

Returns the sign-out URL to use for Windows Live Login.

We recommend that you use the Sign In control instead.

WindowsLiveLogin::getSecureUrl

(

)

Get the secure (HTTPS) URL to use for the Windows Live Login server.

You should not have to use this.

WindowsLiveLogin::getSecurityAlgorithm

(

)

Get the version of the security algorithm being used.

WindowsLiveLogin::getTimestamp

(

)

[private]

Generates a timestamp suitable for the application verifier token.

WindowsLiveLogin::getTrustedLoginUrl

(

)

Returns the trusted sign-in URL to use for Windows Live Login.

WindowsLiveLogin::getTrustedLogoutUrl

(

)

Returns the trusted sign-out URL to use for Windows Live Login.

WindowsLiveLogin::getTrustedParams	(	$	user,
		$	retcode = null
	)

Returns a table of key-value pairs that must be posted to the login URL for trusted login.

Use HTTP POST to do this. Be aware that the values in the table are neither URL nor HTML escaped and may have to be escaped if you are inserting them in code such as an HTML form.

User to be trusted on the local site is passed in as string 'user'.

Optionally, 'retcode' specifies the resource to which successful login is redirected, such as Windows Live Mail, and is typically a string in the format 'id=2000'. If you pass in the value from GetAppRetCode instead, login will be redirected to the application. Otherwise, an HTTP 200 response is returned.

References $params, $token, and $user.

WindowsLiveLogin::getTrustedToken

(

$

user

)

Returns the trusted login token in the format needed by the trusted login gadget.

User to be trusted on the local site is passed in as string 'user'.

References $token, $user, and debug().

static WindowsLiveLogin::initFromXml

(

$

settingsFile

)

[static]

Initialize the WindowsLiveLogin module from a settings file.

'settingsFile' specifies the location of the XML settings file containing the application ID, secret key, and an optional security algorithm. The file is of the following format:

<windowslivelogin> <appid>APPID</appid> <secret>SECRET</secret> <securityalgorithm>wsignin1.0</securityalgorithm> </windowslivelogin>

We recommend that you store the Windows Live Login settings file in an area on your server that cannot be accessed through the Internet. This file contains important confidential information.

References $o, and $settings.

Referenced by _get_wll().

WindowsLiveLogin::parse

(

$

input

)

[private]

Helper method to parse query string and return a table representation of the key and value pairs.

References $input, count, and debug().

WindowsLiveLogin::parseSettings

(

$

settingsFile

)

[private]

References $debug, and $settings.

WindowsLiveLogin::processLogin

(

$

query

)

Processes the login response from Windows Live Login.

Parameters:

query

contains the preprocessed POST query, a map of Strings to an an array of Strings, such as that returned by ServletRequest.getParameterMap().

Returns:

a User object on successful login; otherwise null.

References $action, $context, $query, $token, and debug().

WindowsLiveLogin::processToken	(	$	token,
		$	context = null
	)

Decodes and validates a Web Authentication token.

Returns a User object on success. If a context is passed in, it will be returned as the context field in the User object.

References $context, $token, $user, debug(), null, and parse().

WindowsLiveLogin::setAppId

(

$

appid

)

Use this method to set your application ID if you did not provide one at initialization time.

WindowsLiveLogin::setBaseUrl

(

$

baseurl

)

Set the base URL to use for the Windows Live Login server.

You should not have to change this. Furthermore, we recommend that you use the Sign In control instead of the URL methods provided here.

WindowsLiveLogin::setDebug

(

$

debug

)

Stub implementation for logging errors.

If you want to enable debugging output, set this to true. In this implementation errors will be logged using the PHP error_log function.

References $debug, and _debug().

WindowsLiveLogin::setSecret

(

$

secret

)

You can use this method to set your secret key if one was not provided at initialization time.

WindowsLiveLogin::setSecureUrl

(

$

secureurl

)

Set the secure (HTTPS) URL to use for the Windows Live Login server.

You should not have to change this.

WindowsLiveLogin::setSecurityAlgorithm

(

$

securityalgorithm

)

Set the version of the security algorithm being used.

WindowsLiveLogin::signToken

(

$

token

)

Creates a signature for the given string by using the signature key.

References $token, and debug().

WindowsLiveLogin::u64

(

$

input

)

[private]

URL-unescape and Base64-decode a string.

References $input.

WindowsLiveLogin::validateToken

(

$

token

)

Extracts the signature from the token and validates it.

References $body, $sig, $token, count, debug(), and cluster::list.

---

Member Data Documentation

WindowsLiveLogin::$_appid [private]

WindowsLiveLogin::$_baseurl [private]

WindowsLiveLogin::$_cryptkey [private]

WindowsLiveLogin::$_debug = false [private]

WindowsLiveLogin::$_secureurl [private]

WindowsLiveLogin::$_securityalgorithm [private]

WindowsLiveLogin::$_signkey [private]

---

The documentation for this class was generated from the following file:

• modules/winliveid/windowslivelogin.php