enmobile/oauth2-proxy repository overview

This image is built using the OpenResty⁠ alpine:fat image and incorporates the lua-resty-oidc⁠ library to easily protect an application using standard OAuth2 via environment configuration.

The following environment variables are required to be set at a minimum for it to run:

• OAUTH2_DISCOVERY_URL - this is the OAuth2 discovery URL
• OAUTH2_CLIENT_ID - this is the client id from the OAuth2 provider
• OAUTH2_CLIENT_SECRET - this is the client secret from the OAuth2 provider and is required if OAUTH2_USE_PKCE=false
• OAUTH2_TRUSTED_CERTS_PATH - this is the path on the container that contains the certificate store and defaults to "/etc/ssl/certs/ca-certificates.crt"
• OAUTH2_SSL_VERIFY_DEPTH - this is the level at which certificate chains will verify in terms of their depth and defaults to 5
• OAUTH2_DISCOVERY_CACHE_SIZE - this is the size of the OAuth2 providers discovery cache and defaults to 10m (megabytes)
• OAUTH2_JWKS_CACHE_SIZE - this is the size of the JWK cache and defaults to 100m (megabytes)
• OAUTH2_INTROSPECTION_CACHE_SIZE - this is the size of the instrospection cache and defaults to 10m (megabytes). If introspection exists then the size of this should be increased
• RESOLVER - this is the NGINX resolver to use and defaults to "local=on". As this is meant to run containerized, this should be left as-is since it will inspect the resolve.conf within the running container

The following are required, but have default values in the image:

• OAUTH2_REDIRECT_URI - this is the URL where the OAuth2 provider should redirect back to after a successful authentication flow. It defaults to http://localhost⁠ and can be a fully qualified path or simply a URI, in which case the current host is prepended
• OAUTH2_TOKEN_ALGORITHM - this is the expected algorithm of the OAuth2 provider uses for encryption and defaults to RS256
• OAUTH2_SCOPE - this is the specific set of scope(s) separated by a single space and defaults to "openid email profile"
• OAUTH2_VERIFY_SSL - this is a "yes/no" flag that will attempt to verify the SSL chain and defaults to "no". If set to true, you must perform the the certificate steps on you container yourself and see OAUTH2_TRUSTED_CERTS_PATH
• OAUTH2_USE_PKCE - this is a true/false flag on whether or not the OAuth2 provider is to use PKCE and defaults to false. If this is set to true, then OAUTH2_CLIENT_SECRET is not required
• OAUTH2_RESPONSE_TYPE - this is the type of response expected back from the OAuth2 provider upon a successful authentication and defaults to code and most likely shouldn't be changed
• OAUTH2_ACCEPT_NONE_ALGORITHM - this is a true/false flag the indicates whether or not the OAuth2 provider does or does not sign the tokens and defaults to false
• OAUTH2_ACCEPT_UNSUPPORTED_ALGORITHM - this is a true/false flag that indicates whether or not the token signature will or will not be verified when an unsupported algorithm is used and defaults to false
• OAUTH2_RENEW_EXPIRED_ACCESS_TOKEN - this is a true/false flag that indicates whether to or not silently renew the access token once it is expired if a refresh token is available. If it fails to renew the token, the user will be redirected to the OAuth2 provider authorization endpoint and defaults to true
• OAUTH2_ACCESS_TOKEN_EXPIRES_IN - this specifies the amount of time an access token can live for in seconds and defaults to 3600
• OAUTH2_LOGOUT_PATH - this is a virtual path on the running container where logout actions can be called which in turn redirects to the OAuth2 providers logout URL and defaults to "/logout". It is suggested not to have a concrete URI mapped whereby you want to do additional logout cleanup, and instead handle that in the OAUTH2_POST_REDIRECT_LOGOUT_URI
• OAUTH2_REDIRECT_LOGOUT_ID_TOKEN_HINT - this is a true/false flag that controls whether the redirection after logout should include the id token as an hint (if available). This option is used only if OAUTH2_POST_REDIRECT_LOGOUT_URI is set to true and defaults to false
• OAUTH2_SESSION_REFRESH_INTERVAL - this specifies the amount of time in seconds that an id_token can exist without requiring re-authentication and defaults to 900
• OAUTH2_REDIRECT_AFTER_LOGOUT_URI - this specifies where should the user be redirected after logout from the RP, and overrides any end_session_endpoint that the OAuth2 provider may have provided in the discovery response and defaults to ""
• OAUTH2_POST_REDIRECT_LOGOUT_URI - this specifies where the RP requests that the OAuth2 provider redirects the user after logout. If this option is set to a relative URI, it will be relative to the OAuth2 provider's logout endpoint, not the RP's and defaults to ""
• OAUTH2_ACCESS_TOKEN_LEEWAY - this specifies the time in seconds expiration leeway for access_token renewal. If this is set, renewal will happen this many seconds before the token expiration. This avoids errors in case the access_token just expires when arriving to the OAuth Resource Server and defaults to 600
• OAUTH2_ID_TOKEN_LEEWAY= this specifies the time in seconds expiration leeway for id_token renewal. If this is set, renewal will happen this many seconds before the token expiration. This avoids errors in case the id_token just expires when arriving to the OAuth Resource Server and defaults to 600
• OAUTH2_SESSION_CONTENT - this defines a whitelist of session content to enable in order to reduce the session size and can be one or the other or both of "id_token=true,access_token=true" and defaults to ""
• OAUTH2_PROVIDER_TIMEOUTS - this defines the timeout(s) to associated with the OAuth2 provider and can be one or any combination of "connect = 500,send = 1000,read = 1000" and defaults to ""
• OAUTH2_USE_NONCE - this is a true/false flag that tells whether or not the authorization request includes the nonce parameter and defaults to false
• OAUTH2_LOGOUT_REMOVE_TOKENS - this is a true/false flag notifies the authorization server that previously obtained refresh and access tokens are or are no longer needed. This requires that revocation_endpoint is discoverable. If there is no revocation endpoint supplied or if there are errors on revocation the user will not be notified and the logout process continues normally and defaults to false
• OAUTH2_PROVIDER_KEEPALIVE - this is a yes/no flag that says whether to or not enable connection keepalive with the OAuth2 provider and defaults to "no"
• OAUTH2_TOKEN_AUTH_METHOD - this specifies the method in which authentication is performed on the OAuth2 provider in terms of 1 of the following "client_secret_basic", "client_secret_post", "private_key_jwt", or"client_secret_jwt"] and defaults to "client_secret_post"
• OAUTH2_AUTH_ACCEPT_TOKEN_AS - this defines how the access_token is to be be passed to this container and can be "cookie:cookie_name" or "header:header_name" and defaults to "" which in turn defaults to "Authorization: bearer"
• OAUTH2_LIFECYCLE_CALLBACKS - this defines Lua function callbacks on this container and can be one or more of the following "on_created = handle_created, on_authenticated = handle_authenticated, on_regenerated = handle_regenerated, on_logout = handle_logout" and defaults to ""
• OAUTH2_REQUEST_DECORATOR - this defines a function that can be used to decorate the outgoing request to the OAuth2 provider prior to an authentication and defaults to "". If can be used to add headers or other manipulation and is a simple function that has a request passed in its argument:

