User Guide

s3o (Staff Single Sign On) is a service for securing FT applications using Google 2FA. This page is aimed at developers using s3o to secure their application.

FT Platform

If your application is running on FT Platform, it's recommended that you use the ft-s3o_wrapper puppet module.

Basic Usage

If your application doesn't do anything fancy, it's just a matter of including the module as a dependency and giving it a puppetDB query which points to your backend nodes. For example:

  class { 's3o_wrapper':
    backend_query => 'Service[Apache]',
  }

Be sure to read the module's README to avoid any potential pitfalls.

Advanced usage

The ft-s3o_wrapper module uses varnish under the hood. You can pass it your own custom VCL to take advantage of more of varnish's features. For example, you can specify bespoke logic to decide which URLs should be authenticated and which shouldn't.

See the ft-varnish module's README for more information, including some examples.

Node.js

If you are using node.js, it is recommended that you use the S3O-middleware module for express. See the README for more details.

Direct API usage

Your application can talk to s3o's API directly.

API methods

/authenticate
The /authenticate endpoint is the main entry into the system and starts the flow for providing the username and token to allow the calling service to log in a user. The endpoint expects certain request params to send it down different routes
Request ParamOptionalFormatReason
redirectNohttp://[server]/[path]Used for initial request into application. This should be set to the endpoint s3o should redirect to after a successful login
codeYesStringUsed internally by s3o
stateYesStringUsed internally by s3o
cookiekeyYesStringUsed to determine whether the s3o service should set the username and token data as cookies rather than response params
Deprecated - may be removed in future versions of s3o
Response

The response provided by the application will follow this template and will depend on whether the cookiekey param was passed in /yourAppAuthUrl/?username=[username]&token=[token] If the cookie key param was specified then 2 cookies will be set with the cookie key prefix followed by username and token and will contain the values. As an application calling the s3o service you only need to worry about calling /authenticate?redirect=[yourAppAuthUrl]. The username will be set to the user's AD username. The token is a result of signing that username with s3o's private key. You can check whether the user came from s3o by using s3o's public key (see below) and the token to verify the username.

/publickey

The /publickey endpoint returns the applications public key which can be used by the calling service to validate the authenticity of the data that was returned from the /authenticate endpoint.

The response will be served as plaintext. It will be DER encoded. If you require it to be PES encoded, you will need to convert it yourself

For an example of an application which uses s3o directly, see Clamo Engine.

/v2/authorize

The /v2/authorize endpoint provides an API to verify that a user belongs to an AD group, it can be used to protect resources based on group membership in AD

It returns a 200 if user is in group otherwise it returns a 403

Request ParamOptionalFormat
groupsNoAD group name
/token/validate

The /token/validate endpoint provides an API to validate token signed by service

It returns a 200 if token is valid otherwise it returns a 403

Comparison of Options

Features3o_wrapperS3O-middlewareDirect API
Works on FT PlatformYesYesYes
Works on HerokuNoYesYes
Unopinionated about language/framework usedYesNo. Requires node.js and expressYes
Can get set up quicklyYesYesNo. Requires you to write your own code.
Will handle changes to s3o keys
(automatically within 5 minutes of a change)
YesYesNo

User Management

Adding Additional Users

Anyone with an ft.com Google account will automatically have access to s3o protected systems. External contributors (eg guest bloggers) will need their email address added to a whitelist. Note that we only have the power to enforce 2FA on ft.com accounts. Before adding someone to the whitelist, you should check that they have 2FA enabled on their Google account.

Revoking a User's Access

For external users (ie those with non ft.com email addresses), remove them from the whitelist. For ft.com users, disable their Active Directory account. (You may need to contact the IT Service Desk to do this)