The sections below document the admin console that is available to Gluu Casa administrators after installation. Many of the settings are configured during initial setup. Once Casa and Gluu are properly configured, follow the enable methods section below to "turn on" Casa.
All configuration changes applied via the admin console take effect immediately with no restart or other actions required.
This section contains settings used by Casa to establish a connection to the underlying database. These settings are prepared by the application installer and there is no need to apply any change afterwards. Update these settings only if the application needs to be tested against a different database Server.
Casa leverages oxd to faciliate user authentication against its corresponding Gluu Server. oxd installation and configuration is prompted during Casa installation. To change or update details about the oxd server, or to configure and use an existing oxd deployment, navigate to the
oxd page in the admin console.
Ensure your Gluu Server has "dynamic registration" of clients enabled and that "returnClientSecretOnRead" is set to true while you are applying changes here.
In case of lockout, visit the FAQ document.
The following settings can be adjusted or viewed via the Casa admin console:
oxd server location: host and port of oxd.
Scopes: The scopes to be requested from the authorization server when authentication takes place. Adding scopes to the set of pre-defined scopes allows plugin developers to have access to specific user attributes.
URI of the OpenID Provider (OP): This is the URL of the corresponding Gluu Server where users are sent for authentication, e.g.
Client Name: The name of the OpenID client that Casa uses to facilitate SSO with the Gluu Server.
Authorization Redirect URI: This is the URL of the Casa dashboard landing page that users are directed to after authentication.
Post logout URI: The URL of the page that users should be directed to after they log out of Casa, e.g.
oxd ID: Upon setting up the Casa client, the oxd ID will be automatically generated. It will look something like
Updates need to be made in both the Gluu Server and Casa to get Casa operational.
Enable Authentication Scripts (Gluu)#
The Gluu Server uses interception scripts to implement user authentication. For each type of 2FA credential that should be manageable in Casa, the corresponding authentication script must be enabled in Gluu.
To enable authentication methods in Gluu, open oxTrust and navigate to
Manage custom scripts. Enable the interception script for each type of 2FA credential that should be manageable in Casa - i.e.
It is recommended not to use U2F but FIDO2 as authentication method.
To confirm script functionality, or if issues arise, check the troubleshooting doc in the FAQ.
Set Default Authentication Method (Gluu)#
With the Casa authentication script enabled in the Gluu Server, OpenID Connect clients can now request Casa authentication (i.e. each user's 2FA preferences) using the standard OpenID Connect
To make this behavior the default for all Gluu logins, navigate to
Manage Authentication >
Default Authentication method and set
Default acr and
oxTrust acr to
casa. Click update to save your changes.
Once the applicable interception scripts are enabled in Gluu, a Casa admin can enable 2FA mechanisms in the
Enable methods interface. Check the box for each type of authentication method users should be able to self-service in Casa. You can assign the handler plugin for each method. Choose "System" to use the default implementation provided by the application.
The System plugin supports several authentication methods:
- OTP SMS
- OTP (handling mobile apps and hard tokens)
- FIDO security keys
- Super Gluu.
Developers can provide their own custom handler plugins that add or override the authentication methods.
In their home page, users will see widgets for every available method. These widgets are listed in decreasing order of ACR level. That is, the first method shown will be that with the highest level assigned in its corresponding interception script, and therefore the most secure.
A recommended practice is to enable one script in the Gluu Server (like U2F), then enable the associated method in Casa. Test and confirm that enrollment and authentication is working as expected, then continue adding other desired 2FA methods. In an incognito browser, employ a user other than
admin to test enrollments each time a new method is added. This will prevent the
admin user from being accidentally locked out.
This feature is only available through the 2FA settings plugin.
In the 2FA settings, an admin can:
- Specify the minimum number of credentials a user must enroll before 2FA can be turned on
- Determine whether 2FA should be automatically enabled upon credential enrollment
- Whether users can turn 2FA on and off their own
- Whether users can choose a preferred authentication method
- Choose from a few predefined policies for when 2FA should be prompted.
To reduce the chance of lockouts, we recommend setting a minimum of two (2) strong credentials.
Predefined 2FA policy options include:
- Enforce strong authentication for every login attempt
- Prompt for 2FA when users' location is unrecognized
- Prompt for 2FA when users' device is unrecognized
- Allow the user to set their own strong authentication policy
The default policy is to enforce 2FA for every login attempt. If the admin opts to allow users to manager their own policy, a new widget will appear in the user-facing dashboard as described in the user guide.
In addition, the plugin exposes an API to programmatically manipulate these settings.
Pass reset config#
If passwords are being stored in the Gluu Server (and not at an external backend directory server like AD), an admin can give users the ability to reset their password from inside Casa. To enable the password reset functionality, navigate to
Pass reset config and click the toggle to
Most organizations will want to custom brand Casa. Follow our guide to learn more about custom branding Casa.
Application logs are useful sources of information to diagnose anomalies and understand possible causes of errors if presented. Casa uses the Log4J2 logging framework for this. The severity level for logs can be modified at runtime and requires no restart. For more information about logging, check the FAQ entry.
Reset to password authentication#
If a user is locked out for any reason (e.g. lost device, etc.), an admin can navigate to
Reset to password authentication in the admin console to turn 2FA off for them. Type the username (or part of) in the text field and then press search. Once the user has been located, click the checkbox and click the
Reset to password button. The row will become disabled, and a success message will be displayed.
Casa exposes some REST services and plugin developers can also add their own. If consumption of services is required from the users' browser, known cross origin problems will arise. To "grant" an external domain access to a Casa service, you can add it to the list of allowed CORS domains.
Plugins are vehicles to augment the functionalities available by default in Gluu Casa. To learn more about plugins, visit the developer guide.
In this section of the console, the current list of active plugins is shown. Once an element in the list is selected, a summary of the relevant plugin's metadata is visualized.
Click on the "Add a plugin..." button to select a file in your local hard drive that you wish to onboard as a new plugin into your Gluu Casa installation. Account that plugin files must have a specific format and structure as explained here.
Most of the above aspects can be configured programmatically using the configuration API.