During user registration several HTTP-queries can be utilized to enrich user identity using information retrieved from external systems, e.g. CRM. The response messages are expected to contain XML formatted data in UTF-8 encoding. 

Requests may include data from the ongoing registration that user has already given or other parameters such as the user interface language code. Backend calls are only used during registration workflows to

1. validate the information that the user has given
2. enrich user information based on input
3. workflow control

A backend response may include a status code, error message and information about the user (attributes, roles etc.)

Validation of user input

User input is communicated to the backend system as HTTP URL parameters. The backend system communicates validation result as HTTP status code or as a status code within the backend response XML message.

Enrichment based on user input

Enrichment is an extension to validation of user input. Ubisecure CustomerID may display messages, store user attributes, create and modify organization entities, create roles and create role assignments based on information communicated in the backend response XML message.

Workflow control

The backend system may control the registration workflow with status codes. Currently supported controls are ERROR, STOP and OK. ERROR indicates any errors in the user input and the user is allowed to correct any input. STOP causes the registration workflow to terminate. OK allows workflow to proceed normally.

XML format 

Support for fetching simple name-value pairs from the response XML message can be done with XPath expressions. Output parameters for a backend configuration should be configured in the file backend.properties.

Support for processing more structural information is implemented with Ubisecure CustomerID backend response XML schema. If the backend server does not natively support Ubisecure CustomerID XML schema, it is possible to apply a XSLT transformation to convert the message from backend format to Ubisecure CustomerID XML document.

Example of a Backend Request and a Response

Request (HTTP GET): 

http://localhost:7080/backend?Email=user@test.com&AccountNumber=111&authcode=123&locale=fi

Response:

<customer>
	<firstname>User</firstname>
	<lastname>Test</lastname>
	<contract>123456</contract>
	<status>OK</status>
	<error></error>
</customer>

Ubisecure CustomerID XML Schema

Ubisecure CustomerID XML Schema can be used to import more complicated user data to the system when the XPath based parsing is insufficient. The backend response schema supports a wide range of operations for adding information to the Ubisecure CustomerID database. A high level overview of the XML schema is shown below. Please refer to messages.xsd and importer.xsd for exact details. Package can be downloaded from Ubisecure Extranet (CustomerID-XML-schema.zip).

A response document contains a root response element with children:

<m:Response> 
	<Add .../> 
	<Modify .../> 
	<Remove .../> 
	<m:Control status=""> 
		<m:Message .../> 
		<m:Action> 
			<m:Parameter .../> 
		</m:Action> 
	</m:Control> 
</m:Response>

Status Codes 

The status-attribute of the Control element in XML response can be used to control the workflow as described above.

<m:Response> 
	<m:Control status="ok|stop|error|internal_error"/> 
</m:Response>

Displaying Messages 

A message for the user can be included in the Control-element of the response with localization

<m:Response> 
	<m:Control> 
		<m:Message xml:lang="en">Invalid username</m:Message> 
	</m:Control>
</m:Response> 

The message will be shown as an error message when the data given by the user did not pass validation.

Storing User Attributes

The backend response can alter user attributes in the ongoing registration process. This can be achieved with one or more Action-elements in the Control-element which can contain information about the user as follows: 

<m:Response> 
	<m:Control> 
		<m:Action> 
			<m:Parameter name="user.firstname"> 
				<Value>Firstname</Value> 
			</m:Parameter> 
		</m:Action> 
	</m:Control> 
</m:Response> 

Or using the Modify operation element with current-user in the type attribute:

<m:Response> 
<Modify type="current-user"> 
<Replace name="firstname"> 
<Value>Firstname</Value> 
</Replace> 
</Modify> 
</m:Response>

Create Roles and Create Role Assignments 

The Ubisecure CustomerID XML schema supports several operations which alter the database. In addition to aforementioned Modify, the Add operation can be used to create roles in the system as follows:

<m:Response> 
	<Add type="role" entityName="Company/Admin" errorAction="continue"/> 
	<Modify type="current-user"> 
		<Add name="role"> 
			<Role>Company/Admin</Role> 
		</Add> 
	</Modify> 
</m:Response> 

And in conjunction with the Modify operation roles created can be assigned to the user registering to Ubisecure CustomerID.

Create Organizations 

As seen above the Add element has a type attribute. The attribute defines the type of the entity, which will be created. In addition to roles organizations can be created similarly:

<m:Response> 
	<Add type="organization" entityName="Company" errorAction="continue">
		<Attribute name="friendlyName"> 
		<Value>Example Friendly Name</Value> 
		</Attribute>
		<Attribute name="customattribute">
		<Value>Attribute value</Value>
		</Attribute>
	</Add>
</m:Response>

The errorAction attribute defines a control flow instruction. The Add statement fails with error and causes processing to stop if the entity already exists. With errorAction="continue" the error is ignored and processing continues with the next statement. 

XSLT Transformation 

Refer to http://www.w3.org/TR/xslt for complete details of the XSLT language. Command Line Transformation Utility (msxsl.exe) can be used to test XSL transformation. http://www.microsoft.com/en-us/download/details.aspx?id=21714

Defining the XSLT Document for Backend

Path to the XSLT document to be used in with a specific backend is configured in the backend.properties as follows:

customerdata.transform = <path-to-xslt-document>

Input Parameters and HTTP Status Code 

The input parameters that are communicated to the backend and the HTTP status of the backend response are available as top-level parameters to the stylesheet. 
Parameter namespaces:

• Input parameters 
  http://schema.ubisecure.com/customerid/messages#input  
• HTTP status 
  http://schema.ubisecure.com/customerid/messages#http  

Input parameter names are defined by the input configuration entry in backend.properties.
Example:

customerdata.input = { "user.email": "Email", "user.accountnumber": "AccountNumber" }

defines input parameter names "Email" and "AccountNumber" 
HTTP status parameter names:  

• statusCode 
  the numeric http status code: 200, 401 etc 
• statusMessage 
  http status text: "OK", "Not Found", etc. 
• URI 
  the url of the request 

 Example:

<xsl:stylesheet version="1.0" 
	xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
	xmlns="http://schema.ubisecure.com/customerid/importer" 
	xmlns:m="http://schema.ubisecure.com/customerid/messages" 
	xmlns:http="http://schema.ubisecure.com/customerid/messages#http" 
	xmlns:input="http://schema.ubisecure.com/customerid/messages#input" 
> 
<xsl:param name="http:statusCode" /> 
<xsl:param name="input:Email" /> 
<xsl:param name="input:AccountNumber" /> 
<xsl:template match="/"> 
		<xsl:choose> 
			<xsl:when test="$http:statusCode != 200"> 
				<m:Response> 
					<m:Control status="INTERNAL_ERROR" /> 
				</m:Response> 
			</xsl:when> 
				<xsl:otherwise> 
				<xsl:call-template name="response" /> 
			</xsl:otherwise> 
		</xsl:choose> 
	</xsl:template> 
	<xsl:template name="response"> 
	... 
	</xsl:template> 
</xsl:stylesheet>