This document describes the simple remote login and permissions service available in LabKey Server.
The remote login/permissions service allows cooperating websites to:
The remote login/permissions service has two styles of interaction:
The remote login/permissions service supports the following operations
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.
There are 3 main actions supported by the Login controller
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).
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
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.
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}">
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.
The Java API wraps the calls above with some convenient java classes that
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:
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.
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.