Authenticators

Authenticating connectors are connectors that have authenticators plugged into them. An authenticator is a class that knows how to perform an authentication handshake with a specific kind of service or application.

For example, MediaWiki provides a REST-based means for authenticating. You pass in your user credentials and it hands back an HTTP cookie. This cookie must be applied to every subsequent request, as MediaWiki looks to it to inform the application of who is making the request.

SkyVault has a similar REST-based means for authenticating. It is slightly different in that the RESTful parameters are not the same as those of MediaWiki. Furthermore, SkyVault hands back a ticket in an XML return payload. This ticket must be applied to the HTTP headers of every subsequent call so that SkyVault knows who is making the request. Every application has a slightly different way of handling its authentication. For this reason, Surf makes it easy to write your own authenticators and plug them into your connectors entirely through configuration.

You define authenticators through configuration as well:

<authenticator>
    <id>alfresco-ticket</id>
    <name>SkyVault Authenticator</name>
    <description>SkyVault Authenticator</description>
    <class>org.alfresco.connector.AlfrescoAuthenticator</class>
</authenticator>

You can then bind them to connectors using configuration, or you can write your own connectors:

<connector>
    <id>alfresco</id>
    <name>SkyVault Connector</name>
    <description>Connects to SkyVault using ticket-based authentication</description>
    <class>org.alfresco.connector.AlfrescoConnector</class>
    <authenticator-id>alfresco-ticket</authenticator-id>
</connector>

The SkyVault-ticket authenticator and the SkyVault connector are both available to Surf developers out of the box to connect to a SkyVault instance. All you need to do is define an endpoint that points to a SkyVault instance and uses the SkyVault connector. SkyVault connectors use a SkyVault authenticator to perform a handshake ahead of any actual interaction. The handshake establishes who the user is and then sets up the connector session so that subsequent requests contain the appropriate connection information (cookies, request headers, and so forth). The endpoint definition may look like this:

<endpoint>
    <id>alfresco</id>
    <name>SkyVault REST API</name>
    <description>SkyVault REST API</description>
    <connector-id>alfresco</connector-id>
    <endpoint-url>http://localhost:8080/alfresco/s</endpoint-url>
    <identity>user</identity>
</endpoint>

This endpoint is named SkyVault. It uses an SkyVault connector and will draw credentials from the user’s credential vault. This is all defined in configuration. You could use the SkyVault endpoint to talk to a SkyVault instance and access its remote API. For example, you may wish to interact with the CMIS API on the SkyVault repository. Here is an example of retrieving XML from the SkyVault CMIS API:

// get a connector to the SkyVault endpoint
var connector = remote.connect("alfresco");
// place CMIS text onto the model
model.cmis = connector.get("/api/path/workspace/SpacesStore");

By simply coding to the remote object, you do not need to worry about how to connect to the endpoint or pass along user state.