FAQ content

Adding a new self-hosted configuration

In this article

Getting there

To create and manage your LibAuth profiles, go to LibApps > Admin > LibAuth Authentication.

Navigating to the Manage Authentication page
LibApps admin-level users can access LibAuth settings via the LibApps dashboard, under Admin > LibAuth Authentication.

Before you begin

Before setting up your new self-hosted configuration, you'll want to work with your IT staff on the following:

Permissions

  • If you restrict connections to your self-hosted system, be sure to allow access for the LibAuth server's IP address. The address varies by region, as indicated below:
    • Asia-Pacific customers: au.libauth.com
    • Canadian customers: ca.libauth.com
    • European customers: eu.libauth.com
    • All other customers: us.libauth.com

Server Information

  • Obtain the URL to your self-hosted system. This is the URL where LibAuth should POST the data submitted via the login form.
    • These URLs must be secure. URLs beginning with http:// will not be accepted.
    • The script should accept two HTTP POST parameters (username and password) and return a result to indicate whether or not the authentication was successful.
    • LibAuth will send login data to your server via HTTPS. To maintain a secure transfer of data, we recommend that you provide an HTTPS server URL. 
  • Ask your IT staff what format of data your authentication system returns. LibAuth can accept a plain text message or JSON object (recommended).
    • We recommend the authentication return a JSON object like: {"firstname":"James","lastname":"Bond","email":"jbond@007.com","auth":true}
  • The text returned by your system's URL when the user passes authentication.
    • By default, LibAuth will look for +OK to indicate a successful authentication. Any other value will indicate that authentication failed.
    • If your system provides text other than +OK, then you will need to specify this in your LibAuth configuration.

Attributes

  • Obtain the attributes used for First Name, Last Name, Email, and User ID from your IT staff.

Add a self-hosted configuration

  1. If you have not yet created a LibAuth configuration, skip to Step 2. Otherwise, click on the Add Configuration button to create another one.
Screenshot of the Add Configuration button
  1. Below the Search for Your Institution dropdown, click on the Manual Configuration link.
Clicking to set up a manual configuration
  1. Select Self Hosted as your authentication protocol.
Selecting the self hosted protocol
  1. Under Server Info & Parameters, enter the URL for your self-hosted system provided by your IT staff. The URL must start with https://.
Server info options for the Text return type
  1. For the Return Type, select the type of data being returned by your system. LibAuth can accept either a text string or a JSON object.
    1. Using Text return type: by default, LibAuth will expect a response message of +OK to indicate successful authentication. If your system will return a different response, enter it in the Return Text field.
    2. Using JSON return type: you will be provided with examples of JSON objects that LibAuth expects to receive for failed and successful authentications.
      • Failed authentication: { "auth": false }
      • Successful authentication: { "auth": true, "firstname": "Joe", "lastname": "Smith", "email": "j.smith@school.edu }
      • In both cases, the value of the auth property should be boolean. For successful responses, the values of the properties containing the user's first name, last name, and email address should be strings.
The JSON return type examples
  1. If you are using the JSON return type, configure the attributes released from your server. These should match the property names in the JSON object returned by your system.
    1. Enter the name of the attribute that contains the user's first name. (Optional, but recommended.)
    2. Enter the name of the attribute that contains the user's last name. (Optional, but recommended.)
    3. Enter the name of the attribute that contains the user's email address. (Required.)
    4. Enter the name of the attribute that contains the user's user ID. (Optional, but recommended.)
Attributes fields
  1. Give your configuration a name.
  2. If you'd like, you can also provide notes or details about this configuration for your reference.
  3. Click the Save Configuration button.
The General fields and Save Configuration button