fireblink/prxi-openid-connect

OpenID Connect reverse proxy server that based on a zero-dependency proxy library prxi.

Can be used to provide SSO login (Authentication/Authorization) functionality to any web application or API service, or both at the same time. In most of the cases prxi-openid-connect should be deployed in front of your application to intercept all the requests:

Proxy will handle authentication and authorization for individual path mappings, by allowing access only if JWT token contains allowed claims.

Proxy clearly distinguish API and HTML requests, so when access token expires (and can't be refreshed) or missing API request won't return HTML of the login page, but a JSON error object and correct http status code (401). The same applies to a case when access is denied for a user for requested resource (403 error)

In addition upon every login, logout or token refresh action prxi-openid-connect can call optional webhook endpoints and even change the flow based on the response. This might be handy to track audit logs, request token refresh one more time, etc.

Configuration

Environment Variables

Generic settings

Name	Required	Default Value	Description
`LICENSE_CONSENT`	Yes		`true` value should be provided when you agree to use prxi-openid-connect under the current license terms. Please refer to the License for more details
`MODE`	No	`HTTP`	Server mode, can be either `HTTP` or `HTTP2` (default value: `HTTP`). Note: when HTTP/2 is enabled, upstream should also support it, dynamic conversion from HTTP/2 to HTTP/1.1 is not supported.
`PORT`	No	`3000`	Port number to listen the incoming connections on
`HOSTNAME`	No	`localhost`	Hostname to listen incoming connections on
`HOST_URL`	Yes		Public facing Host URL
`PROXY_REQUEST_TIMEOUT`	No	`30000`	Timeout for the proxy requests
`UPSTREAM_URL`	Yes		Upstream URL
`JWT_META_TOKEN_SECRET`	No		Secret string to sign JWT with custom user meta attributes (if returned by the login webhook)

Logs

Name	Required	Default Value	Description
`LOG_LEVEL`	No	`info`	Log level
`LOG_FILE`	No		Log file path
`LOG_ROTATE_DATE_PATTERN`	No	`YYYY-MM-DD_HH`	Log rotation `%DATE%` format
`LOG_ROTATE_MAX_SIZE`	No	`100m`	Maximum size of the file after which it will rotate. This can be a number of bytes, or units of kb, mb, and gb. If using the units, add 'k', 'm', or 'g' as the suffix. The units need to directly follow the number.
`LOG_ROTATE_MAX_FILES`	No	`5`	Maximum number of logs to keep. If not set, no logs will be removed. This can be a number of files or number of days. If using days, add 'd' as the suffix. It uses auditFile to keep track of the log files in a json format. It won't delete any file not contained in it. It can be a number of files or number of days
`LOG_PRETTY`	No	`false`	If set to `true`, human readable formatting will be used instead of a JSON

Prxi Request Paths

Name	Required	Default Value	Description
`HEALTH_PATH`	No	`/_prxi_/health`	Health check api path
`LOGIN_PATH`	No	`/_prxi_/login`	Login endpoint path. When calling, optional `redirectTo` query parameter can be passed to redirect user to a given url after login
`LOGOUT_PATH`	No	`/_prxi_/logout`	End session/logout path

TLS Settings

Following environment variables allows dynamic configuration of TLS settings. For the whole list of options please refer to https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options

All the <property> values will be converted from snake_case to camelCase.

Name	Required	Description
`TLS_FILE_<property>`	No	Load file into a buffer from the provided path and set it to the `<property>` field
`TLS_STRING_<property>`	No	Set string value into `<property>` field
`TLS_NUMBER_<property>`	No	Set number value into `<property>` field

Note: when TLS is enabled upstream server should also support secure connection. Dynamic conversion from Secure to non-Secure connection is not supported. To accept self-signed certificate of the upstream service use NODE_EXTRA_CA_CERTS to set additional certificate.

OIDC settings

Name	Required	Default Value	Description
`OPENID_CONNECT_DISCOVER_URL`	Yes		Discovery URL, public endpoint to fetch openid-configuration from
`OPENID_CALLBACK_PATH`	No	`/_prxi_/callback`	Callback path that Provider will call upon successful login to exchange code to tokens
`OPENID_CLIENT_ID`	Yes		Client ID
`OPENID_CLIENT_SECRET`	No		Client Secret
`OPENID_SCOPE`	No	`openid email profile`	Scope of the claims

Discovery URL examples (OPENID_CONNECT_DISCOVER_URL):

For KeyCloak https://{host}/realms/{realm}/.well-known/openid-configuration
For AWS Cognito https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/openid-configuration

Cookies

Name	Required	Default Value	Description
`COOKIES_SECURE`	No	`true`	A cookie Secure attribute
`COOKIES_PROXY_TO_UPSTREAM`	No	`true`	Whether prxi-openid-connect specific cookies should be proxies to the upstream service
`COOKIES_ACCESS_TOKEN`	No	`prxi-at`	Access Token cookie name
`COOKIES_ID_TOKEN`	No	`prxi-it`	ID Token cookie name
`COOKIES_REFRESH_TOKEN`	No	`prxi-rt`	Refresh Token cookie name
`COOKIES_ORIGINAL_PATH`	No	`prxi-op`	Cookie name to hold originally request path, only applicable to the HTML page request
`COOKIES_META`	No	`prxi-meta`	Cookie name to hold meta information about the user, only used if login webhook returns `meta` object

Mappings & JWT Claims Path

Name	Required	Default Value	Description
`JWT_AUTH_CLAIM_PATHS`	No		JSON object representing paths (array of strings) to obtain mappings from both Auth/ID token payloads.
`JWT_PROXY_CLAIM_PATHS`	No		JSON object representing paths (array of strings) to obtain mappings to extract from both Auth/ID token payloads. Value is passed as a JSON with the `HEADERS_CLAIMS_PROXY` header to the upstream service and returned by the "Who am I?" API. General usecase is to extract user related information like username, email, given name, etc.

Path example:

{
  # Every path should have a name.
  # Value is an array of string representing nested object fields starting from JWT payload
  # In this example payload.a.b.c will be used to access the claims array
  "name": [ "a", "b", "c" ]
}

Name	Required	Description
`MAPPINGS_PUBLIC`	No	JSON array with public facing path patterns (no authentication/authorization actions will be performed)
`MAPPINGS_PAGES`	No	JSON array with web application pages, generally should refer to the endpoints that return HTML content, as in case of 401 error, proxy server will redirect user to the IDP login page.
`MAPPINGS_WS`	No	JSON array with WS paths, works similar to `MAPPINGS_API`, but in case of 401 error server will respond with just the status code.
`MAPPINGS_API`	No	JSON array with API paths, works similar to `MAPPINGS_PAGES` but in case of 401 error server will respond with an error.

Error example:

{
  "error": true,
  "details": {
    "message": "Unauthorized",
    "code": 401,
  }
}

Mappings format:

[
  # each mapping can have 0 or many mappings
  {
    # each mapping requires a RegEx pattern to match the path, note: ^ and $ characters can be omitted
    "pattern": "/public/.*",
    # [optional] define authorization rules
    # if "auth" is not provided, unauthorized access is allowed
    "auth": {
      # [optional] when "false", allows either unauthorized or a claims hit to GRANT access, default value "true", meaning only authorized access is allowed
      "required": false,

      # [optional] claims matching mode, can be:
      #    "ANY" - default value, any of the claims grant user access
      #    "ALL" - only when all the claims are included access will be granted
      "mode": "ANY",

      # [optional] list of JWT claims to match over
      "claims": {
        # claims can reference one or many named paths (refer to the JWT_AUTH_CLAIM_PATHS environment variable configuration)
        "name": [
          # a hit on EITHER ONE of the claims will GRANT access to the resource
          "role1",
          "role2"
        ]
      }
    }
  }
]

It is highly recommended to intercept 401 errors on the Web Application side and reload the page, so MAPPINGS_PAGES mapping flow is triggered and user gets redirected to the login page.

Redirects

Name	Required	Description
`REDIRECT_PAGE_REQUEST_ON_403`	No	URL to redirect when access is forbidden
`REDIRECT_PAGE_REQUEST_ON_404`	No	URL to redirect when no mapping found for requested path
`REDIRECT_PAGE_REQUEST_ON_500`	No	URL to redirect when unexpected error occurred
`REDIRECT_PAGE_REQUEST_ON_503`	No	URL to redirect when connection to the upstream service cannot be established

Headers

Name	Required	Description
`HEADERS_CLAIMS_AUTH_ALL`	No	Header name to pass all the auth claims extracted from access/id tokens before calling the upstream service
`HEADERS_CLAIMS_AUTH_MATCHING`	No	Header name to pass just the matching auth claims extracted from access/id tokens before calling the upstream service
`HEADERS_CLAIMS_PROXY`	No	Header name to pass extracted attributes from both access and id tokens (useful to extract such information as username and/or email), definition of claims to pass should be described via `JWT_PROXY_CLAIM_PATHS` environment variable (see above)
`HEADERS_INJECT_REQUEST`	No	JSON object of additional headers to apply to the request before calling the upstream service
`HEADERS_INJECT_RESPONSE`	No	JSON object of additional headers to apply to the response

Example:

{
  # null value removes the header from the request/response
  "Authorization": null,
  # non-null value adds/overrides header in the request/response
  "Content-Security-Policy": "default-src 'self'"
}

Webhooks

prxi-openid-connect can optionally make WebHook requests upon certain user action, like login and/or logout.

APIs

prxi-openid-connect can optionally expose additional API endpoint. Such APIs help to provide better UX, e.g. by hiding menu options that user can't access due to the permission restrictions.

Remote configuration

One of the key features of prxi-openid-connect is the ability to load configuration from the remote instance and refresh it periodically. To obtain the admin applicationclick here to get in contact for the commercial agreement.

Name	Required	Default Value	Description
`REMOTE_CONFIGURATION_ENABLED`	No	`false`	Set to `true to enable remote configuration loading
`REMOTE_CONFIGURATION_INTERVAL`	No	`30`	Time interval in seconds to load the configuration from the remote service
`REMOTE_CONFIGURATION_ENDPOINT`	No		Endpoint to load the configuration from
`REMOTE_CONFIGURATION_TOKEN`	Yes		Bearer token to include in the request

Remote configuration request headers:

x-prxi-version - version of the prxi-openid-connect
x-prxi-config-version - version of the configuration, on first load it will equal 0

Upstream Headers

Upstream service may respond with custom headers to control the prxi-openid-connect behavior.

Name	Value	Description
`X-Prxi-Refresh-Tokens`	any	When header is returned by the upstream service, prxi-openid-connect will refresh any existing tokens (access/id)

HTMX Support

Every time prxi-openid-connect needs to send a redirect it checks an incoming request to have the Hx-Boosted header. If header is found and its value is true then prxi-openid-connect will return 200 status code with Hx-Redirect header instead of making a standard HTTP redirect.

IDP Specific Configuration Details

License

This project is distributed under dual licensing.

Quick Summary

This project can be used for free of charge for:

Personal Uses
Noncommercial Organizations

This project also provides 30 days of evaluation period for commercial products and services. After the evaluation period additional license should be obtained or project stopped from being used.

More can be found in LICENSE.md

Contact Information

To obtain a commercial license click here to get in a contact.

@prxi/openid-connect

fireblink/prxi-openid-connect

Configuration

Environment Variables

Generic settings

Logs

Prxi Request Paths

TLS Settings

OIDC settings

Cookies

Mappings & JWT Claims Path

Redirects

Headers

Webhooks

APIs

Remote configuration

Upstream Headers

HTMX Support

Links

IDP Specific Configuration Details

License

Quick Summary

Contact Information

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

@prxi/openid-connect

fireblink/prxi-openid-connect

Configuration

Environment Variables

Generic settings

Logs

Prxi Request Paths

TLS Settings

OIDC settings

Cookies

Mappings & JWT Claims Path

Redirects

Headers

Webhooks

APIs

Remote configuration

Upstream Headers

HTMX Support

Links

IDP Specific Configuration Details

License

Quick Summary

Contact Information

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads