Deployment

Deployment

Loginbuddy is developed as Docker image based on tomcat:jdk11-openjdk. That makes it an image with a very small footprint.

With that, Loginbuddy can easily run as standalone OpenID Connect proxy server or as a sidecar container.

Standalone OpenID Connect proxy

Loginbuddy is configured with registered clients and supported OpenID providers such as google. The container exposes ports 80 and 443, has a publicly accepted TLS certificate and its own hostname. This scenario is reflected in Figure 01:

Figure 01: Loginbuddy deployed as standalone OpenID Connect proxy

Details on Figure 01 (there are variations, this is the 'default')

• 1: web application is a registered oauth/openid connect client of Loginbuddy
  • web application follows the same rules as for any other oauth server (it has a client_id, a redirect_uri and other attributes)
  • web application uses the authorization_code flow to request the users authorization. First stop is Loginbuddy where users choose their favorite provider. Loginbuddy then redirects the user to the chosen provider using its own authorization_code flow with the provider
  • web application receives an authorization_code, issued by Loginbuddy
  • web application uses the received code to exchange it for the token response that was produced by the chosen OpenID provider, available through Loginbuddy
• 2: Loginbuddy is a registered oauth/ OpenID Connect client of each supported OpenID provider
  • Loginbuddy uses the authorization_code flow with PKCE to retrieve the users authorization
  • Loginbuddy follows the flow including the token exchange, id_token validation, retrieval of the userinfo response
  • Loginbuddy conveyes the complete response of the OpenID provider to web application via its own /token endpoint

Benefits of this deployment

• web application only needs to communicate with Loginbuddy
• web application does not need to communicate with any of the OpenID providers
  • Loginbuddy validates any received id_token
  • Loginbuddy normalizes any responses so that web application can expect the same response structure no matter which OpenID provider was chosen
  • Loginbuddy includes the token response of the OpenID provider, the /userinfo response, the plain JSON payload of the id_token when web application exchanges the code for the token response
• multiple web applications can be registered with Loginbuddy

Disadvantages of the deployment

• web application needs to handle the OAuth authorization_code flow
• users get redirected twice
• Loginbuddy needs its own non-self-signed TLS certificate

When should you use this setup?

• whenever you use Loginbuddy with multiple web applications
• web application cannot join the same docker network when running on the same host

Sidecar

Loginbuddy is configured for one web application only and is practically hidden from clients. Loginbuddy becomes part of the web application. Figure 02 displays this setup

Figure 02: Loginbuddy deployed as sidecar of the web application

Details on Figure 02

• 1:
  • web application connects to Loginbuddy to retrieve a valid authorization request URL for the target OpenID provider
  • web application receives the code response of the OpenID provider and conveyes it to Loginbuddy, nothing else
• 2:
  • Loginbuddy runs through the token exchange flow, validates the id_token, calls /userinfo of the OpenID provider
  • Loginbuddy returns the complete response to web application

Benefits of this deployment

• Loginbuddy is completely transparent to clients of the web application
• Loginbuddy does not need a public TLS certificate but a self-signed one which gets imported by the web application
• the web application does not need to 'talk' OAuth or OpenID Connect
• the web application only needs to connect to Loginbuddy locally and not to external servers
• the web application only needs to delegate an authorization_url to the provider and the code-response from the provider back to Loginbuddy
• No redirect_uri for Loginbuddy is required, only for your web application

Disadvantages of the deployment

• Loginbuddy only serves the web application, multiple clients are not supported
• web application has to display a page where users can choose their favourite supported OpenID Provider
  • alternatively, if web application wants to support one provider only it can be included in requests to Loginbuddy directly

OpenID Connect Dynamic Registration

Loginbuddy may be configured to support OpenID Connect Dynamic Registration. In this scenario users are able to either choose an OpenID Provider of the shown list that was configured, or paste the OpenID Configuration URL of their own provider.

The big advantage is that users are not limited by the provided list, the disadvantage may be that you do not know which provider is used. Nevertheless, this setup is supported using the Standalone but also the Sidecar deployment. In both cases, an additional container needs to be launched.

Figure 03 shows the addition to the described design:

Figure 03: Loginbuddy deployed with support for OpenID Connect Dynamic Registration (OIDCDR) scenarios

Details on Figure 03

• 1:
  • Loginbuddy (or Loginbuddy Sidecar) will delegate all requests to the dynamically registered OpenID Provider
• 2:
  • Loginbuddy OIDCDR communicates with the OpenID provider

Reasons for this separation

• Loginbuddy OIDCDR is running without security manager. Otherwise, a connection to non-registered hosts would not be possible
• This way only Loginbuddy OIDCDR will be compromised in case of a rogue OpenID provider

In order to enable this scenario three steps are required:

• 1:
  • The container (Loginbuddy/ Loginbuddy Sidecar) needs to be started with the environment variable SUPPORT_OIDCDR=true
  • this is the master switch to turn on support globally
• 2:
  • The permissions file of both containers (Loginbuddy/ Loginbuddy Sidecar) need to include an entry for a SockerPermission to loginbuddy-oidcdr
• 3:
  • The client needs to be configured with accept_dynamic_provider=true
  • for Loginbuddy this is done in config.json
  • for Loginbuddy Sidecar the web application needs to include the parameter ...&accept_dynamic_provider=true&...

NOTE: OpenID provider that use a self-signed TLS certificate are currently not supported!

Docker Compose Environment Variables

Loginbuddy (standalone and sidecar) can be configured via environment variables. This is the comprehensive list:

Variable	Default	Usage	Comment
SSL_PWD	generated	The SSL_PWD of the keystore that is used by Loginbuddy	This is generated if the development environment is configured. If not set, Loginbuddy generates a keypair and a SSL_PWD which lives as long as Loginbuddy is running
SSL_PORT	443	The SSL port used by Loginbuddy	discovery.json has to be updated if this port is not 443
SUPPORT_OIDCDR	false	When set to true, Loginbuddy supports OpenID Connect Dynamic Registration requests and registers itself with OpenID Authoritzation servers	This requires the container loginbuddy-oidcdr to be available. In addition, each enabled client configuration needs to set accept_dynamic_provider=true
SSL_TRUSTED_SERVER	none	Takes a comma separated list of server:port values. Loginbuddy connects via SSL and imports the servers SSL certificate as trusted cert	Remember to add the host to the permissions.policy file (see Configuration instructions)! Should be used during development only
HOSTNAME_LOGINBUDDY	local.loginbuddy.net	Loginbuddys hostname	Used when a key pair is generated for SSL connections
HAZELCAST	none	Takes a comma separated list of server:port values. When configured, Loginbuddy connects to those Hazelcast servers and uses them instead of its internal cache/session store	Useful if cache/session data should be handled outside of Loginbuddy. Defaults to the internal session/cache store if the connections fails
STORAGE	local	Takes a storage provider which may be used if Loginbuddy is clustered. Currently only HAZELCAST is supported, i.e.: STORAGE=HAZELCAST[hazelcast1:5701,hazelcast2:5701]	This is required if Loginbuddy runs behind a loadbalancer and if there are more than one Loginbuddy nodes
SECRET_OBFUSCATION	generated	Loginbuddy encrypts access_token and refresh_token if configured. The encrypted message also includes the associated incoming client_id and chosen provider	This is required if Loginbuddy should also handle refresh_token requests

Note: Clustering is displayed in the samples project. It is not fully documented here, yet.