Authentication Flow Customization
Authentication Flow Options
UDS Core comes equipped with a robust authentication framework that supports multiple authentication methods to meet diverse security requirements and user preferences. Here’s a breakdown of the authentication options available:
-
Username and Password
The most traditional form of authentication involves users providing a username and password that must match the credentials stored in the system. This method is widely used due to its simplicity and direct control over access credentials.
-
SSO (Single Sign-On)
Single Sign-On (SSO) allows users to authenticate with one set of credentials to access multiple applications. UDS Core can be configured to integrate with various SSO providers, such as Google SSO, Microsoft Entra, and others, streamlining the login process and reducing the burden of managing multiple usernames and passwords.
-
x509 Certificate
x509 certificates provide a way to authenticate using digital certificates. It is commonly used in environments that require higher security, such as corporate or governmental networks. This method uses public key infrastructure (PKI) to verify the user’s identity through a trusted certificate authority.
MFA Authentication
UDS Core comes with two different options for MFA requirements. One time password (OTP) and WebAuthn options can be configured. These options are available for both Username and Password
and x509
authentication flows. They are controlled individually, to provide the most amount of configurability.
- path: realmAuthFlows value: USERNAME_PASSWORD_AUTH_ENABLED: true X509_AUTH_ENABLED: true SOCIAL_AUTH_ENABLED: true OTP_ENABLED: true WEBAUTHN_ENABLED: false X509_MFA_ENABLED: false
Above is the complete list of authentication configurations from a bundle override. Below is the description of what each of those do:
Name | Description | Default Value |
---|---|---|
USERNAME_PASSWORD_AUTH_ENABLED | Controls whether the Username and Password authentication flow is allowed and present on the login page. | true (default), false |
X509_AUTH_ENABLED | Controls whether the X509 authentication is allowed and present (when a proper certificate is present) on the login page. | true (default), false |
SOCIAL_AUTH_ENABLED | Controls whether the Social authentication is allowed and present on the login page. This requires that an Identity Provider be configured as well. | true (default), false |
OTP_ENABLED | Control whether OTP MFA is enabled, making it required for Username and Password authentication. | true (default), false |
WEBAUTHN_ENABLED | Control whether WebAuthn MFA is enabled, making it required for Username and Password authentication. | true , false (default) |
X509_MFA_ENABLED | Control whether X509 authentication flow should also include MFA. Enabling this requires OTP_ENABLED or WEBAUTHN_ENABLED as well. | true , false (default) |
We shift all authn and authz responsibilies to the Identity Provider if choosing to use SSO, this means that MFA is not configurable for SSO options.
Authentication Flows in UDS Core
UDS Core is shipped with a basic authentication flow that includes all three options out of the box. The following diagram shows the basic authentication flows that are deployed with standard UDS Core:
Customizing Authentication Flows
Different operational environments may necessitate distinct authentication flows to comply with specific security policies, regulatory demands, or demographic requirements. UDS Core facilitates the customization of these flows, allowing for tailored security measures and user interfaces. The diagram below illustrates various combinations of the three authentication methods that can be adapted to meet unique operational needs:
These customizations not only ensure appropriate security configurations by enabling or disabling specific flows but also maintain a seamless user experience by adjusting the Keycloak theme accordingly.
The following sections provide a step-by-step guide on how to customize UDS Core to deploy specific authentication flows, catering to the particular needs and guidelines of your environment.
Authentication Flow Customization
If upgrading uds-core, be aware that Keycloak Admin manual configuration will probably be required to set new Realm values. See the manual configuration section below for how to do this.
Bundle Overrides
To simplify the configuration of the available authentication flows, the following three environment variables have been exposed. These variables default to true
in UDS Core, override their values in a bundle to disable.
Setting | Description | Options |
---|---|---|
USERNAME_PASSWORD_AUTH_ENABLED | Toggle on/off the Username and Password Authentication flow. When disabled there will be no username password login, password / password confirm registration fields, no credential reset, and no update password options available. | true (default), false |
X509_AUTH_ENABLED | Toggle on/off X509 (CAC) Authentication flow. | true (default), false |
SOCIAL_AUTH_ENABLED | Toggle on/off Social (Google SSO, Azure AD, etc. ) Authentication flows. | true (default), false |
X509_MFA_ENABLED | Toggle on/off X509 to require additional MFA options (OTP, WebAuthn, etc). | true , false (default) |
These three variables handle the complexities of configuring the following environment variables, which are responsible for both visual (theme) and security (realm). The following variables are not exposed for overriding.
Manual Configuration
Theme Configurations
Theme’s cannot be clickops’ed, for these changes to take affect an upgrade or fresh deployment will be required. Another option is exec-ing into the the keycloak pod and copying in the new themes to the /opt/keycloak/theme/themes/login/
directory. After copying in the theme changes, the theme changes depend on environment variables being defined in the theme.properties file. The above table demonstrates the different environment variables for the theme.properties
file.
Realm Configurations
All Realm Configurations require accesss to the Keycloak admin portal.
Configuration | How to Configure |
---|---|
DENY_USERNAME_PASSWORD_ENABLED | 1. Realm Authentication tab 2. Select the UDS Authentication Authentication Flow3. DISABLE the Deny Access step that is below the Username Password Form |
RESET_CREDENTIAL_FLOW_ENABLED | 1. Realm Authentication tab 2. Select the UDS Reset Credentials Authentication Flow3. DISABLE the Reset Password step |
REGISTRATION_FORM_ENABLED | 1. Realm Authentication tab 2. Select the UDS Registration Authentication Flow3. DISABLE the UDS Registration form step |
OTP_ENABLED | 1. Realm Authentication tab 2. Select the Required Action tab at the top of the Authentication view3. Toggle off the Configure OTP |
WEBAUTHN_ENABLED | 1. Realm Authentication tab 2. Select the Required Action tab at the top of the Authentication view3. Toggle on the Webauthn Register Passwordless Enabled column4. Select the Flows tab at the top of the Authentication view5. Select the UDS Authentication flow6. Set the MFA sub-flow to Required 7. Set the WebAuthn Passwordless Authenticator in the MFA sub-flow to Required |