@vehikl/igloo-server-proxy

Local oauth proxy server

This server should emulate igloo's proxy server for testing purposes

Note

If you are working on an older widget, you might need to specifically use the legacy branch, which is not public.

Integrating with an existing development server

Wrap your application bundler in an express app so all urls are relative/local. Use this for igloo widget repos when possible.

npm install --save @vehikl/igloo-server-proxy
# OR
yarn add @vehikl/igloo-server-proxy

import configureIglooServerProxy from "igloo-server-proxy"
import * as express from "express"
const HTTP_PORT = 3000

const app = express.app()

const proxyOptions = {
  useLegacy: true,
  servicesPath: 'path/to/services'
};

configureIglooServerProxy(app, HTTP_PORT, proxyOptions)
// app - express server
// HTTP_PORT - the port express is serving on
// proxyOptions.useLegacy - load up <host>/<service name>/* oauth endpoints
// proxyOptions.servicesPath - load service config json files from this absolute path

server.listen(HTTP_PORT)

Adding new services

Services should contain the following json:

{
  "clientID": "some-client-id-from-service",
  "clientSecret": "some-client-secret-from-service",
  "site": "http://the-site-where-oauth-happens",
  "authorizationPath": "full/path/to/oauth/authorize",
  "tokenPath": "full/path/to/oauth/token",
  "scope": "Any.scopes Defined.by The.service OrA.EmptyString",
  "resource": "optional/resource",
  "callbackPath": "optional/callback/path",
  "applicationIds": ["ig-name-of-thing"]
}

Both resource and callbackPath are optional, and can be omitted.

authorizationPath and tokenPath can be full URLs if they are not prefixed by the same site. If the path starts with http:// or https://, it will be considered a full URL, otherwise, site will be prefixed to create a full URL.

It is important that the applicationIds match what the widget is submitting so it knows what service to map things to.

To easily add a service, you can use:

npx @vehikl/igloo-server-proxy new

Otherwise service json files are created in constants.js#DEFAULT_SERVICES_PATH.

Test refresh flow

Tokens get persisted, and by default, should be stored in ~/.igloo-proxy-tokens.json. To test refresh flow, log into a service, so the token is properly stored. Then open ~/.igloo-proxy-tokens.json, find the appropriate service, then set ig-yourservice.access_token to either an empty string, or update it with new characters (making the access token invalid). Now refresh the web app, and you should see an initial 401 call through the proxy, followed by the refresh flow.

URL Mapping

OAuth 2.0

All new OAuth endpoints are prefixed with /.api2/api/v1/communities/{communityKey}/oauth2. If the server has useLegacy set to true, there will also be endpoints for /{service-name}, but these should not be relied on. Note that the legacy endpoints are not 1:1 for the newer igloo emulation, only use those if necessary with older widgets.

GET {prefix}/authorize

This endpoint will redirect to the oauth sign-in page, and is often in a pop-up window.

Parameters:

Name	Required?	Description	Value
applicationId	Yes	Value mapping to your service.json file	ig-{servicename}
authorizeUri	Yes	Full service authorize URL	https://some-service.com/oauth2/authorize
tokenUri	Yes	Full service get token URL	https://some-service.com/oauth2/token
scope	Yes	OAuth scope specification. See your oauth provider's documentation for real values.	May contain values like email profile
tokenSubKey	No	Some services require a token sub key, in instances where igloo has two matching applicationIds.	Unknown

Response:

HTTP Status Code	Description	Body
200 OK	Success	None
4xx	Authentication Error	None
Anything else	Server Error	None/Server Message?

GET {prefix}/token

DELETE {prefix}/token

This endpoint retrieves manages the current oauth tokens The GET variant retrieves it, the DELETE variant will remove it.

Parameters:

Name	Required?	Description	Value
applicationId	Yes	Value mapping to your service.json file	ig-{servicename}

Response:

HTTP Status Code	Description	Body
200 OK	Success	(Using GET) { access_token: A, refresh_token: B, expiresAt: C }
4xx	Authentication Error	None
Anything else	Server Error	None/Server Message?

POST {prefix}/refreshtoken

This endpoint retrieves the current access and refresh tokens associated with the service. This will refresh the tokens in the igloo server, but will require a secondary call to GET {prefix}/token to get the updated tokens.

JSON Body:

Name	Required?	Description	Value
ApplicationId	Yes	Value mapping to your service.json file	ig-{servicename}
RefreshToken	Yes	The refresh token, from GET {prefix}/token	An OAuth token
RefreshTokenURI	Yes	Full service refresh token URL	https://some-service.com/oauth2/refresh

Headers:

Name	Required?	Description	Value
Content-Type	Yes	Tell the server the post body format	application/json

Response:

HTTP Status Code	Description	Body
200 OK	Success	None
4xx	Authentication Error	None
Anything else	Server Error	None/Server Message?

Configuring a Service

Server-Side

• Redirect URL: http://your-server-proxy-address:port/.api2/api/v1/communities/{your-community-key}/oauth2/callback
  • Make take the form of http://localhost:3000/.api2/api/v1/communities/igloo-key==/oauth2/callback