Author: Jarle Elshaug


PlugSSO gives access control through secure Single Sign-On allowing users to sign on once using one set of credentials, giving them one-click access to all your web applications from anywhere.

You may have heard of products like Ping, Okta, SiteMinder,…?
Well, it’s time for lightweight microservices: PlugSSO


  • Lightweight, modular and massively scalable
  • Incredibly fast, validates requests in less than 200 µs
  • Easy installation and configuration, one binary and a configuration file
  • Always On Failover cluster with loadbalancing and synchronization between all nodes
  • Runs anywhere having a reverse proxy as the only external dependency
  • Misc. options for Authentication (AuthN), Authorization (AuthZ), Two Factor (2FA) and Geolocation
  • Both external (federated) and internal authentication options
  • Two Factor supporting both OTP and U2F (FIDO2/WebAuthn)
  • Intergrates with SCIM Gateway for customized AuthN/AuthZ logic including Just-in-Time Provisioning (JIT)
  • Misc. attack preventions e.g. brute-force and man-in-the-middle
  • Built-in OAuth and OpenID provider (OP)
  • Works with any reverse proxy server (nginx, traefik, ambassador, istio, envoy, etc) that supports forward/external authentication
  • Docker and Kubernetes-friendly
  • Written in Go, a high-performance networking and multiprocessing language with higher memory safety guarantees than other servers

User login flow:

  • Authentication (mandatory)
    External, using OAuth or OpenID Connect e.g. Azure, ADFS, Google, Facebook,…
    Internal, using built-in directory option e.g. Active Directory, or more advanced through SCIM Gateway giving full flexibility in terms of endpoints, protocols and custom logic to be used e.g. cloud implementation using on-premise authentication
    Users can be “allowlisted” based on organization and login name
    Supports all Azure sign-in options: AzureAdMyOrg, AzureAdMultipleOrgs and AzureAdAndPersonalMicrosoftAccount

  • Authorization (optional)
    User lookup and validation (e.g. group memberships) through built-in directory option, or more advanced through SCIM Gateway where needed custom logic can be defined.
    Supports custom headers to be set for having Single Sign-On towards web applications using header validation (e.g. Symantec/Broadcom/CA Identity Suite using SiteMinder headers).

  • Two Factor (optional)
    Supports both OTP (One Time Password) and U2F (Universal 2nd Factor - FIDO2/WebAuthn)
    For OTP your favourite authenticator app on iPhone or Android can be used (e.g. Microsoft, Google, Authy,…) having a first time on-the-fly registration by scanning a QR code.
    For U2F an external USB or NFC security key is required giving a seamless registration and login just by a “touch” e.g. YubiKey, or you could use a device supporting Touch/Face ID e.g. iPhone or Android.
    Note, OTP and others are phishable. For the time beeing, U2F is the only solution that is not phishable. U2F integrates with back-end using a public key, and authentication then “magically” doesn’t work when it is a malicious site. This is the #1 reason for using U2F - FIDO2/WebAuthn.

  • Geolocation (optional)
    Allow users coming from allowlisted countries

  • Built-in OAuth and OpenID Connect Provider (optional)
    If your web application supports OAuth or OpenID Connect, it can be setup to use PlugSSO as provider. Users then get Single Sign-On by PlugSSO and becomes automatically accepted by destination application.

Configuration, one or more Domains configured with:

  • Authentication (mandatory)
  • Authorization (optional)
  • Two Factor (optional)
  • Realms (mandatory)
    Each realm defined allows traffic to that path and below e.g:

Look and feel


Login/authentication will be according to your domain configuration for the realm you are accessing. If prelogin is enabled, a prelogin dialog will be used for selecting were to login. This dialog is built dynamically based on the domain configuration. Most common scenario is having your own company as the only selection. Figure below shows a more complex scenario for a domain having several external federation options including internal user/password login.

Internal login option supports all kind of use cases, endpoints and protocols e.g. having a cloud based PlugSSO installation with on-premise login to for example Active Directory (not using ADFS).

Figure below shows Azure tenant login screen for “My Company”.

Note, cookie life time defined by your external OAuth provider decides how frequent you will see this login dialog box. Most of the times you will be automatic authenticated and will not notice this first step authentication.

If authorization is enabled, there will be some behind the scenes validation of the user before the final Two Factor step

Two Factor Authentication - OTP

Figure below shows the final Two Factor Authentication step when using OTP. User then have to enter a Time-based One Time Password generated by the authenticator app

On the first use, PlugSSO have to be registered in the authenticator app before getting the final authentication. Figure below shows how this registration looks like.

You might use your app and test scanning QR code in figure above to see how it shows up. Display name will be set to the product display name value we have defined in the PlugSSO configuration together with your login mail address.

Figure below shows how random codes generated by the authenticator app looks like

Self Service for OTP

Self service for OTP is available through Can't login? link in the Two Factor login screen. Like figure below shows, we can then click Reset button to get a mail sent to our mailbox having a link to reset the authenticator app.

Two Factor Authentication - U2F (FIDO2/WebAuthn)

Figure below shows the final Two Factor Authentication step when using U2F. User then have to touch the security key to login.

Two figures below shows how login looks like when using a mobile device having a Touch ID account registered.

On the first use, your device have to be registered. Figure below shows how this registration looks like when using a security key.

OAuth and OpenID Connect Provider

OpenID Connect well-known configuration can be found at:

Test PlugSSO online

You may online test PlugSSO at having path /sso protected

Domain1 (prelogin Google, Azure and internal authentication pluss Two Factor = OTP) - realms:

Domain2 (same as Domain1, but Two Factor = U2F) - realms:

Domain3 (direct Google authentication) - realms:

For testing purpose, internal login accepts all usernames having password = password
You may also test using misc sub paths under each realm

If more than 4 incorrect login attempts, user will be banned for 1 hour.

OpenID Connect authentication require a consent on first time use. This means user have to accept exchanging profile attributes like mail address with PlugSSO. Installing and using mobile apps you are probably familiar with this concept.

Domain1/Domain2 is configured with Azure authentication having AzureAdAndPersonalMicrosoftAccount. This means all users with a work, school, or personal Microsoft account can access this domain.

Note, you may not use your work or school account unless your Azure tenant administrator have granted global consent permissions (default turned off) or specific consent to PlugSSO. You then have to use a personal Microsoft account (,, If you get a dialog box like shown in figure below, you have to click Have an admin account? Sign in with that account and then specify your personal account.

Last modified January 3, 2021