HID Global
Access Management Services for DigitalPersona Access Management


Web Authentication Policy Service

The goal of the Web Authentication Policy Service (WAPS) is to specify the authentication policy required for a specific user to manage a Resource.

It is implemented as a GUI-less Web Service that can be located inside or outside the firewall, depending on the logic of the specific WAPS implementation. Location inside the firewall is more common since WAPS may need connection to Active Directory, the DigitalPersona Server or other customer Databases.

WAPS can use any protocol the customer chooses for listening. However, it is important that the Service Provider (SP) using WAPS must always have access to it.

WAPS can be hosted in any supported environment and developed using any Web development framework as long as the SP can communicate with it.

Open API schemas

Open API (Swagger) schemas are available here.

IDPWebPolicy interface

The DigitalPersona Web Authentication Policy Service (WAPS) is implemented as a WCF service. The IDPWebPolicy interface has only one method, GetPolicyList(), as described in the next topic.

namespace DPWcfPolicyService
{
	[ServiceContract]
  public interface IDPWebPolicy
  {
  /*
  * Return policy for specific resource, specific user and specific action
  */
	[WebInvoke(Method = "GET",
		ResponseFormat = WebMessageFormat.Json,
		BodyStyle = WebMessageBodyStyle.Wrapped,
		UriTemplate = "GetPolicyList?user={userName}&type={nameType}&uri=
			{resourceUri}&action={action}")]
	List<Policy> GetPolicyList(String userName, UInt16 nameType,
		String resourceUri, ResourceActions action);
	/*
	* Return policy for specific resource, specific user, specific action using
		contextual/behavior information
	*/
	[OperationContract()]
	[WebInvoke(Method = "POST",
		ResponseFormat = WebMessageFormat.Json,
		BodyStyle = WebMessageBodyStyle.Wrapped,
		UriTemplate = "GetPolicyListEx")]
	List<Policy> GetPolicyListEx(String userName, UInt16 nameType, String
		resourceUri, ResourceActions action, ContextualInfo info);
  }
  [DataContract]
  public enum ResourceActions
  {
		[EnumMember]
    Read = 0,
    [EnumMember]
    Write = 1,
    [EnumMember]
		Delete = 2,
    }
	[DataContract]
  public class PolicyElement
  {
  		public PolicyElement(String id)
		{
			cred_id = id;
    }
	[DataMember]
	public String cred_id { get; set; }
    }
	[DataContract]
  public class Policy
  {
		public Policy()
		{
			policy = new List<PolicyElement>();
		}
		[DataMember]
    public List<PolicyElement> policy{ get; set; }
    }
	[DataContract]
	public class ContextualInfo
	{
		[DataMember]
		public Boolean behavior { get; set; }
		[DataMember]
		public Boolean ip { get; set; }
		[DataMember]
		public Boolean device { get; set; }
	 [DataMember]
		public Boolean altusInstalled { get; set; }
		[DataMember]
		public String computer { get; set; }
		[DataMember]
		public String domain { get; set; }
		[DataMember]
		public String user { get; set; }
		[DataMember]
		public Boolean insideFirewall { get; set; }
		[DataMember]
		public Boolean remoteSession { get; set; }
	}
}

Methods

GetPolicyList method

The GetPolicyList() method returns a list of policies representing authentication options; at least one of them must be met in order to access (read, write or delete) the specific Secret of the user.

Syntax

~~~List GetPolicyList(String userName, UInt16 nameType, String resourceUri, ResourceActions action);



<table style="width:95%;margin-left:auto;margin-right:auto;">
  <tr>
    <th style="width:20%" ALIGN="left">Parameter</th>
    <th style="width:35%" ALIGN="left">Description</th>
  </tr>
  <tr>
  <td valign="top">userName</td>
  <td valign="top">The name of the user whose Secret is to be managed.</td>
  </tr>
  <tr>
  <td valign="top">userNameType</td>
  <td valign="top">The format of the user name provided in the userName parameter. See the table [here](user-name-formats) for a detailed description of user name formats.</td>
  </tr>
  <tr>
  <td valign="top">resourceUri</td>
  <td valign="top">	Uri which represent resource to be accessed. For example, a Secret name like “SystemLogonInfo.”
  </td>
  </tr>  
  <tr>
  <td valign="top">action</td>
  <td valign="top">The action requested for this resource. Currently the following actions are supported: 1) Read, 2) Write and 3) Delete.</td>
  </tr>       
</table>

#### Returns  

Returns a list of policies of which one must be met in order to access the resource.  

#### Notes  

GetPolicyList () should be implemented as HTTP GET using JSON as the response format.
The following is an example of using GetPolicyList().  

~~~http://www.mycompany.com/DPWebPolicy/DPWebPolicyService.svc/GetPolicyList?
user=someone@mycompany.com&type=6&uri=SystemLogonInfo&action=Read

