NB: This document is an attempt to acquire feedbacks on some possible commands that could be added to CLI to make Authentication configuration "simple" for main use cases.
CLI authentication commands expectations
- Offer simple commands to enable/disable HTTP and SASL authentication for both Http server and management interfaces.
- Hide complexity of elytron management model as much as possible without introducing unwanted simplification.
- Take benefit of existing Out Of The Box elytron configuration.
- Drive users to select the right set of options thanks to CLI completion that controls visibility of options.
- Help users discover the underlying elytron model thanks to the echo-dmr command to print out the set of sent model operations.
- Allow user to visualise the management or application authentication configuration.
- These commands syntax are aligned with what is proposed for SSL configuration.
NB: Adding users to properties files or file-system based is out of the scope of the following commands. These backends should have been configured (add-user.sh and/or CLI DMR operations).
Limiting the set of identity backends and mechanisms
Seems that SSL certificate, properties file and new fs-realm users are common and simple enough to be the first one addressed, JDBC LDAP, ... would require to interact directly with elytron model.
For SASL, any mechanism can be set. EXTERNAL, DIGEST-MD5. PLAIN, JBOSS-LOCAL-USER, SCRAM-*, DIGEST-SHA-* ones can be configured from the command.
For HTTP, any mechanism can be set. CLIENT-CERT, BASIC, DIGEST and FORM ones can be configured from the command.
Configure SASL Authentication for management interfaces
enable-sasl-management
Associate an elytron SASL factory to the management interface. In case a SASL factory already exists, the factory is extended (or updated) with the selected mechanism. If no mechanism is provided, the out of the box SASL factory is associated to the management interface. This command creates all the non existing resources required to configure authentication. This command can be called multiple times to configure the referenced SASL factory.
security enable-sasl-management ( [--file-system-realm=<a string>]
[--user-role-decoder=<a string>] |
[--user-properties-file=<null>]
[--group-properties-file=<null>]
[--relative-to=<a string>] )
[--mechanism=<a string>]
[--exposed-realm-name=<a string>]
[--external-trust-store=<a string>]
[--management-interface=<a string>]
[--new-auth-factory-name=<a string>]
[--new-realm-name=<a string>]
[--new-security-domain-name=<a string>]
[--no-reload] [--super-user]
The mininal command to associate the out of the box elytron SASL factory to the HTTP interface
security enable-sasl-management
The mininal command to enable EXTERNAL would be:
security enable-sasl-management --mechanism=EXTERNAL --external-trust-store=my-trusted-users-key-store-name
By default, if no --management-interface is provided, we default to http-interface. Command would force the server to reload except if --no-reload is set.
Options
Mechanisms:
--mechanism: The mechanism to enable. CLI completer exposes all supported SASL mechanisms.
Truststore realm:
--external-trust-store=Must be specified when the mechanisms is EXTERNAL, this is the name of the trust-store. Completion propose the existing key-stores.
Filesystem realm (enabled when the mechanism requires this configuration):
--file-system-realm=The filesystem-realm name.
--user-role-decoder=Only if --file-system-realm is in use. The name of the role decoder to extract the roles from the users repository.
--exposed-realm-name=The realm-name exposed to the user.
Properties file realm (enabled when the mechanism requires this configuration):
--users-properties-file=A path to the properties file.
--groups-properties-file=A path to the properties file.
--exposed-realm-name=The realm-name located in users properties file and exposed to the user. must be set for this realm.
--relative-to=Server property to make properties file relative.
Local user properties:
--super-user: In order to configure local user with super-user permissions.
Names for generated resources:
--new-auth-factory-name=To name the factory with the specified name, by default computed based on the mechanism name.
--new-security-domain=To name the security domain with the specified name, by default computed based on the realm name.
--new-realm-name=To name the realm with the specified name, by default computed based on the realm realm name.
Management interface
--management-interface=The management interface to configure, by default is http-interface+http-upgrade
Server directives
--no-reload=By default server is reloaded, use this option to not reload the server.
disable-sasl-management
This command removes the active SASL factory or a mechanism from the active SASL factory. Without any mechanism provided, this command erases the factory from the http-upgrade or native interface. NB: Existing resources are not removed from management model.
security disable-sasl-management [--management-interface=<a string>]
[--mechanism=<a string>] [--no-reload]
reorder-sasl-management
Re-order the SASL mechanisms. The --mechanisms-order option is a comma separated list of mechanisms names. CLI completion proposes the mechanisms present in the targeted factory. By default http-interface is used.
security reorder-sasl-management --mechanisms-order=<a string>
[--management-interface=<a string>]
[--no-reload]
Enabling/Disabling HTTP Authentication for http management interface
enable-http-auth-management
This command targets only the management http-interface. Similar behaviour than enable-sasl-management command.
security enable-http-auth-management ( [--file-system-realm=<a string>]
[--user-role-decoder=<a string>] |
[--user-properties-file=<null>]
[--group-properties-file=<null>]
[--relative-to=<a string>] )
[--mechanism=<a string>]
[--exposed-realm-name=<a string>]
[--external-trust-store=<a string>]
[--new-auth-factory-name=<a string>]
[--new-realm-name=<a string>]
[--new-security-domain-name=<a
string>] [--no-reload]
The mininal command to associate the out of the box elytron HTTP factory to the HTTP interface
security enable-http-auth-management
Options
Same options than --enable-sasl-management. The completer for --mechanism exposes HTTP mechanisms.
disable-http-auth-management
This command removes the active HTTP factory or a mechanism from the active HTTP factory. Without any mechanism provided, this command erases the factory from the interface. NB: Existing resources are not removed from management model.
security disable-http-auth-management [--mechanism=<a string>]
[--no-reload]
Enabling/Disabling HTTP Authentication for undertow security domain
enable-http-auth-http-server
Associate an elytron HTTP factory to the security domain. In case a SASL factory already exists, the factory is extended(or updated) with the selected mechanism. If no mechanism is provided, the Out of The Box Application HTTP factory is associated to the security domain. This command creates all the non existing resources required to configure authentication. This command can be called multiple times to configure the referenced HTTP factory. Similar behaviour than enable-http-auth-management command.
security enable-http-auth-http-server --security-domain=<a string> (
[--file-system-realm=<a string>]
[--user-role-decoder=<a string>] |
[--user-properties-file=<null>]
[--group-properties-file=<null>]
[--relative-to=<a string>] )
[--mechanism=<a string>]
[--exposed-realm-name=<a string>]
[--external-trust-store=<a string>]
[--new-auth-factory-name=<a string>]
[--new-realm-name=<a string>]
[--new-security-domain-name=<a
string>] [--no-reload]
The mininal command to associate the out of the box elytron HTTP factory to the Foo security-domain
security enable-http-auth-http-server --security-domain=Foo
Options
--security-domain=Mandatory, the undertow security domain.
Other options are the same than --enable-sasl-management. The completer for --mechanism exposes HTTP mechanisms.
disable-http-auth-http-server
This command removes the security domain or a mechanism from the active HTTP factory. Without a mechanism, the security domain is removed. NB: Elytron existing resources are not removed from management model.
security disable-http-auth-http-server --security-domain=<a string>
[--mechanism=<a string>]
[--no-reload]
Visualising Security configuration for management and application
In order to quickly visualise what the configuration is, the following commands are provided:
security display-http-server-info [--server-name=<a string>]
security display-management-info
Output example (SSL and SASL applied to http-interface):
[standalone@localhost:9993 /] security display-management-info
http-interface
SSL enabled: true
Server SSLContext: server.keystore.jks
Key Manager: key-manager-server.keystore.jks
Key Store: server.keystore.jks
http authentication enabled: false
sasl authentication enabled: true
Authentication Factory: management-sasl-authentication
Security Domain: ManagementDomain
Mechanisms:
JBOSS-LOCAL-USER realm-mapper=local
DIGEST-MD5 realm-name=ManagementRealm
native-interface
SSL enabled: false
sasl authentication enabled: false
Generated resources
Under the hood, the CLI command adds the required resources for the factory to operate. CLI identifies already existing resources that can be reused, for example if the provided properties files exist inside a properties-realm, this one will be reused. If a SASL factory is already associated to the management interface, it will be reused and updated with mechanisms.
The security-domain default-realm and mechanism realm-mapper are identified with the following strategy:
- Set a realm-mapper for all mechanisms that can be configured, this mapper references a key-store, local realm or user/password realms.
- Set a realm-name for BASIC/DIGEST/DIGEST-MD5.
- The security-domain.default-realm is never updated.
A constant realm-mapper, if not already present is generated for newly generated realm.
Comments