LaunchPad

Introduction

Faria’s LaunchPad platform allows users to log in once and switch between all applications they have access to. LaunchPad allows switching between multiple identities within those applications.

For example, a user might be a teacher at one school and a parent at another. All verified Faria users have access to LaunchPad. Logging into a client application such as ManageBac or OpenApply also logs the user into LaunchPad.

LaunchPad supports integration with third party applications. This allows the LaunchPad experience to extend to select third party partners in addition to Faria’s own products. This document discusses the capabilities of LaunchPad and the ways you can integrate them.

The components

To learn more about LaunchPad capabilities we offer to integration partners, please select one of the sections listed to the left. If you wish to become a single sign-on partner with Faria, please let us know at [email protected].

Here are the major pieces of the LaunchPad puzzle:

  1. A Dashboard shows a user their applications as icons floating above a background.
  2. A Launchbar sits at the top of every application, allowing a user to jump between applications authenticated via LaunchPad.
  3. Forward Authentication allows a user to sign into your application from LaunchPad.
  4. Automatic Login allows a user to sign into your application automatically (if they are currently signed into LaunchPad).
  5. Logout Everywhere allows a user to sign out of all their applications simultaneously.
  6. Solo Identity Pairing allows a user to link their account to a third party application with their LaunchPad account.

Read on for more details on each component, or jump ahead to Building Your Integration.