This URL requests a list of policies required to read a secret with the name SystemLogonInfo, which belongs to a user with the name someone@mycompany.com.

The example response would be the following.

{"GetPolicyListResult":
	[
		{"policy":[
			{"cred_id":"AC184A13-60AB-40e5-A514-E10F777EC2F9"},
			{"cred_id":"8A6FCEC3-3C8A-40c2-8AC0-A039EC01BA05"}
		]},
		{"policy":[
			{"cred_id":"AC184A13-60AB-40e5-A514-E10F777EC2F9"},
			{"cred_id":"E750A180-577B-47f7-ACD9-F89A7E27FA49"}
		]}
	]
}

This response means that the user someone@mycompany.com needs to provide “Fingerprint AND PIN” or “Fingerprint AND Bluetooth” to be allowed to read the SystemLogonInfo Secret.

GetPolicyListEx method

The GetPolicyListEx() method is an extension of the GetPolicyList() method which adds Contextual/Behavior information and returns a list of policies which are authentication options of which at least one must met in order to access (read, write or delete) the specific Secret of the specific user.

Syntax 

List<Policy> GetPolicyListEx(User user, String resourceUri, ResourceActions
action, ContextualInfo info);
Parameter Description
userName The name of the user whose Secret is to be managed.
resourceUri AUri which represents the resource to be accessed. For example, a Secret name like “SystemLogonInfo.”
action The action requested for this resource. Currently the following actions are supported: 1) Read, 2) Write and 3) Delete.
info Contextual/Behavior information provided (see detailed description below).

Returns

Returns a list of policies of which one must be met to access the resource.

Examples

GetPolicyListEx () should be implemented as HTTP POST using JSON as response format. The following is an example of the use of GetPolicyListEx().

http://www.digitalpersona.com/DPWebPolicy/DPWebPolicyService.svc/GetPolicyListEx

Below is an example of an HTTP request body.

{
	"user":{"name":"someone@mycompany","type":6},
	"resourceUri":"SystemLogonInfo",
	"action":1,
	"info":
	{
		"behavior":true,
		"ip":true,
		"device":true,
		"altusInstalled":true,
		"computer":"computername.mycompany.net",
		"domain":"mycompany.net",
		"user":"someone@mycompany.com",
		"insideFirewall":true,
		"remoteSession":false
	}
}

This URL requests the policies required to read a secret (in this example Secret is requested resource) with the name SystemLogonInfo which belongs to a user with the name someone@mycompany.com.

The example response would be the following.

{"GetPolicyListExResult":
	[
		{"policy":[
			{"cred_id":"AC184A13-60AB-40e5-A514-E10F777EC2F9"},
			{"cred_id":"8A6FCEC3-3C8A-40c2-8AC0-A039EC01BA05"}
		]},
		{"policy":[
			{"cred_id":"AC184A13-60AB-40e5-A514-E10F777EC2F9"},
			{"cred_id":"E750A180-577B-47f7-ACD9-F89A7E27FA49"}
		]}
	]
}

This response means that the user someone@mycompany.com needs to provide “Fingerprint AND PIN” or “Fingerprint AND Bluetooth” to be allowed to read the SystemLogonInfo Secret.

Data Contracts

ResourceActions enumerator

ResourceActions enumerates the possible actions the caller may apply to a particular resource.

public enum ResourceActions
{
	[EnumMember]
	Read = 0,
  [EnumMember]
  Write = 1,
  [EnumMember]
  Delete = 2,
}

We support only three actions in this version of WAPS.

  • Read
  • Write
  • Delete

PolicyElement class

The PolicyElement class describes one policy element.

public class PolicyElement
{
	public PolicyElement(String id)
  {
	  cred_id = id;
  }
  [DataMember]
  public String cred_id { get; set; }
}
Parameter Description
cred_id The unique Id of a credential.

The following credentials are supported.

Credential GUID
User password {D1A1F561-E14A-4699-9138-2EB523E132CC}
Fingerprints {AC184A13-60AB-40e5-A514-E10F777EC2F9}
PIN {8A6FCEC3-3C8A-40c2-8AC0-A039EC01BA05}
Smart Cards {D66CC98D-4153-4987-8EBE-FB46E848EA98}
Proximity cards {1F31360C-81C0-4EE0-9ACD-5A4400F66CC2}
Contactless cards {7BF3E290-5BA5-4C2D-AA33-24B48C189399}
Recovery Questions {B49E99C6-6C94-42DE-ACD7-FD6B415DF503}
Bluetooth {E750A180-577B-47f7-ACD9-F89A7E27FA49}
?? MISSING CREDENTIAS ??

Below is an example of JSON representation of a fingerprint credential. The relationship between policy elements within one policy is AND. Note that we must use “braceless” GUID representation in our API in URLs and JSON representation.

