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

• Remote Login API Overview
• Base URL
• Set Up External Redirect Hosts
• URL/XML API
• createToken.view
• verifyToken.view
• invalidateToken.view
• Java API
• HTTP and Certificates

Remote Login API Overview

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.

• 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.

• 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 doc will use ${baseurl} to refer to this base URL.

The base URL is of the form:

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

For example, a local development machine might be using port 8080 and the context path "labkey", so the base URL would be:

http://localhost:8080/labkey

On some servers (such as www.labkey.org) there is no context path. The base URL where you are reading this topic is simply:

https://www.labkey.org

Set Up Allowable External Redirect Hosts

Before calling any of the actions described below, you must first approve the authentication provider server as an allowable URL for external redirects.

For details see Configure Allowable External Redirect Hosts.

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%40myemail.com

verifyToken.view

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

Your web app will access this URL and parse the resulting page. Note that your firewall configuration must allow your web server to call out to the LabKey Server. 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 permissions 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

<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

<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

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.

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.

Related Topics

• Configure Allowable External Redirect Hosts