HTTPConnector

Namespace: urn:mace:shibboleth:2.0:resolver
Schema: http://shibboleth.net/schema/idp/shibboleth-attribute-resolver.xsd

The HTTP data connector generates multiple attributes resulting from calling a web service. The connector itself is primarily just a framework for constructing a request to issue using the Apache HttpClient library and processing a response. There is no attempt to standardize a web service interface, but the design is geared towards making simple, templated GET requests and processing XML or JSON result sets using a script. More advanced use cases can be supported by means of pluggable Java interfaces or more advanced scripting.

1 General Configuration
- 1.1 Caching Behavior
- 1.2 Examples
2 Reference
3 Spring Configuration

General Configuration

The connector marries three essential pieces of configuration to be supplied by the deployer:

an HttpClient bean and various security and networking parameters necessary to invoke the web service safely
request creation
response processing

Two options for request creation exist, one for simple GET requests and one for more complex POST requests with a body. Both rely on a <URLTemplate> element to produce the URL, which can be populated with dependency data much like an LDAP search filter or database query. The POST option also supports a <BodyTemplate> element that can similarly generate a request body based on dependency data, typically JSON or XML. With POST, you also can control caching of results (if a results cache is used) by generating a cache entry key using a <CacheKeyTemplate> element.

The only supplied implementation for response processing is script-based, using the <ResponseMapping> element to supply a script to produce attribute data from the response body. For efficiency, the implementation assumes that the response processing script can consume the results in real time, and leaves any buffering of the data to the script, should that be necessary. Support is built-in for limiting the size of the data, allowed content types, and HTTP status codes accepted, to address the most common sanity checks.

At minimum, an httpClientRef attribute must be supplied to provide the client runtime bean to use. This will usually if not always be accompanied by an httpClientSecurityParametersRef attribute to supply security settings, although a few shortcut settings are available for certificate authentication use cases. A complete summary and examples can be found on the HttpClientConfiguration page.

Spring beans may be defined either in additionally loaded Spring resources configured into the Attribute Resolver service's resource collection, or in a central location such as global.xml

Caching Behavior

The built-in caching support (if enabled) keys the cached data for a GET request by the fully populated template URL generated, typically including information about the subject in the URL. For POST requests, you may provide a template for producing an appropriate cache key, or omit it to disable caching.

Customized implementations of the ExecutableSearchBuilder<HTTPSearch> interface MUST implement appropriate cache key semantics, particularly if they inherit from that base class.

Examples

Any examples here omit the Spring beans that define the HTTP client and security parameters to use. Examples of these can be found in the HttpClientConfiguration topic.

 <DataConnector id="myHTTP" xsi:type="HTTP"
		httpClientRef="WebServiceHttpClient"
		httpClientSecurityParametersRef="ExampleOrgWSSecurity">
	<URLTemplate>
		<![CDATA[
		https://webservice.example.org/api/subject/$pathEscaper.escape($resolutionContext.principal)/groups
		]]>
	</URLTemplate>

	<ResponseMapping>
		<Script>
		<![CDATA[
		var HashSet = Java.type("java.util.HashSet");
		var HttpClientSupport = Java.type("net.shibboleth.utilities.java.support.httpclient.HttpClientSupport");
		var IdPAttribute = Java.type("net.shibboleth.idp.attribute.IdPAttribute");
		var StringAttributeValue = Java.type("net.shibboleth.idp.attribute.StringAttributeValue");
  
		// Limits length to 64k
		var body = HttpClientSupport.toString(response.getEntity(), "UTF-8", 65536);
		var result = JSON.parse(body);
 
		var attr = new IdPAttribute("group");
		var values = new HashSet();
		if (result.groups != null) {
			for (var i=0; i<result.groups.length; i++) {
				values.add(new StringAttributeValue(result.groups[i].name));
			}
		}
		attr.setValues(values);
		connectorResults.add(attr);
		]]>
		</Script>
	</ResponseMapping>

	<ResultCache expireAfterWrite="PT5M"/>
</DataConnector>

Reference

The following attributes may be specified (the only required attribute is httpClientRef).

Name	Type	Default	Description

Name	Type	Default