The examples below all use our production Launchpad URLs (such as https://launchpad.managebac.com/). If you are working in a development or staging environment you will of course need to use the hostname and endpoints provided to you for that environment instead.

Terminology

  • Individual (person) - A single person who may have access to more than one application and many discrete accounts inside those applications.
  • LaunchPad Account - A single account in LaunchPad typically represents an individual person.
  • Client Application Account - An account that an individual accesses in your application using a login and password (or other credentials).
  • LaunchPad Identity - Inside LaunchPad each of your application’s accounts is represented as an identity belonging to a specific LaunchPad account.
  • Pairing - The process by which an individual connects Client Application Accounts to LaunchPad, thereby creating identities.
  • LaunchPad Client Application - This could be a Faria application or a third-party application. If your application is single-tenant/multi-install then each installation will be a distinct Client Application as far as LaunchPad is concerned. LaunchPad’s security model is based around each Client Application owning its own set of identities.
  • “Your Application” - Refer to a third party application (yours) that is in the process of building an integration with LaunchPad.
  • School - The given school or educational institution a particular individual is associated with. If your system is multi-tenant and associates individuals with multiple schools, please contact us for help.
  • Launchbar - The LaunchPad application switcher. This is the interface element that sits at the top of the browser window and allows an individual to jump between the various applications and identities they have access to with LaunchPad.
  • Authentication Session - An individual forward-authentication session (or request for a login session). This session will reference its own ‘LaunchPad Identity’ which you can use to retrieve your local 'Client Application Account’ via the pairing_value that was agreed upon in the pairing process.

Forward authentication

Forward authentication is a required capability.

There are three ways an individual might end up using the forward authentication capability to gain access your client application:

  1. The individual was using the Launchbar and selected an identity that belongs to your client application.
  2. The individual was using the LaunchPad dashboard and selected an identity that belongs to your client application.
  3. You have implemented Automatic Log-In, an individual has visited a page supporting auto-login, and that individual is currently logged into LaunchPad.

Forward authentication is the most critical piece of the LaunchPad puzzle. With this capability, LaunchPad can request client applications and perform authentication against a paired identity they own. An individual signs into LaunchPad once, and their authentication session is forwarded to other applications.

When an individual is signed into LaunchPad they can jump directly to other applications without ever leaving your application (via forward authentication) using our Launchbar.

To integrate your application you must:

  1. Implement the Forward Authentication API to receive these requests.
  2. Use the Launchpad API to accept or reject a request.
  3. Have paired relevant identities from your client application into LaunchPad.

You can do this via the Solo Identity Pairing workflow.

The Forward authentication workflow

A typical authentication interaction looks like this:

  1. An individual selects an identity from your client application to authenticate as.
  • This can happen due to an individual signing into LaunchPad, and selecting an active identity via the Dashboard or due to an individual interacting with the Launchbar, and selecting an active identity.
  1. LaunchPad generates a Forward Authentication Request and redirects the browser.
  2. The browser sends the forward authentication request to your application, using the Forward Authentication API.
  3. Your application verifies the request internally to make sure the account is still active and in good standing.
  4. Your application makes a decision, and informs LaunchPad, using the Authentication Sessions API:
  • Accept the authentication request and give the user access.
  • Reject the authentication request and send the user back to LaunchPad.
  • Ignore the authentication request and send the user somewhere else. The authentication request will time out automatically, but this is not a recommended approach. You are encouraged to always mark an authentication request as explicitly accepted or rejected.

Handling forward authentication

Direction

From LaunchPad to your application.

Request

POST https://clientapp.com/launchpad/api/handle_forward_authentication

Signed/encrypted JWE payload

{
  "session_id": ["session UUID"]
}

LaunchPad will make this request. You are expected to make a decision and then approve (or reject) the authentication session during the forward authentication HTTP request. Authentication requests live for 30 seconds before they are considered invalidated.

You must execute approval requests synchronously. You should reject the login session if your API request to approve the session is not successful. This is to help prevent session replay attacks.

To improve performance you can throw your reject messages into a background thread. In the future, we may allow rejections to be recorded past the 30-second timeout. Currently, a rejection that is too slow will be treated as ignore (which rejects the login).

Client applications should never simply allow a forward authentication request to bypass or override other security considerations. All typical checks of an account’s validity for login should still be checked (if the account is deleted, disabled, locked out, etc.) The client application should also check that the account in question is actually paired with Launchpad (in cases where a primary key is being used for pairing purposes).

Launchbar

Launchbar is a required capability.

The Launchbar is a component you embed in your application as an inline frame (via an HTML iframe tag), which contains content served directly by LaunchPad. The Launchbar provides a simple, secure, fast, and consistent way to jump directly to any other application an individual has access to, without requiring each application’s development team to start from scratch.

Launchbar

See Also: Building Your Integration.

The UI Component - an iframe

You must add the Launchbar to your application (globally) as an inline frame.

<iframe src="https://launchpad.managebac.com/launchbar?app=ManageBac" allowtransparency="" height="30px" id="launchbarframe" style="border: none; background:#333;" width="100%"></iframe>

You should render this HTML on the server-side (not client-side) so the browser can start loading the content of the Launchbar iframe as quickly as possible. You must position the iframe at the top of the page.

The iframe must allow transparency and may expand/contract as necessary to show popup menus or other dialogues (such as the LaunchPad session timeout). In all cases your application’s UI will be visible underneath (though dialogues may choose to apply an opacity effect, fading the background.)

Parameter Description
app Name of your application (currently shown as 'ManageBac’). The name of the 'active’ application will be highlighted in Launchbar.

The Glue - launchbar_client.js

You must also add a piece of JavaScript “glue” which acts as a cross-window messaging bridge between the Launchbar (loaded in the iframe) and your client application’s window.

<script src="https://launchpad.managebac.com/assets/launchbar_client.js" data-config="{"pairing_value":10752610,"client_logout":{"url":"/logout","method":"get"}}"></script>

This tag has a data-config attribute which contains an escaped JSON document, that holds the following key-value pairs:

Parameter Description
pairing_value The pairing value of the current identity used to highlight the active identity.
client_logout The path of your application’s log-out method, invoked by Launchpad when the user chooses 'Log-out Everywhere’. It contains two sub-keys: url and method. Usually the method will be PUT or DELETE and url a path.

Once properly integrated, Launchbar works out-of-the-box and always shows the identities available to any particular individual. Launchbar shows the name of your application in bold.

Details - Handling Page Refresh

Every time your application requests a new page the Launchbar is reloaded, extending your LaunchPad session.

If your client application (after loading) runs completely client-side (AJAX, etc) you will need to manually ping LaunchPad (every 5 minutes or so is a good interval) if there is client activity, otherwise LaunchPad will have no way to know about this activity and the login session may timeout.

// ping Launchpad periodically so we do not get logged out
window.LaunchpadAPI.ping()

Automatic login

Automatic login is a recommended capability.

This capability allows a user signed into LaunchPad (and previously paired with your application) to automatically login by visiting the same page they typically use to manually login to your application. If you do not implement this capability, an end user who has already signed into LaunchPad and has your application linked in LaunchPad will need to authenticate to your application manually.

Implementation

To integrate automatic login, add the automatic login script to your application’s signin or pre-signin page (such as a landing page that has a signin button, even if you are not presenting a login form yet).

<script async src="https://launchpad.managebac.com/utils/login_check.js?app=ManageBac&app_id=<add_id>"></script>
Parameter Description
app The name of your application.
app_id The ID of your application (issued by Faria if needed).

The app_id is not typically required for multi-tenant SaaS web apps. The primary use of this value is to help LaunchPad locate the proper “instance” of an application for single-tenant applications which have hundreds of different discrete installations.

The login_check.js endpoint will return nothing if the current user is not signed into LaunchPad.

If the user is signed into LaunchPad, the endpoint will return a script which will update window.location.href, redirect to LaunchPad, and request a login session for your application. LaunchPad will generate a forward authentication request back to your application.

Caveats - Infinite Redirect Loops

There is the risk of an infinite loop. If your application cannot process a forward authentication request and that failure results in redirection to your login page, that could result in yet another auto-login attempt, failure, redirect, and so on.

You are required to avoid this behaviour. We recommend a counter stored in the session that increments after a forward-authentication failure. One or two retries should be fine, but if you’re still failing on the 3rd attempt you should disable auto-login the next time a user hits your login page and log the error for examination by your development team.

Logout everywhere

Logout everywhere is a strongly recommended capability. If you do not implement this capability, an individual who clicks “Log Out Everywhere” from the Launchbar will not be logged out of your application. This can cause confusion.

When an individual chooses to log-out everywhere LaunchPad will notify all other applications with open sessions in the same browser of the logout. All Faria applications destroy/close associated login sessions upon receiving this notification. Your application should do the same.

After passing the logout request to LaunchPad and receiving confirmation of the logout this will issue on the client-side a request to logout of the client application.

In the future this feature may logout from LaunchPad, redirect to a LaunchPad sign in page, and then notify your application asynchronously that it needs to perform a logout.

To integrate you must accept the logout everywhere request in your application.

Handling logout everywhere

POST https://yourapp.com/launchpad/api/do_logout

Direction

From LaunchPad to your aplication.

Request

(signed and encrypted JWE payload)

{
  "identity_id": "97c775fc-a7da-451d-b2e5-f7067ea250c5",
  "session_id": "ac67b80b-4a6a-425e-bfc7-60dc20f93592",
  "pairing_value": "U12345"
}
Parameter Description
identity_id The UUID of the underlying identity in LaunchPad.
session_id The UUID of the end user’s session in LaunchPad.
pairing_value The pairing value that represents a user in your application.

Upon receiving this request, your application should end that user’s session immediately. Your application should track sessions using the LaunchPad session_id, so it can find and terminate these sessions quickly from the server-side. This means that if you are using any wholly client-side session mechanism (like Rails’ CookieStore sessions) you will need to change the server-side to support this behaviour properly.

Launchpad will repeat these logout requests with exponential falloff until your application responds with an 200 OK response.

Expected response

200 OK
{"logout": "done"}

Solo identity pairing

Solo identity pairing is a required capability. Identity pairing is the main goal of integration with Launchpad. If you do not implement this capability, an end user can not link their own account in your application with their other identities in LaunchPad.

This capability is currently under partner review. Please discuss with your Faria contact before implementing.

With the Solo identity pairing workflow you allow your end users to link up their account in your system with their existing LaunchPad account.

To integrate:

  1. You should implement the identity pairing workflow within your application, and make sure that the end user can access it.
  2. You should make the workflow easily available to individuals who use your application.
  3. Your application should keep track of which individual’s accounts have been paired and which have not.

Workflow

  1. User logs into your application.
  2. User follows a link (“Pair with LaunchPad” or similar) from your application.
  3. This links back to your own site and generates a signed POST to LaunchPad (/third/pair/request) to request pairing.
  4. The individual is shown a “Would you like to add Application XYZ to your LaunchPad?” dialog.
  5. If the individual agrees your application’s LaunchPad pair/provision endpoint, it will call it, passing an agreed upon pairing value and an approval code.
  6. Your application will then call LaunchPad’s pair/provision endpoint passing it the approval code and identity packet.
  7. Upon receiving a successful response your application will commit the pairing to the database and redirect to LaunchPad’s third/pair/complete URL.
  8. The user will then be given the option to return to your application (via a forward authentication request).

From the individual’s point of view:

  1. Clicks “Pair with LaunchPad”.
  2. Sees the approval screen.
  3. Clicks “Yes, add this application” button inside LaunchPad.
  4. Sees the confirmation screen.
  5. Clicks “Return to Application XYZ”.

Pairing an Identity

If you’re using Rails or want to see an example implementation of pairing, see our example 3rd party application.

Direction

The pairing workflow is initiated from your application.

A Pairing is Requested

POST https://launchpad.managebac.com/third/pairing/request

(signed and encrypted JWE)

{
  "school_name": "St. Martha's Academy",
  "pairing_value": ["unique and immutable ID"]
}
  • school_name is mandatory and will be used by LaunchPad to attempt to match the school with other schools the user is already associated with (so we can show a school logo, group identities by school, etc.)
  • pairing_value is recommended and is how LaunchPad will refer to the identity in the future for forward authentication, federated logout, and other requests to your application that reference the user.

It is recommended you use the primary key of your user/person/login table as the pairing_value. If you do not pass a pairing value LaunchPad will assign you one (a v4 UUID) and you will be responsible for storing it in your database.

A Pairing Approval is Requested

The individual is shown a dialog asking if they wish to add your application to their LaunchPad.

A Pairing is Approved

If they click “Yes” the request is considered approved and LaunchPad will redirect to your application’s pair/provision endpoint.

Provisioning

POST https://yourapp.com/launchpad/api/pair/provision

(signed and encrypted JWE)

{
  "pairing_value": ["unique and immutable ID"],
  "approval_code": ["string"]
}
  • pairing_value is the same value you passed previously or (if you did not pass a value) the UUID that LaunchPad auto-generated.
  • approval_code is a code you pass to the backend API to confirm your client-side reservation of a given pairing when you make the actual provisioning request.

Inside of this web request your application is expected to contact LaunchPad (through the backend) to confirm and commit the pairing.

Your Application Requests and Confirms the Provisioning

POST https://launchpad.managebac.com/api/v1/pairing/provision

(signed and encrypted JWE)

{
  "approval_code": ["approval code you were given previously"],
  "identity": {
    "name": "Jimmy Smith",
    "title": "Student",
    "description": "",
    "school": {
      "name": "St. Martha's Academy"
    }
  }
}

Response

{ "status": "paired" }

Upon receiving a successful pairing response your application should save the pairing and issue a redirect to LaunchPad’s pairing complete endpoint. Or preferably you’ve already saved the pairing and any error will trigger a rollback in the DB transaction.

HTTP 304 Location: https://lauchpad.managebac.com/third/pairing/complete

Resolving Problems with Claims

You need to take care when working with the solo identity pairing workflow because an implementation error in this workflow can cause data inconsistencies and inconvenience your end users.

If you feel any end users should not be eligible for this workflow, you should discuss this with your Faria contact. If your application supports merging of user accounts or otherwise making major changes to a user that would threaten the pairing with LaunchPad, you should make your best effort to prevent breaking the pairing.

For example:

  1. If you are merging two users, and only one has been paired, then the newly merged user should take possession of the single pairing UUID you have. This is to ensure logins continue to work.
  2. If you are merging two users who are both paired, then you should choose one of the users to keep in LaunchPad, and send an identity update against the other one, marking it as deleted. Note that this also triggers a logout everywhere on the identity marked as deleted.
  3. If there is no way to avoid breaking the pairing, you should send identity updates for all identities involved and mark them as either archived or deleted, which will remove your application entirely from that end user’s LaunchPad.

If you’re running a multi-tenant SaaS application, which supports moving an user from one school to another, then the existing account pairing must be terminated as you move the user (an identity update triggered with status set to deleted). The end user will have to invoke the solo identity pairing workflow again to get their LaunchPad identity for your application re-connected.

Auto Identity Pairing

You can use auto identity pairing to pair up to 100 identities in a single request. If the individual identity already exists in LaunchPad then the title and status fields will be updated for the existing record.

POST https://launchpad.managebac.com/api/v1/identites/import

(signed and encrypted JWE)

{
  "school_api_key": "97c775fc-a7da-451d-b2e5-f7067ea250c5",
  "identities": [
    {
      "managebac_id": "MB98765",
      "pairing_value": "U01234",
      "status": "active/archived/hidden/suspended/deleted",
      "title": "Student"
    }
  ]
}
Key Description
school_api_key The ManageBac API key
identities Array of JSON identities

The JSON identities must be defined by the following keys:

Key Description
managebac_id The ManageBac UUID
pairing_value 3rd-party’s UUID
status A valid status [active, archived, hidden, suspended, deleted]
title A String representing the title of the identity

If there are no issues with the auto-login process you will receive a success response:

{
  "status": "success"
}

If there are any issues then the data key will contain the details.

{
  "status": "failure",
  "data": {"key": "message"}
}

Common error messages and their causes

Message Cause
'API will not process more than 100 identities in a single request’ More than 100 identities were sent for processing
'identities param must be Array’ Value for identities key must be an Array
'invalid API key’ Incorrect ManageBac API key
'identity payload is not valid’ JSON for identity is invalid
'managebac_id is not valid’ ManageBac ID for identity is invalid
'status is not valid’ A status other than active/archived/hidden/suspended/deleted

Similar steps and warnings apply for each individual user as with Solo identity pairing, especially resolving problems.

Building Your Integration

After reviewing this document, you should now be able to start working on an integration between LaunchPad and your application.

Critical integration steps

There are several major steps you must take to get the integration working:

  1. Review Faria’s requirements for a new LaunchPad integration, and update your application if necessary.
  2. Obtain and exchange credentials with your Faria contact.
  3. Implement Launchbar, to allow your end users to sign themselves into another application from your application.
  4. Implement Forward Authentication, to start allowing end users to sign into your application from the Launchbar or from LaunchPad itself.
  5. Implement Solo Identity Pairing, to allow your end users to link their own accounts in LaunchPad.
  6. Implement Log-out Everywhere, to terminate sessions for end users who have logged themselves out elsewhere.
  7. Implement Identity Updates, to keep information in LaunchPad up-to-date.

Common Integration Environments

Faria’s engineering team uses a variety of non-production environments for testing and demonstration purposes. You should expect to have to also provision multiple instances of your application during your integration journey.

Environment Use Case
Development For your development purposes you will have access to a fully-functional development environment running the latest version of LaunchPad. You can also request that these environments be reset from time to time in order to facilitate testing.
Demo Sandbox This is a quasi-production environment which participates in Faria’s product sandbox cluster. Your application must be prepared to reset itself hourly. If you can fulfil this requirement your application will be demonstrated as part of Faria’s Products Sandbox where applications from Faria and partners are linked together with live integration pathways.
Production Actual integration, monitored by Faria’s Technical Operations group. Your Faria contact can advise of SLAs and other guarantees relevant to your integration.

Once you decide which environments to integrate (usually, you will have to integrate several development environments and at least one sandbox environment in addition to the production environment), you can start reviewing requirements.

Integration requirements

You should review your application and make sure it supports the following features.

  1. Server-Side Sessions: This is a requirement of Logout everywhere,. If you plan to integrate that capability you should make sure this is in place.
  2. HTTPS: LaunchPad will only communicate with your application via HTTPS, and in the future we may limit our client to only work over certain OpenSSL cipher suites.
  3. JavaScript.: Launchbar requires JavaScript. Automatic login, requires JavaScript. The client-side encrypted POSTing used for transmitting data securely requires JavaScript.

Once your application is considered compliant, you can contact your Faria contact and exchange credentials, which will be useful for your upcoming integration.

If you are planning to integrate with LaunchPad in our Sandbox environment, you must fulfil the following, additional requirement:

  1. Timed Reset: Your application must reset itself to a known-good state every few hours, preferably via a remote API. Your Faria contact can further advise on why this is a requirement and on the benefits of your application being part of Faria’s Products Sandbox.

Integration credentials

For each environment, you generate a 2,048-bit RSA key pair. You will provide your Faria contact with your application’s boot endpoint (see section 9.4). This is where your public key will be published. In addition, you should be prepared to confirm your key’s fingerprint with your Faria contact.

LaunchPad’s own public key is easily retrievable via its own pubkey endpoint. See Section 9.3.

Common integration information

Your Faria contact will provide you with the following information relevant to a specific LaunchPad environment:

  1. Application Name,: The name of your application that shows on the Launchbar.
  2. LaunchPad API Endpoint,: The top-level endpoint for requests you need to make via the LaunchPad backend API.

The following additional information should be common to all LaunchPad environments:

LaunchPad Back-end API

Integrating with Faria LaunchPad allows your application to inter-operate with other applications built for Faria LaunchPad, including but not limited to ManageBac and OpenApply. All applications that participate within the LaunchPad scheme are available to users possessing relevant credentials.

Your application will use the LaunchPad Back-end API primarily to:

  1. Approve or deny sessions requested via the forward authentication mechanism.
  2. Retrieve all identities relevant to a given person, to render an in-app SSO Launchpad. (deprecated)
  3. Publish updated identities to the SSO Portal, to maintain data consistency.

Authentication

Client applications authenticating against the Launchpad API using RSA symmetric cryptography (each request is signed with your private key). All API requests are transmitted as Nested JWT. Because these Nested JWT packets are signed and encrypted they are also used for secure client-side transmission of data (any redirects between LaunchPad and your application that pass data, etc).

The encryption and signing process looks something like this (pseudo-code):

jwt = JWT(request params + metadata,  signed: your private key, alg: "RS512")
jwe = JWE(jwt, encrypt_with: Launchpad's public key)
version = "v0.1"
payload = version + ";" + jwe

You must encode the raw data via JWT and will resemble the following example:

{
  "data": { "API params" },
  "faria_source": {
    "name": ["your application name"],
    "uri": ["your applications unique uri"]
  }
  "api_url": ["normalized URL you are requesting"]
  "exp": ["Time now in UTC + 60 seconds converted to an integer"]
}

You need to use RS512 as the algorithm for the JWT cryptographic signatures. For more information on the JWE and JWT formats read the RFC documents:

  1. JWT
  2. JWE

When performing a POST, PUT, or PATCH operation you pass the JWE content as the request body. When performing a GET or DELETE operation you provide the JWE content in the Faria-JWE HTTP header. ContentType should always be set to application/jwe. Almost all API requests return JSON responses.

When redirecting from the client you should render an empty form and perform a POST of that form to the desired URL.

Example:

<form id='frm' action="https://launchpad.managebac.com/example" method="post">
  <input type="hidden" name="content_type" value="application/jwe" />
  <input type="hidden" name="payload" value="[JWE payload]" />
</form>
<script>
  document.findElementById('frm').submit();
</script>
<noscript>You must enable Javascript.</noscript>

You are free to extend this page as you see fit but it must contain these elements. Our goal is to have LaunchPad respond quickly to this request. This should be reserved for users on a very slow or unreliable Internet connection.

We have published a Ruby gem that handles most of this for you automatically as well as providing a simple Ruby API wrapper for LaunchPad. See launchpad_api for details.

All API calls outlined in this document require authentication (unless specified otherwise). All documentation below will show JSON as the input format but remember that this input must always still be wrapped in a valid JWE/JWT packet.

Working with Identities

The pairing process will connect an individual’s account on your client application with an identity inside of LaunchPad.

Anytime that individual’s metadata changes you should send an identity update request to LaunchPad with the new information. This also applies to major changes such as removal, archival, etc. i.e., If an individual’s account is deleted from your system it’s your responsibility to send LaunchPad a final identity changing that identity’s status to deleted.

Any such identity updates should be queued and permanently retried until they are acknowledged with a 200 OK. Failure to successfully push identity updates (after several retries) should be logged as a critical failure and brought to the attention of your Faria contact.

At this time there is no way to “unpair” an identity.

Identity Meta-data

  • Full name.
  • Title (Admin, Student, Parent) - This is the caption that will be shown next to your application in Launchpad.
  • Description (not currently used).
  • Status: active, hidden, suspended, archived, deleted.
  • School/Name: name of the school the individual is associated with.
  • School/Faria ID (KB-Organization-1234, etc.) (the internal Faria ID for the school, if you know it).

An identity update request

PATCH /api/v1/identities/by_pairing_value/1234

{
  "identity": {
    "name": "Jeremiah Smith",
    "status": "deleted",
    "title": "Student",
    "school": {
      "name": "Rogers Academy"
    }
  }
}

Only modified fields need to be included in your PATCH request.

If the identity’s school is not yet associated with a faria_id then including the school’s name gives you a way to change the name that is displayed inside LaunchPad for grouping accounts by school.

If you are aware that the identity’s school is already associated with a faria_id then there is no point in including the school key - at this point you may not change the faria_id, the school association, or the school’s name - the school key will be silently ignored.

Retrieving an identity

If you want to check the current status of any single paired identity you can do so:

GET /api/v1/identities/by_pairing_value/1234

{
  "value": "1234",
  "name": "Jeremiah Smith",
  "status": "active",
  "title": "Student",
  "description": "",
  "school": {
    "name": "Rogers Academy",
    "faria_id": "KB-Organization-95746"
  }
}

Utilities

The API offers a few utilities for simple queries and testing purposes.

ping

Pings the Launchpad services and returns “ok” if all is well along with the exact version of the API.

GET /api/v1/ping

Response:

{
  "ping": "ok",
  "version": "1.0.0"
}

Ping can be used even without authentication.

info

Provides data that might be useful for troubleshooting.

GET /api/v1/info

Response:

{
  "version": "1.0.0",
  "source": { "your reflected source information" }
}

pubkey

Provides Launchpad’s public key.

GET /api/v1/pubkey

-----BEGIN PUBLIC KEY-----
MIIBIjAN........................................................
01TzUhPT........................................................
D2jA2nan........................................................
2cUOGjsE........................................................
XBRgnBJ2........................................................
VwtiehX8........................................................
UwID....
-----END PUBLIC KEY-----

The response to this request will be text/plain. Pubkey can be used even without authentication.

echo

Provides a simple echo endpoint that returns the exact data back to you that you sent the API (albeit inside of the echo key).

POST /api/v1/echo

{ "hello": "world" }

Response:

{
  "echo": {
    "hello": "world"
  }
}

Interacting with authentication sessions

You will be asked by the Faria LaunchPad portal to evaluate authentication sessions via the forward authentication API. As a client application, you can only approve and decline those sessions linked to your own client application.

Each authentication session is linked to an identity (requested identity) and a person (requesting party). Only the client application owning the requested identity may respond to the authentication session.

An authentication session

The forward authentication request you are sent will include the full session payload in it’s signed parameters:

{
    "id": "78dab300-bb45-447d-8848-e4904acdc8b0",
    "pairing_value": "Tv2FoeVkVLv",
    "identity": {
        "id": "97c775fc-a7da-451d-b2e5-f7067ea250c5",
        "title": "Student",
        "status": "loginable",
        "pairing_value": "Tv2FoeVkVLv"
    },
    "person": {
        "family_name": "Stone",
        "given_name": "Doris",
        "id": "ea2c03cb-762c-48c6-801f-3df640f537e2"
    },
    "requested_at": "2014-09-05T16:48:13.414Z",
    "processed_at": null,
    "expires_at": null,
    "status": "requested",
    "initial_duration": 3600,
    "data": null
}

In the future, the data field will carry end-user-specific information, like the original IP address where requests occurred.

Approve an authentication session

POST /authentication_sessions/:session_id/approve

{
  "data": {}
}

Response

{
  "status": "approved",
  "id": "78dab300-bb45-447d-8848-e4904acdc8b0",
  "initial_duration": 3600
}

You should call this method if you have recognised the session and intend to approve it. Relevant information is captured by the LaunchPad portal for future auditing use. You must call this endpoint synchronously before completing the users login process. If this endpoint does not return an “approved” status then the login wont be successful.

You can emit anything relevant to your application under data. This might be information useful in the future for tracking errors or auditing.

Why might an approved status not be returned?

  1. Sessions are only held in “requested” status for 30 seconds. You must approve or decline a request within 30 seconds of receiving it. If this window has passed you will receive a 404 Not Found error instead of an approved session response.

  2. If the session has already been approved or declined you will also receive a 404 Not Found error. If two requests are issued simultaneously only the first will be approved. This is an attempt to mitigate any type of reply attack.

Decline an authentication session

POST /api/v1/authentication_sessions/:session_id/decline

{
  "data": {}
}

Response

{
  "status": "declined",
  "id": "78dab300-bb45-447d-8848-e4904acdc8b0"
}

You should call this method if something is wrong with the person’s claim. This way the LaunchPad portal will be alerted of repeated authentication failures. You may call this endpoint asynchronously outside of a forward authentication session, but be aware you still only have 30 seconds to return the declined status before the session is no longer available for updates.

If Launchpad is sending you regular login requests for users whose status has changed on your side then it’s likely you aren’t using the identity update API in a timely fashion. It’s recommended that if a session fails to be approved because a user no longer has access (locked out, archived, deleted, etc). that you immediately schedule an asynchronous background identity update to notify LaunchPad of the proper status of that user.

You can emit anything that is relevant to your application under data.

Requesting authentication sessions (deprecated)

Deprecated: This API call is deprecated and the responsibility of requesting a new authentication session is transferred to the Launchbar, a component that you will load from LaunchPad itself in an inline frame.

You need to implement this if you wish to build an identity LaunchPad within your application.

POST /authentication_sessions

Besides a valid client application token in your signed request, the following information is required:

  • requester_identity_id: The identity reference of the requesting user.
  • wanted_identity_id: The identity reference of the desired authentication target.

There are a few preconditions:

  1. The identity referred by requester_identity_id ('Requester Identity’) must be owned by the calling client application. In other words, you can only request authentication on behalf of one of your users.
  2. The identity referred by wanted_identity_id ('Requested Identity’) will implicitly reference the target application, and it is up to the target client application to determine whether it will grant access. Conventionally, the target client application will only recognise identities associated with a person who also holds the requester identity.

Generally, you will send this request synchronously after your user has requested authentication from your in-app identity launchpad.

If your request is successfully recognised (but not yet processed), you will receive the representation of the newly created authentication session with context.client_application_url, and you should then redirect the user. The target client application, which implements the forward authentication API, will handle everything from there.

{
  "context": {
      "client_application_url": "https://target.example.com/handle_forward_authentication?session_id=:session_id"
  },
  "data": null,
  "expires_at": null,
  "id": "78dab300-bb45-447d-8848-e4904acdc8b0",
  "identity": {
    "…"
  },
  "person": {
      "family_name": "Stone",
      "given_name": "Doris",
      "id": "ea2c03cb-762c-48c6-801f-3df640f537e2",
      "identities": [
        "…"
      ]
  },
  "processed_at": null,
  "requested_at": "2014-09-05T16:48:13.414Z",
  "status": "requested"
}

Configuring your Application with boot

This endpoint doesn’t require authentication.

GET /integrations/launchpad/boot

{
  "key": "-----BEGIN PUBLIC KEY-----\nMIIBIjAN...\n-----END PUBLIC KEY-----",
  "uri": "https://app.yourapp.com/integrations/launchpad/"
}

This endpoint provides LaunchPad the minimum information it needs to access your application’s configuration endpoint. Typically we set up your integration manually, but the boot endpoint offers the option to set some configuration manually.

Your uri is the preferred endpoint you would like LaunchPad to use for all further communication with your application. boot itself should fall within this same URI namespace. /launchpad/api/ is our preferred integration path.

If your application is multi-tenant and uses the subdomain as account-key pattern, your application will be required to support a single subdomain as the integration endpoint (app.yourapp.com, start.yourapp.com, etc.) and that subdomain will then be responsible for the necessary routing of individuals to other subdomains (such as during forward authentication, etc).

Libraries and sample implementations

For a sample implementation of Launchpad integration, see our sample Ruby on Rails project on GitHub. This application leans heavily on our launchpad_api gem.

If you’re building a Ruby application with a framework other than Rails we still recommend that you start with our gem. It makes quick work of a lot of the boilerplate encryption/decryption/signing work that has to be done.