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

TIP: I manage the web site oauth.blog. If you select the Login or Sign-Up menu you get to see a list of supported OpenID providers. That page is created by oauth.blog. But, as soon as you select an OpenID provider Loginbuddy takes over behind the scenes. The final result with user details is based on the response returned to oauth.blog by Loginbuddy. The 'sidecar' deployment is used

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!