function(request)
  // do something to request
  return request
end

• LOG_LEVEL - this defines the NGINX logging level and follows the standard levels defaulting to "info"
• ENABLE_CORS_SUPPORT - this is a true/false flag that when set to true will automatically use the OAUTH2_DISCOVERY_URL and add the appropriate CORS headers to the requests and defaults to true
• PROTECT_ALL - this is a true/false flag that protects everything from the root / with the OAuth2 provider and defaults to true
• SESSION_SECRET - this is recommended to be set and is simply a random secret to use for the sesssion and can be set in one of 2 ways on the container in the default.conf:

set_by_lua_file $session_secret /etc/nginx/conf.d/lua/session.lua;

or the nginx way:

set $session_secret YOUR_SECRET;

When you add the required OAuth2 environment variables as mentioned above, you can simply run a container to test. Hitting http://localhost⁠ should prompt the OAuth2 provider to login in. Upon a success, it will display a success page, and a logout link.

This is NGINX, so all you need to do is identify your location mappings and then mount the volume if running locally using Docker Compose, or as a part of you image build. Here is an example default.config:

upstream api-service {
    server api-service:9000;
}

upstream web-service {
    server web-service:9090;
}

server {
    listen 8000;
    charset utf-8;
    client_header_buffer_size 128k;
    large_client_header_buffers 16 128k;
    set_by_lua_file $session_secret /etc/nginx/conf.d/lua/session.lua;

    location /api/v1 {
        proxy_pass http://api-service;
    }

    location /api/v2  {
        proxy_pass http://api-service;
    }

    location / {
        proxy_pass http://web-service;
    }
}

docker-compose:

volumes:
      - ./myconfig/default.conf:/etc/nginx/conf.d/default.conf

DOCKERFILE

COPY myconfig/default.conf /etc/nginx/conf.d/default.conf

Doing a config above will protect every endpoint location. If you only want to protect a certain location, then:

1. Set the PROTECT_ALL environment variable to false

2. Add a *_by_lua_file (depends on the phase you desire) to your protected location block:

location /api/v1 {
    rewrite_by_lua_file /etc/nginx/conf.d/lua/authenticate.lua;;
    proxy_pass http://api-service;
}