@prxi/openid-connect v1.4.8

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

Logs

Prxi Request Paths

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.

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

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

Mappings & JWT Claims Path

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" ]
}

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

Headers

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.

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.

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.

Links

• Docker Image official Docker image
• GitHub Repository
• @prixi/dev a simple CLI reverse proxy tool for local development purposes, can be handy to simulate fireblink/prxi-openid-connect setup without a need to run docker container and/or setup test IDP configuration

IDP Specific Configuration Details

• AWS Cognito User Pool
• Keycloak

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.