Remote Login API Overview

This document describes the simple remote login and permissions service available in LabKey Server.

The remote login/permissions service allows cooperating websites to:

  • Use a designated LabKey server for login
  • Attach permissions to their own resources based on permissions to containers (folders) on the Labkey Server.

The remote login/permissions service has two styles of interaction:

  • Simple URL/XML based API which can be used by any language
  • Java wrapper classes that make the API a little more convenient for people building webapps in java.
  • PHP wrapper classes that make the API a little more convenient for people building webapps in PHP.

The remote login/permissions service supports the following operations

  • Get a user email and opaque token from the LabKey server. This is accomplished via a web redirect and the LabKey server’s login api will be shown if the user does not currently have a logged-in session active in the browser.
  • Check permissions for a folder on the labkey server.
  • Invalidate the token, so that it cannot be used for further permission checking.

Base URL

A labkey server has a base URL that we use throughout this API description. This is of the form

<protocol>//<server>[:<port>]/[contextPath]

Such as

http://localhost:8080/labkey

In the above example, the port is 8080 and the contextpath is labkey. On some servers (such as labkey.org) there is no context path. This doc will use ${baseurl} to refer to this base URL.

URL/XML API

There are 3 main actions supported by the Login controller

createToken.view

To ensure that a user is logged in and to get a token for further calls, a client must redirect the browser to the URL:

${baseurl}/login/createToken.view?returnUrl=${url of your page}

Where ${url of your page} is a properly encoded url parameter for a page in the client web application where control will be returned. After the user is logged in (if necessary) the browser will be redirected back to <url of your page> with the following 2 extra parameters which your page will have to save somewhere (usually session state).

  • labkeyToken – this is a hex string that your web application will pass into subsequent calls to check permissions.
  • labkeyEmail – this is the email address used to log in. It is not required to be passed in further calls

Example

To create a token for the web page

http://localhost:8080/logintest/permissions.jsp

You would use the following URL

https://www.labkey.org/login/createToken.view?returnUrl=http%3A%2F%2Flocalhost%3A8080%2Flogintest%2Fpermissions.jsp

After the login the browser would return to your page with additional parameters:

http://localhost:8080/logintest/permissions.jsp?labkeyToken=7fcfabbe1e1f377ff7d2650f5427966e&labkeyEmail=marki%40labkey.com

verifyToken.view

This action is not intended to be used from the browser (though you certainly can do so for testing). This URL returns an XML document indicating what permissions are available for the logged in user on a particular folder.

Your web app will access this URL (Note that your firewall configuration must allow your web server to call out to the LabKey server) and parse the resulting page. The general form is

${baseurl}/login/${containerPath}/verifyToken.view?labkeyToken=${token}

Where ${containerPath} is the path on the labkey server to the folder you want to check permisisons against and ${token} is the token sent back to your returnUrl from createToken.view.

Example

To check permissions for the home folder on www.labkey.org, here’s what you’d request:

https://www.labkey.org/login/home/verifyToken.view?labkeyToken=7fcfabbe1e1f377ff7d2650f5427966e

An XML document is returned. There is currently no XML schema for the document, but it is of the form

<TokenAuthentication success="true" token="${token}" email="${email}" permissions="${permissions}" />

Where permissions is an integer with the following bits turned on for permissions to the folder.

READ: 0x00000001
INSERT: 0x00000002
UPDATE: 0x00000004
DELETE: 0x00000008
ADMIN: 0x00008000

If the token is invalid the return will be of the form

<TokenAuthentication success="false" message="${message}">

invalidateToken.view

This URL invalidates a token and optionally returns to another URL. It is used as follows

${baseurl}/login/createToken.view?labkeyToken=${token}&returnUrl=${url of your page}

Where ${token} is the token received from createToken.view and returnUrl is any page you would like to redirect back to. returnUrl should be supplied when calling from a browser and should NOT be supplied when calling from a server.

Java API

The Java API wraps the calls above with some convenient java classes that

  • store state in web server session
  • properly encode parameters
  • parse XML files and decode permissions
  • cache permissions

The Java API provides no new functionality over the URL/XML API

To use the Java API store the remoteLogin.jar in the WEB-INF/lib directory of your web application. The API provides two main classes:

  • RemoteLogin – contains a static method to return a RemoteLoginHelper instance for the current request.
  • RemoteLoginHelper – Interface providing methods for calling back to the server.

Typically a protected resource in a client application will do something like this

RemoteLoginHelper rlogin = RemoteLogin.getHelper(request, REMOTE_SERVER);
if (!rlogin.isLoginComplete())
{
        response.sendRedirect(rlogin.getLoginRedirect());
        return;
}
Set<RemoteLogin.Permission> permissions = rlogin.getPermissions(FOLDER_PATH);

if (permissions.contains(RemoteLogin.Permission.READ))
        //Show data
else
        //Permission denied

The API is best described by the Javadoc and the accompanying sample web app.

HTTP and Certificates

The Java API uses the standard Java URL class to connect to server and validates certificates from the server. To properly connect to an https server, clients may have to install certificates in their local certificate store using keytool.

Help can be found here: http://java.sun.com/javase/6/docs/technotes/tools/windows/keytool.html

The default certificate store shipped with Java JDK 1.6 supports more certificate authorities than previous jdk’s. It may be easier to run your web app under 1.6 than install a certificate on your client JDK. The labkey.org certificate is supported under JDK 1.6.

discussion

Discussion

Search 

Pages 

previousnext
 
expand all collapse all