Remote Operations Reference
- Scott Cantor
DRAFT
This is a starting point to document the many operations implemented for SP agents to call on the Java hub (implemented in an IdP plugin) to perform.
This material is highly subject to change.
- 1 General DDF Message Format
- 2 HTTP Remoting
- 3 General Operations
- 3.1 ping
- 3.2 parse-request-map
- 3.3 storage
- 3.4 sealer
- 3.5 session-initiator
- 3.5.1 initiator/saml2
- 3.6 token-consumer
- 3.6.1 consumer/saml2-post
- 3.6.2 consumer/saml2-post-simplesign
- 3.6.3 consumer/saml2-artifact
General DDF Message Format
Input messages are not formally standardized, but:
Currently the agent identity is not included (it’s in the HTTP layer) but this may change.
Not all messages will include an application ID, but many do.
If the message includes a forwarded HTTP request, it will be in a structure member called “http” (see below).
Output messages are a structure with some defined members that may or may not be present:
Member Name | DDF Type | Content/Definition |
|---|---|---|
event | string | If present, contains the error event resulting from a failed operation. |
http | struct | If present, contains an HTTP response to relay back to the user agent. Not all operations will contain one, but usually if they do, it will be mandatory and expected by the agent. |
All operations are top-level webflows defined at /idp/profile/sp/opname
Unless otherwise specified, all operations MAY return an “event” member as noted above, and a number of standard events exist for invalid input scenarios.
HTTP Remoting
When an HTTP request has to be remoted (in whole or in part), the input will contain a struct member named “http” with the following substructure:
Member Name | DDF Type | Content/Definition |
|---|---|---|
scheme | string | Requested scheme (generally https or http) |
hostname | unsafe_string | Requested hostname reported by web server |
port | integer | Requested port |
content_type | string | Value of content type header |
body | string | Body content, assumed to be UTF-8 safe for the subset of cases when it would be used (this is tentative, feels like it should be unsafe_string, but that would make it functionally impossible to operate on). Could be that either would be allowed as use case dictates. |
content_length | long integer | Value of content length header |
remote_user | string | Value of REMOTE_USER internal server variable |
remote_addr | string | Requesting client address as reported by web server |
method | string | Requested HTTP method |
uri | unsafe_string | Requested URI (the part after the scheme, host, and port |
url | unsafe_string | Requested URL (including scheme, host, and port (if non-default) |
query | string | Requested query string |
headers | structure | Each header is populated as a member whose name is the header name and whose unsafe_string value is the header value |
certificates | list | Probably unused, but would contain a list of base64-encoded string-valued objects containing each certificate in a chain presented by client |
When an HTTP response has to be remoted, the output will contain a struct member named “http” with the following substructure:
Member Name | DDF Type | Content/Definition |
|---|---|---|
redirect | unsafe_string | Redirect URL to return to client, mutually exclusive with response structure |
response.data | unsafe_string | Response body |
response.status | integer | HTTP response status code |
headers | list | Each header is populated as a list element whose name is the header name and whose unsafe_string value is the header value |
General Operations
These are generic functions that don’t involve a specific Application and so the input does not carry an “appId” member.
ping
Testing operation that returns the current epoch in seconds.
parse-request-map
Parses the supplied XML representation of a <RequestMap> conforming to the updated 4.0 schema and returns the parsed XML as a DDF structure (Javadocs TBD). Provided for use by agents without XML parsing capability. This is not a generic parsing operation, but validates the result against the updated XML Schema and ensures that the root element is as expected.
storage
Remote implementation of the StorageService API (probably will end up as a subset, TBD). The storage context values are automatically prefixed by the agent ID to avoid conflicts with other agents sharing the same storage back-end.
The requested operation is based on the HTTP method used, one of PUT, GET, POST, or DELETE, corresponding to record creation, read, update, or delete. When doing a non-versioned update, the record will be created if not found to update.
TBD: Probably will need an atomic create/read/update operation of some sort to save round trips, likely based on flag in the input.
sealer
Remote implementation of the DataSealer API allowing agents to encrypt or decrypt private data. The agent ID is embedded in the data being encrypted to cross-check ownership.
The requested operation is based on the HTTP method used: GET signifies decryption/unwrapping and POST signifies encryption/wrapping.
session-initiator
API to initiate a login request to an IdP on behalf of the requesting agent’s application. This is a facade for an unbounded set of subflows that implement support for particular protocols. The input contract contains some fixed inputs and variable inputs that depend on the implementation(s) of subflows available. The operation will attempt any number of initiator subflows in a defined order until one succeeds or all have failed.
initiator/saml2
Session initiator subflow supporting SAML 2.0, i.e., responsible for producing SAML 2.0 <AuthnRequest> messages on behalf of agents. A number of inputs are supported to influence request generation, typically based on content, but this can be disallowed on a per-Agent/Application/RelyingParty basis.
token-consumer
API to process an authentication response on behalf of the requesting agent’s application. This is a facade for an unbounded set of subflows that implement support for particular protocols. The input contract contains some fixed inputs and variable inputs that depend on the implementation(s) of subflows available. The operation will check each enabled subflow supported by an application for usability and run the first (and only the first) subflow indicating it can handle the request.
consumer/saml2-post
consumer/saml2-post-simplesign
consumer/saml2-artifact
Token consumer subflows for each supported SAML binding. These detect compatibility via examination of the HTTP request. Inputs and outputs are as above.