{"cred_id":"AC184A13-60AB-40e5-A514-E10F777EC2F9"}

Policy class

This class describes one authentication policy. To access a particular resource, multiple authentication policies could be applied. In this case the relationship between the authentication policies would be OR.

public class Policy
{
	public Policy()
  {
	  policy = new List<PolicyElement>();
  }
  [DataMember]
  public List<PolicyElement> policy{ get; set; }
}

Below is an example of the JSON representation of a policy. This policy describes an authentication policy which requires “Fingerprint AND PIN” credentials to be provided.

{"policy":[
	{"cred_id":"AC184A13-60AB-40e5-A514-E10F777EC2F9"},
	{"cred_id":"8A6FCEC3-3C8A-40c2-8AC0-A039EC01BA05"}
]},

ContextualInfo class

This class describes Contextual/Behavior information.

[DataContract]
public class ContextualInfo
{
	[DataMember]
	public Boolean behavior { get; set; }
	[DataMember]
	public Boolean ip { get; set; }
	[DataMember]
	public Boolean device { get; set; }
	[DataMember]
	public Boolean altusInstalled { get; set; }
	[DataMember]
	public String computer { get; set; }
	[DataMember]
	public String domain { get; set; }
	[DataMember]
	public String user { get; set; }
	[DataMember]
	public Boolean insideFirewall { get; set; }
	[DataMember]
	public Boolean remoteSession { get; set; }
    }
Parameter Description
behavior Boolean value which is true if user behavior is matched, false otherwise.
ip Boolean value which is true if user IP is matched with the trained data, false otherwise.
device Boolean value which is true if user device is matched with the trained data, false otherwise.
altusInstalled Boolean value which is true if DigitalPersona client software is installed on client machine, false otherwise.
computer DNS name of the client machine.
domain AD domain client computer belongs to.
user UPN name of the user currently logged on client machine.
insideFirewall Boolean value which is true if client machine located inside corporate firewall, false otherwise.
remoteSession Boolean value which is true user access client machine remotely, false otherwise.

Below is an example of the JSON representation of ContextualInfo.

{
	"behavior":true,
	"ip":true,
	"device":true,
	"altusInstalled":true,
	"computer":"kloizinD7.crossmatch.net",
	"domain":"crossmatch.net",
	"user":"Kirill.Lo@crossmatch.com",
	"insideFirewall":true,
	"remoteSession":false
}

Policy Configuration

dpWebDefaultPolicies configuration element

The dpWebDefaultPolicies element in the Web.config file contains general configuration information about the Authentication Policies.

Put the dpWebDefailtPolicies element within the configuration element in a Web.config. The dpWebDefailtPolicies element has no attributes.

The dpWebDefaultPolicies element may include the following elements.

dpWebPolicies configuration element

The dpWebPolicies element in the Web.config file contains configuration information about standard Authentication Policies (authentication policies when step-up authentication is not triggered).

Put the dpWebPolicies element within the dpWebDefaultPolicies element in a Web.config. The dpWebPolicies element has no attributes.

The dpWebPolicies element may include the following elements.

dpWebPolicy configuration element.

The dpWebPoliciy element in the Web.config file contains configuration information about one particular Authentication Policy.

The following table describes the attributes of the dpWebPoliciy element.

Attribute Data type Description
name String Readable name of authentication policy. This attribute is required.
tokens String List of authentication tokens separated by semicolon (;) in token GUID format. This attribute is required.

Below are a few examples of the dpWebPolicies element.

<dpWebPolicy name="Password" tokens="D1A1F561-E14A-4699-9138-2EB523E132CC" />

The element above represents a Password only policy.

<dpWebPolicy name="Fingerprint" tokens="AC184A13-60AB-40E5-A514-E10F777EC2F9" />

The element above represents a Fingerprint only policy.

<dpWebPolicy name="Fingerprint AND Password" tokens="AC184A13-60AB-40E5-
A514-E10F777EC2F9; D1A1F561-E14A-4699-9138-2EB523E132CC" />

The element above represents a Fingerprint AND Password policy.

Example of dpWebPolicies Configuration Element

Below is an example of dpWebPolicies Configuration Element.

<dpWebPolicies>
	<dpWebPolicy name="Password" tokens="D1A1F561-E14A-4699-9138-2EB523E132CC" />
	<dpWebPolicy name="Fingerprint" tokens="AC184A13-60AB-40E5-A514-E10F777EC2F9" />
	<dpWebPolicy name="Contactless" tokens="F674862D-AC70-48CA-B73E-64A22F3BAC44" />
	<dpWebPolicy name="Smart Card" tokens="D66CC98D-4153-4987-8EBE-FB46E848EA98" />
	<dpWebPolicy name="One-time Password" tokens="324C38BD-0B51-4E4D-BD75-200DA0C8177F" />
