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