#$REALM_NAME=examplePropRealm$ user1=password123 user2=password123
Set Up and Configure Authentication for Applications
Configure Authentication with a Properties File-Based Identity Store
Configure Authentication with a Filesystem-Based Identity Store
Configure Authentication with a Kerberos-Based Identity Store
Configure Authentication with a Form as a Fallback for Kerberos
Configure Applications to Use Elytron or Legacy Security for Authentication
Set up and Configure Authentication for the Management Interfaces
You need to create two properties files: one that maps user to passwords and another that maps users to roles. Usually these files are located in the jboss.server.config.dir directory and follow the naming convention *-users.properties and *-roles.properties, but other locations and names may be used. The *-users.properties file must also contain a reference to the properties-realm, which you will create in the next step: #$REALM_NAME=YOUR_PROPERTIES_REALM_NAME$
Example user to password file: example-users.properties
#$REALM_NAME=examplePropRealm$ user1=password123 user2=password123
Example user to roles file: example-roles.properties
user1=Admin user2=Guest
/subsystem=elytron/properties-realm=examplePropRealm:add(groups-attribute=groups,groups-properties={path=example-roles.properties,relative-to=jboss.server.config.dir},users-properties={path=example-users.properties,relative-to=jboss.server.config.dir,plain-text=true})
The name of the properties-realm is examplePropRealm, which is used in the previous step in the example-users.properties file. Also, if your properties files are located outside of jboss.server.config.dir, then you need to change the path and relative-to values appropriately.
/subsystem=elytron/security-domain=exampleSD:add(realms=[{realm=examplePropRealm,role-decoder=groups-to-roles}],default-realm=examplePropRealm,permission-mapper=default-permission-mapper)
/subsystem=elytron/http-authentication-factory=example-http-auth:add(http-server-mechanism-factory=global,security-domain=exampleSD,mechanism-configurations=[{mechanism-name=BASIC,mechanism-realm-configurations=[{realm-name=exampleApplicationDomain}]}])
This example shows creating an http-authentication-factory using BASIC authentication, but it could be updated to other mechanisms such as FORM.
/subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=example-http-auth)
Your application's web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in WildFly. An example of this is available in the Configure Applications to Use Elytron or Legacy Security for Authentication section.
You need a directory where your users will be stored. In this example, we are using a directory called fs-realm-users located in jboss.server.config.dir.
/subsystem=elytron/filesystem-realm=exampleFsRealm:add(path=fs-realm-users,relative-to=jboss.server.config.dir)
If your directory is located outside of jboss.server.config.dir, then you need to change the path and relative-to values appropriately.
When using the filesystem-realm, you can add users using the management CLI.
/subsystem=elytron/filesystem-realm=exampleFsRealm/identity=user1:add()
/subsystem=elytron/filesystem-realm=exampleFsRealm/identity=user1:set-password( clear={password="password123"})
/subsystem=elytron/filesystem-realm=exampleFsRealm/identity=user1:add-attribute(name=Roles, value=["Admin","Guest"])
/subsystem=elytron/simple-role-decoder=from-roles-attribute:add(attribute=Roles)
This simple-role-decoder decodes a principal's roles from the Roles attribute. You can change this value if your roles are in a different attribute.
/subsystem=elytron/security-domain=exampleFsSD:add(realms=[{realm=exampleFsRealm,role-decoder=from-roles-attribute}],default-realm=exampleFsRealm,permission-mapper=default-permission-mapper)
/subsystem=elytron/http-authentication-factory=example-fs-http-auth:add(http-server-mechanism-factory=global,security-domain=exampleFsSD,mechanism-configurations=[{mechanism-name=BASIC,mechanism-realm-configurations=[{realm-name=exampleApplicationDomain}]}])
This example shows creating an http-authentication-factory using BASIC authentication, but it could be updated to other mechanisms such as FORM.
/subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=example-fs-http-auth)
Your application's web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in WildFly. An example of this is available in the Configure Applications to Use Elytron or Legacy Security for Authentication section.
Your application is now using a filesystem-based identity store for authentication.
To set up authentication using a database for an identity store, you need to determine how your usernames, passwords, and roles are stored in that database. In this example, we are using a single table with the following sample data:
|
username |
password |
roles |
|
user1 |
password123 |
Admin |
|
user2 |
password123 |
Guest |
To connect to a database from WildFly, you must have the appropriate database driver deployed as well as a datasource configured. This example shows deploying the driver for postgres and configuring a datasource in WildFly:
deploy /path/to/postgresql-9.4.1210.jar data-source add --name=examplePostgresDS --jndi-name=java:jboss/examplePostgresDS --driver-name=postgresql-9.4.1210.jar --connection-url=jdbc:postgresql://localhost:5432/postgresdb --user-name=postgresAdmin --password=mysecretpassword
/subsystem=elytron/jdbc-realm=exampleDbRealm:add(principal-query=[{sql="SELECT password,roles FROM wildfly_users WHERE username=?",data-source=examplePostgresDS,clear-password-mapper={password-index=1},attribute-mapping=[{index=2,to=groups}]}])
NOTE: The above example shows how to obtain passwords and roles from a single principal-query. You can also create additional principal-query with attribute-mapping attributes if you require multiple queries to obtain roles or additional authentication or authorization information.
/subsystem=elytron/security-domain=exampleDbSD:add(realms=[{realm=exampleDbRealm,role-decoder=groups-to-roles}],default-realm=exampleDbRealm,permission-mapper=default-permission-mapper)
/subsystem=elytron/http-authentication-factory=example-db-http-auth:add(http-server-mechanism-factory=global,security-domain=exampleDbSD,mechanism-configurations=[{mechanism-name=BASIC,mechanism-realm-configurations=[{realm-name=exampleDbSD}]}])
This example shows creating an http-authentication-factory using BASIC authentication, but it could be updated to other mechanisms such as FORM.
/subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=example-db-http-auth)
Your application's web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in WildFly. An example of this is available in the Configure Applications to Use Elytron or Legacy Security for Authentication section.
To set up authentication using an LDAP server for an identity store, you need to determine how your usernames, passwords, and roles are stored. In this example, we are using the following structure:
dn: dc=wildfly,dc=org dc: wildfly objectClass: top objectClass: domain dn: ou=Users,dc=wildfly,dc=org objectClass: organizationalUnit objectClass: top ou: Users dn: uid=jsmith,ou=Users,dc=wildfly,dc=org objectClass: top objectClass: person objectClass: inetOrgPerson cn: John Smith sn: smith uid: jsmith userPassword: password123 dn: ou=Roles,dc=wildfly,dc=org objectclass: top objectclass: organizationalUnit ou: Roles dn: cn=Admin,ou=Roles,dc=wildfly,dc=org objectClass: top objectClass: groupOfNames cn: Admin member: uid=jsmith,ou=Users,dc=wildfly,dc=org
To connect to the LDAP server from WildFly, you need to configure a dir-context that provides the URL as well as the principal used to connect to the server.
/subsystem=elytron/dir-context=exampleDC:add(url="ldap://127.0.0.1:10389",principal="uid=admin,ou=system",credential-reference={clear-text="secret"})
/subsystem=elytron/ldap-realm=exampleLR:add(dir-context=exampleDC,identity-mapping={search-base-dn="ou=Users,dc=wildfly,dc=org",rdn-identifier="uid",user-password-mapper={from="userPassword"},attribute-mapping=[{filter-base-dn="ou=Roles,dc=wildfly,dc=org",filter="(&(objectClass=groupOfNames)(member={1}))",from="cn",to="Roles"}]})
/subsystem=elytron/simple-role-decoder=from-roles-attribute:add(attribute=Roles)
/subsystem=elytron/security-domain=exampleLdapSD:add(realms=[{realm=exampleLR,role-decoder=from-roles-attribute}],default-realm=exampleLR,permission-mapper=default-permission-mapper)
/subsystem=elytron/http-authentication-factory=example-ldap-http-auth:add(http-server-mechanism-factory=global,security-domain=exampleLdapSD,mechanism-configurations=[{mechanism-name=BASIC,mechanism-realm-configurations=[{realm-name=exampleApplicationDomain}]}])
This example shows creating an http-authentication-factory using BASIC authentication, but it could be updated to other mechanisms such as FORM.
/subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=example-ldap-http-auth)
Your application's web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in WildFly. An example of this is available in the Configure Applications to Use Elytron or Legacy Security for Authentication section.
IMPORTANT: In cases where you configure an LDAP server in the elytron subsystem for authentication and that LDAP server then becomes unreachable, WildFly will return a 500, or internal server error, error code when attempting authentication using that unreachable LDAP server. This behavior differs from the legacy security subsystem, which will return a 401, or unauthorized, error code under the same conditions.
IMPORTANT: Before you can set up certificate-based authentication, you must have two-way SSL configured.
/subsystem=elytron/key-store-realm=ksRealm:add(key-store=twoWayTS)
You must configure this realm with a truststore that contains the client's certificate. The authentication process uses the same certificate presented by the client during the two-way SSL handshake.
You need to create a x500-attribute-principal-decoder to decode the principal you get from your certificate. The below example will decode the principal based on the first CN value.
/subsystem=elytron/x500-attribute-principal-decoder=CNDecoder:add(oid="2.5.4.3",maximum-segments=1)
For example, if the full DN was CN=client,CN=client-certificate,DC=example,DC=jboss,DC=org, CNDecoder would decode the principal as client. This decoded principal is used as the alias value to lookup a certificate in the truststore configured in ksRealm.
IMPORTANT: The decoded principal *MUST* must be the alias value you set in your server's truststore for the client's certificate.
This is example uses a constant-role-mapper to assign roles to a principal from ksRealm but other approaches may also be used.
/subsystem=elytron/constant-role-mapper=constantClientCertRole:add(roles=[Admin,Guest])
/subsystem=elytron/security-domain=exampleCertSD:add(realms=[{realm=ksRealm}],default-realm=ksRealm,permission-mapper=default-permission-mapper,principal-decoder=CNDecoder,role-mapper=constantClientCertRole)
/subsystem=elytron/http-authentication-factory=exampleCertHttpAuth:add(http-server-mechanism-factory=global,security-domain=exampleCertSD,mechanism-configurations=[{mechanism-name=CLIENT_CERT,mechanism-realm-configurations=[{realm-name=exampleApplicationDomain}]}])
/subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=exampleCertHttpAuth)
/subsystem=elytron/server-ssl-context=twoWaySSC:write-attribute(name=security-domain,value=exampleCertSD) /subsystem=elytron/server-ssl-context=twoWaySSC:write-attribute(name=authentication-optional, value=true)
Your application's web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in WildFly. An example of this is available in the Configure Applications to Use Elytron or Legacy Security for Authentication section.
In addition, you need to update your web.xml to use CLIENT-CERT as its authentication method.
<login-config> <auth-method>CLIENT-CERT</auth-method> <realm-name>exampleApplicationDomain</realm-name> </login-config>
IMPORTANT: The following steps assume you have a working KDC and Kerberos domain as well as your client browsers configured.
/subsystem=elytron/kerberos-security-factory=krbSF:add(principal="HTTP/host@REALM",path="/path/to/http.keytab",mechanism-oids=[1.2.840.113554.1.2.2,1.3.6.1.5.5.2])
Depending on how your environment is configured, you will need to set some of the system properties below.
|
System Property |
Description |
|
java.security.krb5.kdc |
The host name of the KDC. |
|
java.security.krb5.realm |
The name of the realm. |
|
java.security.krb5.conf |
The path to the configuration krb5.conf file. |
|
sun.security.krb5.debug |
If true, debugging mode will be enabled. |
To configure a system property in WildFly:
/system-property=java.security.krb5.conf:add(value="/path/to/krb5.conf")
The the client's Kerberos token will provide the principal, but you need a way to map that principal to a role for your application. There are several ways to accomplish this, but this example creates a filesystem-realm, adds a user to the realm that matches the principal from the Kerberos token, and assigns roles to that user.
/subsystem=elytron/filesystem-realm=exampleFsRealm:add(path=fs-realm-users,relative-to=jboss.server.config.dir) /subsystem=elytron/filesystem-realm=exampleFsRealm/identity=user1@REALM:add() /subsystem=elytron/filesystem-realm=exampleFsRealm/identity=user1@REALM:add-attribute(name=Roles, value=["Admin","Guest"])
/subsystem=elytron/simple-role-decoder=from-roles-attribute:add(attribute=Roles)
This simple-role-decoder decodes a principal's roles from the Roles attribute. You can change this value if your roles are in a different attribute.
/subsystem=elytron/security-domain=exampleFsSD:add(realms=[{realm=exampleFsRealm,role-decoder=from-roles-attribute}],default-realm=exampleFsRealm,permission-mapper=default-permission-mapper)
/subsystem=elytron/http-authentication-factory=example-krb-http-auth:add(http-server-mechanism-factory=global,security-domain=exampleFsSD,mechanism-configurations=[{mechanism-name=SPNEGO,mechanism-realm-configurations=[{realm-name=exampleFsSD}],credential-security-factory=krbSF}])
/subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=example-krb-http-auth)
Your application's web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in WildFly. An example of this is available in the Configure Applications to Use Elytron or Legacy Security for Authentication section.
In addition, you need to update your web.xml to use SPNEGO as its authentication method.
<login-config> <auth-method>SPNEGO</auth-method> <realm-name>exampleApplicationDomain</realm-name> </login-config>
Configuring kerberos-based authentication is covered in a previous section.
You can use the existing http-authentication-factory you configured for kerberos-based authentication and and an additional mechanism for FORM authentication.
/subsystem=elytron/http-authentication-factory=example-krb-http-auth:list-add(name=mechanism-configurations, value={mechanism-name=FORM})
The existing configuration for kerberos-based authentication should already have a security realm configured for mapping principals from kerberos token to roles for the application. You can add additional users for fallback authentication to that realm. For example if you used a filesystem-realm, you can simply create a new user with the appropriate roles:
/subsystem=elytron/filesystem-realm=exampleFsRealm/identity=fallbackUser1:add()
/subsystem=elytron/filesystem-realm=exampleFsRealm/identity=fallbackUser1:set-password(clear={password="password123"})
/subsystem=elytron/filesystem-realm=exampleFsRealm/identity=fallbackUser1:add-attribute(name=Roles, value=["Admin","Guest"])
You need to update the web.xml to use the value SPNEGO,FORM for the auth-method, which will use FORM as a fallback authentication method if SPNEGO fails. You also need to specify the location of your login and error pages.
<login-config>
<auth-method>SPNEGO,FORM</auth-method>
<realm-name>exampleApplicationDomain</realm-name>
<form-login-config>
<form-login-page>/login.jsp</form-login-page>
<form-error-page>/error.jsp</form-error-page>
</form-login-config>
</login-config>
After you have configured the elytron or legacy security subsystems for authentication, you need to configure your application to use it.
Your application's web.xml needs to be configured to use the appropriate authentication method. When using elytron, this is defined in the http-authentication-factory you created. When using the legacy security subsystem, this depends on your login module and the type of authentication you want to configure.
Example web.xml with BASIC Authentication
<web-app>
<security-constraint>
<web-resource-collection>
<web-resource-name>secure</web-resource-name>
<url-pattern>/secure/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>Admin</role-name>
</auth-constraint>
</security-constraint>
<security-role>
<description>The role that is required to log in to /secure/*</description>
<role-name>Admin</role-name>
</security-role>
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>exampleApplicationDomain</realm-name>
</login-config>
</web-app>
You can configure your application's jboss-web.xml to specify the security domain you want to use for authentication. When using the elytron subsystem, this is defined when you created the application-security-domain. When using the legacy security subsystem, this is the name of the legacy security domain.
Example jboss-web.xml
<jboss-web> <security-domain>exampleApplicationDomain</security-domain> </jboss-web>
Using jboss-web.xml allows you to configure the security domain for a single application only. Alternatively, you can specify a default security domain for all applications using the undertow subsystem. This allows you to omit using jboss-web.xml to configure a security domain for an individual application.
/subsystem=undertow:write-attribute(name=default-security-domain, value="exampleApplicationDomain")
IMPORTANT: Setting default-security-domain in the undertow subsystem will apply to ALL applications. If default-security-domain is set and an application specifies a security domain in a jboss-web.xml file, the configuration in jboss-web.xml will override the default-security-domain in the undertow subsystem.
You can define authentication in both the elytron and legacy security subsystems and use them in parallel. If you use both jboss-web.xml and default-security-domain in the undertow subsystem, WildFly will first try to match the configured security domain in the elytron subsystem. If a match is not found, then WildFly will attempt to match the security domain with one configured in the legacy security subsystem. If the elytron and legacy security subsystem each have a security domain with the same name, the elytron security domain is used.
You can override the authentication configuration of an application with one configured in WildFly. To do this, use the override-deployment-configuration property in the application-security-domain section of the undertow subsystem:
/subsystem=undertow/application-security-domain=exampleApplicationDomain:write-attribute(name=override-deployment-config,value=true)
For example, an application is configured to use FORM authentication with the exampleApplicationDomain in its jboss-web.xml.
Example jboss-web.xml
<login-config> <auth-method>FORM</auth-method> <realm-name>exampleApplicationDomain</realm-name> </login-config>
By enabling override-deployment-configuration, you can create a new http-authentication-factory that specifies a different authentication mechanism such as BASIC.
Example http-authentication-factory
/subsystem=elytron/http-authentication-factory=exampleHttpAuth:read-resource()
{
"outcome" => "success",
"result" => {
"http-server-mechanism-factory" => "global",
"mechanism-configurations" => [{
"mechanism-name" => "BASIC",
"mechanism-realm-configurations" => [{"realm-name" => "exampleApplicationDomain"}]
}],
"security-domain" => "exampleSD"
}
}
This will override the authentication mechanism defined in the application's jboss-web.xml and attempt to authenticate a user using BASIC instead of FORM.
/subsystem=elytron/credential-store=exampleCS:add(relative-to=jboss.server.data.dir, location=cs.jceks,create=true,credential-reference={clear-text=cs-secret})
/subsystem=elytron/credential-store=exampleCS/alias=keystorepw:add(secret-value="secret")
/subsystem=elytron/credential-store=exampleCS:read-children-names(child-type=alias)
{
"outcome" => "success",
"result" => ["keystorepw"]
}
/subsystem=elytron/credential-store=exampleCS/alias=keystorepw:remove
/subsystem=elytron/key-store=twoWayKS:write-attribute(name=credential-reference,value={store=exampleCS,alias=keystorepw})
This process is covered in a previous section. For example, if you wanted to secure the management interfaces using a filesystem-based identity store, you would follow the steps in Configure Authentication with a Filesystem-Based Identity Store.
Example http-authentication-factory
/subsystem=elytron/http-authentication-factory=example-http-auth:add(http-server-mechanism-factory=global,security-domain=exampleSD,mechanism-configurations=[{mechanism-name=DIGEST,mechanism-realm-configurations=[{realm-name=exampleManagementRealm}]}])
Example sasl-authentication-factory
/subsystem=elytron/sasl-authentication-factory=example-sasl-auth:add(sasl-server-factory=configured,security-domain=exampleSD,mechanism-configurations=[{mechanism-name=DIGEST-MD5,mechanism-realm-configurations=[{realm-name=exampleManagementRealm}]}])
Example update http-authentication-factory
/core-service=management/management-interface=http-interface:write-attribute(name=http-authentication-factory, value=example-http-auth)
{
"outcome" => "success",
"response-headers" => {
"operation-requires-reload" => true,
"process-state" => "reload-required"
}
}
reload
Example update sasl-authentication-factory
/core-service=management/management-interface=http-interface:write-attribute(name=http-upgrade.sasl-authentication-factory, value=example-sasl-auth)
{
"outcome" => "success",
"response-headers" => {
"operation-requires-reload" => true,
"process-state" => "reload-required"
}
}
reload
By default, WildFly provides an authentication mechanism for local users, also know as silent authentication, through the local security realm.
Silent authentication must be used via a sasl-authentication-factory.
IMPORTANT: When enabling silent authentication, you must ensure the security domain referenced by your sasl-authentication-factory references a security realm that contains the $local user. By default, WildFly provides the local identity realm that provides this user.
/subsystem=elytron/sasl-authentication-factory=example-sasl-auth:list-add(name=mechanism-configurations, value={mechanism-name=JBOSS-LOCAL-USER, realm-mapper=local})
reload
/subsystem=elytron/sasl-authentication-factory=example-sasl-auth:add(sasl-server-factory=configured,security-domain=exampleSD,mechanism-configurations=[{mechanism-name=DIGEST-MD5,mechanism-realm-configurations=[{realm-name=exampleManagementRealm}]},{mechanism-name=JBOSS-LOCAL-USER, realm-mapper=local}])
reload
/subsystem=elytron/sasl-authentication-factory=managenet-sasl-authentication:read-resource
{
"outcome" => "success",
"result" => {
"mechanism-configurations" => [
{
"mechanism-name" => "JBOSS-LOCAL-USER",
"realm-mapper" => "local"
},
{
"mechanism-name" => "DIGEST-MD5",
"mechanism-realm-configurations" => [{"realm-name" => "ManagementRealm"}]
}
],
"sasl-server-factory" => "configured",
"security-domain" => "ManagementDomain"
}
}
/subsystem=elytron/sasl-authentication-factory=temp-sasl-authentication:list-remove(name=mechanism-configurations,index=0)
reload
RBAC can be configured to automatically assign or exclude roles for users that are members of groups. This is configured in the access-control section of the core management. When the management interfaces are secured with the elytron subsystem, and users are assigned groups when they authenticate. You can also configure roles to be assigned to authenticated users in a variety of ways using the elytron subsystem, for example using a role mapper or a role decoder.
In WildFly, you can use the Elytron subsystem, along with the Undertow subsystem, to enable HTTPS for deployed applications.
Before enabling HTTPS in WildFly, you must obtain or generate the keystore you plan on using. To generate an example keystore:
$ keytool -genkeypair -alias localhost -keyalg RSA -keysize 1024 -validity 365 -keystore /path/to/keystore.jks -dname "CN=localhost" -keypass secret -storepass secret
/subsystem=elytron/key-store=httpsKS:add(path=/path/to/keystore.jks,credential-reference={clear-text=secret},type=JKS)
The previous command uses an absolute path to the keystore. Alternatively you can use the relative-to attribute to specify the base directory variable and path specify a relative path.
/subsystem=elytron/key-store=httpsKS:add(path=keystore.jks,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret},type=JKS)
/subsystem=elytron/key-manager=httpsKM:add(key-store=httpsKS,credential-reference={clear-text=secret})
/subsystem=elytron/server-ssl-context=httpsSSC:add(key-manager=httpsKM,protocols=["TLSv1.2"])
IMPORTANT: You need to determine what SSL/TLS protocols you want to support. The example commands above uses TLSv1.2.
/subsystem=undertow/server=default-server/https-listener=https:read-attribute(name=security-realm)
{
"outcome" => "success",
"result" => "ApplicationRealm"
}
The above command shows that the https-listener is configured to use the ApplicationRealm legacy security realm for its SSL configuration. Undertow cannot reference both a legacy security realm and an ssl-context in Elytron at the same time so you must remove the reference to the legacy security realm. Also there has to be always configured either ssl-context or security-realm. Thus when changing between those, you have to use batch operation:
Remove the reference to the legacy security realm and update the https-listener to use the ssl-context from Elytron :
batch /subsystem=undertow/server=default-server/https-listener=https:undefine-attribute(name=security-realm) /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context,value=httpsSSC) run-batch
In WildFly, you can use the Elytron subsystem, along with the Undertow subsystem, to enable two-way SSL/TLS for deployed applications.
Before enabling HTTPS in WildFly, you must obtain or generate the keystores, truststores and certificates you plan on using.
Create server and client keystores:
$ keytool -genkeypair -alias localhost -keyalg RSA -keysize 1024 -validity 365 -keystore server.keystore.jks -dname "CN=localhost" -keypass secret -storepass secret $ keytool -genkeypair -alias client -keyalg RSA -keysize 1024 -validity 365 -keystore client.keystore.jks -dname "CN=client" -keypass secret -storepass secret
Export the server and client certificates:
$ keytool -exportcert -keystore server.keystore.jks -alias localhost -keypass secret -storepass secret -file server.cer $ keytool -exportcert -keystore client.keystore.jks -alias client -keypass secret -storepass secret -file client.cer
Import the sever and client certificates into the opposing truststores:
$ keytool -importcert -keystore server.truststore.jks -storepass secret -alias client -trustcacerts -file client.cer $ keytool -importcert -keystore client.truststore.jks -storepass secret -alias localhost -trustcacerts -file server.cer
/subsystem=elytron/key-store=twoWayKS:add(path=/path/to/server.keystore.jks,credential-reference={clear-text=secret},type=JKS)
/subsystem=elytron/key-store=twoWayTS:add(path=/path/to/server.truststore.jks,credential-reference={clear-text=secret},type=JKS)
NOTE
The previous command uses an absolute path to the keystore. Alternatively you can use the relative-to attribute to specify the base directory variable and path specify a relative path.
/subsystem=elytron/key-store=myKS:add(path=keystore.jks,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret},type=JKS)
/subsystem=elytron/key-manager=twoWayKM:add(key-store=twoWayKS,credential-reference={clear-text=secret})
/subsystem=elytron/trust-manager=twoWayTM:add(key-store=twoWayTS)
/subsystem=elytron/server-ssl-context=twoWaySSC:add(key-manager=twoWayKM,protocols=["TLSv1.2"],trust-manager=twoWayTM,need-client-auth=true)
IMPORTANT
You need to determine what SSL/TLS protocols you want to support. The example commands above uses TLSv1.2.
/subsystem=undertow/server=default-server/https-listener=https:read-attribute(name=security-realm)
{
"outcome" => "success",
"result" => "ApplicationRealm"
}
The above command shows that the https-listener is configured to use the ApplicationRealm legacy security realm for its SSL configuration. Undertow cannot reference both a legacy security realm and an ssl-context in Elytron at the same time so you must remove the reference to the legacy security realm. Also there has to be always configured either ssl-context or security-realm. Thus when changing between those, you have to use batch operation:
batch /subsystem=undertow/server=default-server/https-listener=https:undefine-attribute(name=security-realm) /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context,value=twoWaySSC) run-batch
reload
You need to configure your client to present the trusted client certificate to the server to complete the two-way SSL/TLS authentication. For example, if using a browser, you need to import the trusted certificate into the browser’s truststore.
Two-Way HTTPS is now enabled for applications.
Before enabling HTTPS in WildFly, you must obtain or generate the key store you plan on using. To generate an example key store, use the following command.
$ keytool -genkeypair -alias localhost -keyalg RSA -keysize 1024 -validity 365 -keystore keystore.jks -dname "CN=localhost" -keypass secret -storepass secret
/subsystem=elytron/key-store=httpsKS:add(path=keystore.jks,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret},type=JKS)
/subsystem=elytron/key-manager=httpsKM:add(key-store=httpsKS,credential-reference={clear-text=secret})
/subsystem=elytron/server-ssl-context=httpsSSC:add(key-manager=httpsKM,protocols=["TLSv1.2"])
IMPORTANT: You need to determine what SSL/TLS protocols you want to support. The example commands above uses TLSv1.2.
NOTE: The above command uses relative-to to reference the location of the keystore file. Alternatively, you can specify the full path to the keystore in path and omit relative-to.
/core-service=management/management-interface=http-interface:write-attribute(name=ssl-context, value=httpsSSC) /core-service=management/management-interface=http-interface:write-attribute(name=secure-socket-binding, value=management-https)
Before enabling HTTPS in WildFly, you must obtain or generate the key stores, trust stores and certificates you plan on using. To generate an example set of key stores, trust stores, and certificates use the following commands.
Generate your server and client key stores.
$ keytool -genkeypair -alias localhost -keyalg RSA -keysize 1024 -validity 365 -keystore server.keystore.jks -dname "CN=localhost" -keypass secret -storepass secret $ keytool -genkeypair -alias client -keyalg RSA -keysize 1024 -validity 365 -keystore client.keystore.jks -dname "CN=client" -keypass secret -storepass secret
Export your server and client certificates.
$ keytool -exportcert -keystore server.keystore.jks -alias localhost -keypass secret -storepass secret -file server.cer $ keytool -exportcert -keystore client.keystore.jks -alias client -keypass secret -storepass secret -file client.cer
Import the sever and client certificates into the opposing trust stores.
$ keytool -importcert -keystore server.truststore.jks -storepass secret -alias client -trustcacerts -file client.cer $ keytool -importcert -keystore client.truststore.jks -storepass secret -alias localhost -trustcacerts -file server.cer
/subsystem=elytron/key-store=twoWayKS:add(path=server.keystore.jks,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret},type=JKS)
/subsystem=elytron/key-store=twoWayTS:add(path=server.truststore.jks,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret},type=JKS)
/subsystem=elytron/key-manager=twoWayKM:add(key-store=twoWayKS,credential-reference={clear-text=secret})
/subsystem=elytron/trust-manager=twoWayTM:add(key-store=twoWayTS)
/subsystem=elytron/server-ssl-context=twoWaySSC:add(key-manager=twoWayKM,protocols=["TLSv1.2"],trust-manager=twoWayTM,want-client-auth=true,need-client-auth=true)
IMPORTANT: You need to determine what SSL/TLS protocols you want to support. The example commands above uses TLSv1.2.
NOTE: The above command uses relative-to to reference the location of the keystore file. Alternatively, you can specify the full path to the keystore in path and omit relative-to.
/core-service=management/management-interface=http-interface:write-attribute(name=ssl-context, value=twoWaySSC) /core-service=management/management-interface=http-interface:write-attribute(name=secure-socket-binding, value=management-https)
reload
You need to configure your client to present the trusted client certificate to the server to complete the two-way SSL/TLS authentication. For example, if using a browser, you need to import the trusted certificate into the browser’s trust store.
Two-way SSL/TLS is now enabled for the management interfaces.
An ldap-key-store allows you to use a keystore stored in an LDAP server. You can use an ldap-key-store in same way you can use a key-store.
To create and use an ldap-key-store:
To connect to the LDAP server from WildFly, you need to configure a dir-context that provides the URL as well as the principal used to connect to the server.
Example dir-context
/subsystem=elytron/dir-context=exampleDC:add( \
url="ldap://127.0.0.1:10389", \
principal="uid=admin,ou=system", \
credential-reference={clear-text=secret} \
)
When configure an ldap-key-store, you need to specify both the dir-context used to connect to the LDAP server as well as how to locate the keystore stored in the LDAP server. At a minimum, this requires you specify a search-path.
Example ldap-key-store
/subsystem=elytron/ldap-key-store=ldapKS:add( \ dir-context=exampleDC, \ search-path="ou=Keystores,dc=wildfly,dc=org" \ )
Once you have defined your ldap-key-store, you can use it in the same places where a key-store could be used. For example, you could use an ldap-key-store when configuring HTTPS and Two-Way HTTPS for applications.
A filtering-key-store allows you to expose a subset of aliases from an existing key-store, and use it in the same places you could use a key-store. For example, if a keystore contained alias1, alias2, and alias3, but you only wanted to expose alias1 and alias3, a filtering-key-store provides you several ways to do that.
To create a filtering-key-store:
/subsystem=elytron/key-store=myKS:add( \
path=keystore.jks, \
relative-to=jboss.server.config.dir, \
credential-reference={ \
clear-text=secret \
}, \
type=JKS \
)
When you configure a filtering-key-store, you specify which key-store you want to filter and the alias-filter for filtering aliases from the key-store. The filter can be specified in one of the following formats:
alias1,alias3, which is a comma-delimited list of aliases to expose.
ALL:-alias2, which exposes all aliases in the keystore except the ones listed.
NONE:+alias1:+alias3, which exposes no aliases in the keystore except the ones listed.
This example uses a comma-delimted list to expose alias1 and alias3.
/subsystem=elytron/filtering-key-store=filterKS:add( \ key-store=myKS, \ alias-filter="alias1,alias3" \ )
Once you have defined your filtering-key-store, you can use it in the same places where a key-store could be used. For example, you could use a filtering-key-store when configuring HTTPS and Two-Way HTTPS for applications.
You can reload a keystore configured in WildFly from the management CLI. This is useful in cases where you have made changes to certificates referenced by a keystore.
To reload a keystore.
/subsystem=elytron/key-store=httpsKS:load
If you add a keystore to the elytron subsystem using the key-store component, you can check the keystore's contents using the alias child element and reading its attributes.
For example:
/subsystem=elytron/key-store=httpsKS/alias=localhost:read-attribute(name=certificate-chain)
{
"outcome" => "success",
"result" => [{
"type" => "X.509",
"algorithm" => "RSA",
"format" => "X.509",
"public-key" => "30:81:9f:30:0d:06:09:2a:8......
The following attributes can be read:
|
Attribute |
Description |
|
certificate |
The certificate associated with the alias. If the alias has a certificate chain this will always be undefined. |
|
certificate-chain |
The certificate chain associated with the alias. |
|
creation-date |
The creation date of the entry represented by this alias. |
|
entry-type |
The type of the entry for this alias. Available types: PasswordEntry, PrivateKeyEntry, SecretKeyEntry, TrustedCertificateEntry, and Other. Unrecognized types will be reported as Other. |
When configuring SSL/TLS in the elytron subsystem, you can provide and use custom implementations of the following components:
key-store
key-manager
trust-manager
client-ssl-context
server-ssl-context
When creating custom implementations of Elytron components, they must present the appropriate capabilities and requirements.
/extension=org.wildfly.extension.elytron:add()
/subsystem=elytron:add reload
/subsystem=elytron:remove reload
IMPORTANT: Other subsystems within WildFly may have dependencies on the elytron subsystem. If these dependencies are not resolved before disabling it, you will see errors when starting WildFly.
/subsystem=security:remove reload
IMPORTANT: Other subsystems within WildFly may have dependencies on the security subsystem. If these dependencies are not resolved before disabling it, you will see errors when starting WildFly.
/subsystem=security:add reload
By default the elytron and security subsystems will run in parallel if both are enabled. For authentication in applications, you can use the application-security-domain property in the undertow subsystem to configure a security domain in the elytron subsystem.
/subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=example-http-auth)
NOTE: This must match the security-domain configured in the jboss-web.xml of your application.
If the application-security-domain is not set, WildFly will look for a security domain configured in the security subsystem that matches the security-domain configured in the jboss-web.xml of your application.
For enabling HTTPS using a legacy security realm, you can use the security-realm attribute in the https-listener section of the undertow subsystem:
/subsystem=undertow/server=default-server/https-listener=https:read-attribute(name=security-realm)
{
"outcome" => "success",
"result" => "ApplicationRealm"
}
For enabling HTTPS using elytron, you need to undefine the security-realm attribute and set the ssl-context attribute. As there has to be always configured either ssl-context or security-realm you have to use batch operation when changing between those:
batch /subsystem=undertow/server=default-server/https-listener=https:undefine-attribute(name=security-realm) /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context,value=httpsSSC) run-batch
Security realms in the Elytron subsystem, when used in conjunction with security domains, are use for both core management authentication as well as for authentication with applications. Security realms are also specifically typed based on their identity store, for example jdbc-realm, filesystem-realm, properties-realm, etc.
Adding a security realm takes the general form:
/subsystem=elytron/type-of-realm=realmName:add(....)
Examples of adding specific realms, such as jdbc-realm, filesystem-realm, and properties-realm can be found in previous sections.
A role decoder converts attributes from the identity provided by the security realm into roles. Role decoders are also specifically typed based on their functionality, for example empty-role-decoder, simple-role-decoder, and custom-role-decoder.
Adding a role decoder takes the general form:
/subsystem=elytron/ROLE-DECODER-TYPE=roleDeoderName:add(....)
In addition to roles being assigned to a identity, permissions may also be assigned. A permission mapper assigns permissions to an identity. Permission mappers are also specifically typed based on their functionality, for example logical-permission-mapper, simple-permission-mapper, and custom-permission-mapper.
Adding a permission mapper takes the general form:
/subsystem=elytron/simple-permission-mapper=PermissionMapperName:add(...)
A role mapper maps roles after they have been decoded to other roles. Examples include normalizing role names or adding and removing specific roles from principals after they have been decoded. Role mappers are also specifically typed based on their functionality, for example add-prefix-role-mapper, add-suffix-role-mapper, and constant-role-mapper.
Adding a role mapper takes the general form:
/subsystem=elytron/ROLEM-MAPPER-TYPE=roleMapperName:add(...)
Security domains in the Elytron subsystem, when used in conjunction with security realms, are use for both core management authentication as well as for authentication with applications.
Adding a security domain takes the general form:
/subsystem=elytron/security-domain=domainName:add(realms=[{realm=realmName,role-decoder=roleDecoderName}],default-realm=realmName,permission-mapper=permissionMapperName,role-mapper=roleMapperName,...)
An authentication factory is an authentication policy used for specific authentication mechanisms. Authenticaion factories are specifically based on the authentication mechanism, for example http-authentication-factory and
sasl-authentication-factory and kerberos-security-factory.
Adding an authentication factory takes the general form:
/subsystem=elytron/AUTH-FACTORY-TYPE=authFactoryName:add(....)
Elytron subsystem provides a specific resource definition that can be used to configure a default Java Policy provider. The subsystem allows you to define multiple policy providers but select a single one as the default:
/subsystem=elytron/policy=policy-provider-a:add(custom-policy=\[{name=policy-provider-a, class-name=MyPolicyProviderA, module=x.y.z}\])