</dpWebPolicies>

The above policies should allow using Password OR Fingerprint OR Contactless cards OR Smart Cards OR OTP if step up authentication is not triggered.

dpWebStepUpPolicies configuration element

The dpWebStepUpPolicies element in the Web.config file contains configuration information about step-up Authentication Policies (authentication policies when step-up authentication is triggered).

Put the dpWebStepUpPolicies element within the dpWebDefailtPolicies element in a Web.config file. The dpWebStepUpPolicies element has no attributes.

The dpWebStepUpPolicies element may include one or more dpWebPoliciy elements.

Below is an example of dpWebStepUpPolicies Configuration Element.

<dpWebStepUpPolicies>
	<dpWebPolicy name="Fingerprint AND Password" tokens="AC184A13-60AB-40E5-
		A514-E10F777EC2F9; D1A1F561-E14A-4699-9138-2EB523E132CC" />
	<dpWebPolicy name="Fingerprint AND PIN" tokens="AC184A13-60AB-40E5-A514-
		E10F777EC2F9; 8A6FCEC3-3C8A-40c2-8AC0-A039EC01BA05" />
</dpWebStepUpPolicies>

Those policies would force the user to use Fingerprint AND Password OR Fingerprint AND PIN if step-up authentication is triggered.

dpWebStepUpTriggers configuration element

The dpWebStepUpTriggers element in the Web.config file contains configuration information about triggers which can trigger Step-up Authentication.

Put the dpWebStepUpTriggers element within the dpWebDefailtPolicies element in a Web.config. The dpWebStepUpTriggers element has no attributes.

The dpWebStepUpTriggers element may include the following elements.

dpWebStepUpTrigger Configuration Element

The dpWebStepUpTrigger element in the Web.config file contains configuration information about one particular Step Up Authentication trigger.

The following table describes the attributes of the dpWebStepUpTrigger element.

Attribute Data type Description
name String Trigger name. This attribute is required.

Below are few examples of using the dpWebStepUpTrigger element.

<dpWebStepUpTrigger name="behavior" />

The element above represents the Behavior trigger, which initiates step-up authentication if previously captured user behavior is not matched.

<dpWebStepUpTrigger name="insideFirewall" />

The element above represents the inside firewall trigger, which initiates step up authentication if the user’s machine is located outside the corporate network.

List of Triggers supported

In this release we support the following triggers.

Parameter Description
behavior Trigger step up authentication if user behavior does not match.
ip Trigger step up authentication if user IP does not match with the trained data stored in the BehavioSec cloud.
device Trigger step up authentication if user device does not match with the trained data stored in the BehavioSec cloud.
altusInstalled Trigger step up authentication if DPCA is not installed on client machine.
computer Trigger step up authentication if client machine is not trusted.
domain Trigger step up authentication if client machine does not belong to trusted AD domain.
user Trigger step up authentication user who is trying to access web server is not currently logon user on local machine.
insideFirewall Trigger step up authentication if local machine is not located in corporate network (not inside corporate firewall).
remoteSession Trigger step up authentication if user connected to local machine remotely.
Example of dpWebStepUpTriggers Element

Below is an example of the dpWebStepUpTriggers Configuration Element.

<dpWebStepUpTriggers>
	<dpWebStepUpTrigger name="behavior" />
	<dpWebStepUpTrigger name="insideFirewall" />
</dpWebStepUpTriggers>

The above settings will trigger step-up authentication if user behavior does not match or when the local machine is located outside of the firewall.

Example of dpWebDefaultPolicies Element

Below is an example of the dpWebDefaultPolicies configuration element.

<dpWebDefaultPolicies>

	<dpWebPolicies>
		<dpWebPolicy name="Password" tokens="D1A1F561-E14A-4699-9138-2EB523E132CC" />
		<dpWebPolicy name="Fingerprint" tokens="AC184A13-60AB-40E5-A514-		E10F777EC2F9" />
  </dpWebPolicies>

	<dpWebStepUpPolicies>
    <dpWebPolicy name="Fingerprint AND Password" tokens="AC184A13-60AB-40E5-
			A514-E10F777EC2F9; D1A1F561-E14A-4699-9138-2EB523E132CC" />
  </dpWebStepUpPolicies>

	<dpWebStepUpTriggers>
    <dpWebStepUpTrigger name="behavior" />
    <dpWebStepUpTrigger name="insideFirewall" />
  </dpWebStepUpTriggers>

</dpWebDefaultPolicies>

The policy above will allow a user to authenticate with their Fingerprint OR Password if step-up authentication is not triggered, it will force the user to use Fingerprint AND Password if step-up authentication is triggered, and user behavior and computer location outside firewall will trigger step-up authentication.