[[Security_Realms_Examples]]
= Examples
:icons: font

This section of the document contains a couple of examples for the most
common scenarios likely to be used with the security realms, please feel
free to raise Jira issues requesting additional scenarios or if you have
configured something not covered here please feel free to add your own
examples - this document is editable after all icon:smile-o[role="yellow"]

At the moment these examples are making use of the ' `ManagementRealm`'
however the same can apply to the ' `ApplicationRealm`' or any custom
realm you create for yourselves.

[[ldap-authentication]]
== LDAP Authentication

The following example demonstrates an example configuration making use
of Active Directory to verify the users username and password.

[source,xml,options="nowrap"]
----
<management>
  <security-realms>
    <security-realm name="ManagementRealm">
      <authentication>
        <ldap connection="EC2" base-dn="CN=Users,DC=darranl,DC=jboss,DC=org">
          <username-filter attribute="sAMAccountName" />
        </ldap>
      </authentication>
    </security-realm>
 
  </security-realms>
 
  <outbound-connections>
    <ldap name="EC2" url="ldap://127.0.0.1:9797" search-dn="CN=wf8,CN=Users,DC=darranl,DC=jboss,DC=org" search-credential="password"/>
  </outbound-connections>
 
  ...
 
</management>
----

[NOTE]

For simplicity the `<local/>` configuration has been removed from this
example, however there it is fine to leave that in place for local
authentication to remain possible.

[[enable-ssl]]
== Enable SSL

The first step is the creation of the key, by default this is going to
be used for both the native management interface and the http management
interface - to create the key we can use the `keyTool`, the following
example will create a key valid for one year.

Open a terminal window in the folder \{
`jboss.home}/standalone/configuration` and enter the following command:
-

`keytool -genkey -alias server -keyalg RSA -keystore server.keystore -validity 365`

[source,options="nowrap"]
----
Enter keystore password:
Re-enter new password:
----

In this example I choose ' `keystore_password`'.

....
What is your first and last name?
  [Unknown]:  localhost
....

[NOTE]

Of all of the questions asked this is the most important and should
match the host name that will be entered into the web browser to connect
to the admin console.

Answer the remaining questions as you see fit and at the end for the
purpose of this example I set the key password to ' `key_password`'.

The following example shows how this newly created keystore will be
referenced to enable SSL.

[source,xml,options="nowrap"]
----
<security-realm name="ManagementRealm">
  <server-identities>
    <ssl>
      <keystore path="server.keystore" relative-to="jboss.server.config.dir" keystore-password="keystore_password" alias="server" key-password="key_password" />
    </ssl>
  </server-identities>
  <authentication>
    ...
  </authentication>
</security-realm>
----

The contents of the `<authentication />` have not been changed in this
example so authentication still occurs using either the local mechanism
or username/password authentication using Digest.

[[add-client-cert-to-ssl]]
== Add Client-Cert to SSL

To enable Client-Cert style authentication we just now need to add a
`<truststore />` element to the `<authentication />` element referencing
a trust store that has had the certificates or trusted clients imported.

[source,xml,options="nowrap"]
----
<security-realm name="ManagementRealm">
  <server-identities>
    <ssl>
      <keystore path="server.keystore" relative-to="jboss.server.config.dir" keystore-password="keystore_password" alias="server" key-password="key_password" />
    </ssl>
  </server-identities>
  <authentication>
    <truststore path="server.truststore" relative-to="jboss.server.config.dir" keystore-password="truststore_password" />
    <local default-user="$local"/>
    <properties path="mgmt-users.properties" relative-to="jboss.server.config.dir"/>
  </authentication>
</security-realm>
----

In this scenario if Client-Cert authentication does not occur clients
can fall back to use either the local mechanism or username/password
authentication. To make Client-Cert based authentication mandatory just
remove the `<local />` and `<properties />` elements.
