PlugSSO


Author: Jarle Elshaug

Overview

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

Highlights:

  • Protects all web applications located behind Plug-Front
  • Protects all OAuth and OpenID Connect based web applications without regard for location
  • 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 load balancing and synchronization between all nodes
  • Runs anywhere having a reverse proxy as the only external dependency
  • Misc. options for Authentication (AuthN), Authorization (AuthZ), Multi Factor (MFA) and Geolocation
  • Both external (federated) and internal authentication options
  • Multi Factor supporting OTP and U2F (FIDO2/WebAuthn) in both password-less and username-less mode
  • Integrates 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, Kubernetes and Unikernels-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).
  • Multi 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 and roaming support, an external USB or NFC security key is required giving a seamless registration and login just by a “touch” e.g. YubiKey. For none roaming, you could use a device supporting PIN/Fingerprint/Touch-ID/Face-ID e.g. laptop, iPhone or Android. Password-less and username-less mode is supported. With the username-less mode you don’t need to initially provide any information. The authenticator does not ask for username or password. There are no traditional first step authentication needed either. Note, OTP and others are phishable. For the time being, 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 only users coming from allowlisted countries
  • Built-in OAuth and OpenID Connect Provider (optional)
    Cloud and on-premise web applications supporting OAuth or OpenID Connect can be setup to use PlugSSO as provider. Users then get authentication and Single Sign-On by PlugSSO and becomes automatically accepted by destination application.

Configuration, one or more Domains configured with:

  • Authentication (mandatory)
  • Authorization (optional)
  • Multi Factor (optional)
  • Realms (mandatory)
    Each realm defined allows traffic to that path and below e.g.:
    /app1
    /app2
    /app3/rest

Look and feel

Login

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. Multi Factor selection can also be included. Figure below shows a more complex scenario for a domain having several external federation options including internal user/password login and Multi Factor selection.

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 Multi Factor step

Multi Factor - OTP

Figure below shows the final Multi 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

Multi Factor - U2F (FIDO2/WebAuthn)

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

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

Figure below shows how login may look like on Windows 10 having Fingerprint and PIN enabled.

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

Multi Factor - Self Service

Self service for Multi Factor is available through the Can't login? link in the authentication screen. Like figure below shows, we can then click Register button to get a mail sent to our mailbox having a link to register the authenticator app/device.

OAuth and OpenID Connect Provider

OpenID Connect well-known configuration can be found at:

https://elshaug.xyz/plug/oauth/.well-known/openid-configuration

Test PlugSSO online

You may online test PlugSSO at https://elshaug.xyz having path /sso protected. There will be Single Sign-On between all realms in the same domain. For testing purpose, internal login accepts all usernames having password = password. If more than 4 incorrect login attempts, user will be banned for 1 hour. You may also test using misc sub paths under each realm.

U2F prerequisite:
External USB or NFC security key is required, or running on a device having PIN or biometric security enabled like Fingerprint, Touch ID or Face ID

OTP prerequisite:
OTP Authenticator app is required e.g. installed on iPhone or Android (using an app from Microsoft, Google, Authy,…)

 
Logout: /plug/logout
Note, you will also be logged out when going from one domain to another
Domain1
Prelogin: Google, Azure and internal authentication
Authorization: No
Multi Factor: Selection (OTP, U2F/FIDO2, U2F/FIDO2 less)
Comment: Multi Factor can be selected having OTP as default.
         Selecting "U2F/FIDO2 less" will automatically start
         username-less authentication (Prelogin not needed)
         See also comments for Domain2/Domain3.
      
Realms for testing:
/sso/app1
/sso/app2
/docs/plugsso/configuration

Domain2
Prelogin: Google, Azure and internal authentication
Authorization: No
Multi Factor: U2F/FIDO2
Comment: Password is not needed, but username is required. Username
         will be automatically given by the Prelogin authentication. 
         When using Microsoft or Google you may already have
         the auth cookie and will not notice this authentication.
         On first time use, you need to register your
         Authenticator/ID. You may later on register as many as
         you want e.g. when using another device or using
         a different username.
        
Realms for testing:
/sso/app3
/sso/app4

Domain3 
Prelogin: Only for registration - Google, Azure and internal authentication
Authorization: No
Multi Factor: U2F/FIDO2 less 
Comment: Username-less and we do not have to provide any username
         or password. Authenticator/ID needs to be registered on
         first time use having a Prelogin and the traditional
         authentication. You may later on register as many as you
         want e.g. when using another device or want to use
         a different username. When having several usernames
         registered, you have to select one of then from the list
         that pops up during the login process.
  
Realms for testing:
/sso/app5
/sso/app6

Domain4 
Prelogin: No Prelogin, using direct Google authentication
Authorization: No
Multi Factor: No 

Realms for testing:  
/sso/app7
/sso/app8/abc

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.

Microsoft login selection is configured with Azure authentication having AzureAdAndPersonalMicrosoftAccount. This means all users with a work, school, or personal Microsoft account are allowed for authentication.

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 have been defined in Azure for PlugSSO. So, you most likely have to use a personal Microsoft account (@outlook.com, @hotmail.com, @live.com, …). 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