Note: The remote login API service described in this topic is no longer supported or maintained; we recommend using the CAS identity provider if you need a LabKey identity provider service.

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

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

The base URL is of the form:


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


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

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. Learn how in this topic:


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):

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


To create a token for the web page


You would use the following URL:

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



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:


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.


To check permissions for the home folder on, here’s what you’d request:
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.

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())
Set<RemoteLogin.Permission> permissions = rlogin.getPermissions(FOLDER_PATH);

if (permissions.contains(RemoteLogin.Permission.READ))
//Show data
//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:

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 certificate is supported under JDK 1.6.

Related Topics


Was this content helpful?

Log in or register an account to provide feedback

expand all collapse all