microgateway-plugin-sso-proxy

** THIS IS PRE-RELEASE, UNSUPPORTED SOFTWARE, AND SUBJECT TO CHANGE **

Provides transparent SSO authentication services to components behind this proxy. This can run as a plugin for Edge Microgateway or can be run standalone. (Note: Requires access to Edge Microgateway either way.)

Usage:

• npm install
• cp config/sample.yaml config/default.yaml
• Edit config/default.yaml
• npm start

Configuration hints:

You may setup multiple configs and select between them by setting the NODE_ENV env var.

You may use env vars to override values in your config, see config/custom-environment-variables.yaml

e2e endpoints:

authorizationURL: https://login.e2e.apigee.net/oauth/authorize
tokenURL: https://login.e2e.apigee.net/oauth/token
callbackURL: http://localhost:3000/auth/sso/callback

prod endpoints:

authorizationURL: https://login.apigee.net/oauth/authorize
tokenURL: https://login.apigee.net/oauth/token
callbackURL: http://localhost:3000/auth/sso/callback

Protocol

1. Proxy will validate JWT included as authorization header bearer token or access_token cookie.
2. Proxy will automatically refresh an expired or missing access_token cookie with refresh_token cookie if present.
3. Proxy will intercept 401 from target and start OAuth 2.0 authorization flow using a 401 and meta tag redirect (url will also be in location header)
4. Proxy will redirect to original url (or value of x-restart-url header) after auth flow if GET request. This value will be passed in the state query var during the OAuth flow.
5. Proxy will only ever pass a valid JWT access token in the Authorization header as a Bearer token to the target.

For the entire flow, please see this diagram:

Sequence Diagram

diagram source:

sequenceDiagram
participant Browser
participant Proxy
participant Service
participant SSO
Note left of Browser: Start request...
Browser->>Proxy: req
Note left of Proxy: may include "x-restart-url" header
Proxy->>Proxy: check authorization header (Bearer) or access_token cookie for JWT
Proxy-->>SSO: if expired, refresh using refresh_token cookie
Proxy->>Service: req w/ Authorization header Bearer token
Service-->>Browser: if no auth needed, just continue
Service->>Proxy: 401 if auth missing and needed
Proxy->>Browser: 401 + meta redirect to start auth flow
Note left of Proxy: flow start url in location header, restart url in state query var (only for GET reqs)

Note left of Browser: Standard OAuth 2.0 auth code flow...
Browser->>SSO: Get login form
SSO->>Browser: Login form
Browser->>SSO: Post login (or to another OAuth login provider)
SSO->>Browser: 302 + auth code
Browser->>Proxy: auth code to oauth callback
Proxy->>SSO: Verify auth code
SSO->>Proxy: access and refresh JWTs

Note left of Browser: Finish request...
Proxy-->>Browser: If no restart url, 200 w/ "authenticated" in body
Proxy->>Browser: If restart url, 302 to restart url
Note right of Browser: sets access_token & refresh_token cookies
Browser->>Proxy: req w/ access_token JWT cookie
Proxy->>Proxy: Verify JWT
Proxy->>Service: req w/ Authorization header Bearer token
Service->>Service: check Authorization header Bearer token
Service->>Browser: response