client app

This commit is contained in:
Bill Burke 2016-05-10 22:48:33 -04:00
parent 403d494303
commit df46deaf2d
15 changed files with 204 additions and 2 deletions

View file

@ -16,5 +16,9 @@
.. link:topics/first-realm/realm.adoc[Create a New Realm]
.. link:topics/first-realm/user.adoc[Create a New User]
.. link:topics/first-realm/account.adoc[User Account Service]
. link:topics/first-jboss-servlet.adoc[Securing a JBoss Servlet Application]
.. link:topics/installation/system-requirements.adoc[System Requirements]
. link:topics/secure-jboss-app.adoc[Securing a JBoss Servlet Application]
.. link:topics/secure-jboss-app/before.adoc[Before You Start]
.. link:topics/secure-jboss-app/install-client-adapter.adoc[Install the Client Adapter]
.. link:topics/secure-jboss-app/download-quickstarts.adoc[Download, Build, Deploy Application Code]
.. link:topics/secure-jboss-app/create-client.adoc[Create and Register Client]
.. link:topics/secure-jboss-app/subsystem.adoc[Configure Subsystem]

View file

@ -73,6 +73,11 @@
"name": "Keycloak Adminstration Guide",
"link": "https://keycloak.gitbooks.io/server-adminstration-guide/content/"
},
"appguide": {
"name": "Securing Applications with Keycloak",
"link": "https://keycloak.gitbooks.io/server-adminstration-guide/content/"
},
"clientadapter": "RH-SSO-7.0.0.ER10-eap7-adapter.zip",
"project": {
"name": "Keycloak",
"version": "1.9.3.Final-SNAPSHOT"

Binary file not shown.

After

Width:  |  Height:  |  Size: 169 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 108 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 137 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 248 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 166 KiB

BIN
keycloak-images/clients.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 206 KiB

View file

@ -2,6 +2,7 @@
=== Login to Admin Console
After you create the initial admin account, click on the _Administration Console_ link on the bottom of the Welcome Page.
Alternatively you can go to the console url directly at http://localhost:8080/auth/admin/
.Login Page
image:../../{{book.images}}/login-page.png[]

View file

@ -0,0 +1,8 @@
== Securing a JBoss Servlet Application
In this section you will learn how to secure a Java Servlet application on the JBoss EAP 7 or Wildfly 10 application
servers. You will learn how to install the {{book.project.name}} Client Adapter onto a JBoss EAP or Wildfly Application Server
distribution. You will create and register a client application in the {{book.project.name}} Admin Console. Finally,
you will configure the application to be secured by {{book.project.name}}.

View file

@ -0,0 +1,28 @@
=== Before You Start
Before you can participate in this tutorial, you need to complete the installation of {{book.project.name}} and create the
initial admin user as shown in the <<fake/../../first-boot.adoc#_install-boot, Install and Boot>> tutorial. There is one
caveat to this. You are going to have to run a separate JBoss EAP 7 or Wildfly 10 instance on the same machine as the
{{book.project.name}} server. This separate instance will run your Java Servlet application. Because of this you will
have to run the {{book.project.name}} under a different port so that there are no port conflicts when running on the
same machine. Use the `jboss.socket.binding.port-offset` system property on the command line. The value of this property
is a number that will be added to the base value of every port opened by the {{book.project.name} server.
To boot the {{book.project.name}} server:
.Linux/Unix
[source]
----
$ .../bin/standalone.sh -Djboss.socket.binding.port-offset=100
----
.Windows
[source]
----
> ...\bin\standalone.bat -Djboss.socket.binding.port-offset=100
----
After booting up {{book.project.name}}, you can then access the admin console at http://localhost:8180/auth/admin/

View file

@ -0,0 +1,30 @@
=== Create and Register Client
The next step you have to do is to define and register the client in the {{book.project.name}} Admin Console. Log into
the Admin Console with your admin account as you did in previous tutorials. In the top left hand drop down menu select and manage
the `demo` realm. Next click the `Clients` left menu. This will bring you to the `Clients` page.
.Clients
image:../../{{book.images}}/clients.png[]
On the right hand side you should see a button named `Create`. Click this button and fill in the fields as shown below:
.Add Client
image:../../{{book.images}}/add-client.png[]
After clicking the `Save` button your client application entry will be created. You now have to go back to the JBoss EAP or Wildfly
instance that the application is deployed on and configure it so that this app is secured by {{book.project.name}}. You can obtain
a template for the configuration you need by going to the `Installation` tab in the client entry in the {{book.project.name}} Admin Console.
.Installation Tab
image:../../{{book.images}}/client-installation.png[]
Select the `Keycloak OIDC JBoss Subsystem XML` option. This will generate an XML template that you'll need to cut and paste.
.Template XML
image:../../{{book.images}}/client-install-selected.png[]

View file

@ -0,0 +1,41 @@
=== Download, Build, Deploy Application Code
The project and code for the application you are going to secure it at Github.com. You will need the following
installed on your machine and available in your PATH before you can continue:
* Java JDK 8
* Apache Maven 3.1.1 or higher
You can obtain the code by cloning the
quickstart repo at git@github.com:jboss-developer/rh-sso-quickstarts.git. Follow these steps to download the code, build it,
and deploy it. Make sure your JBoss EAP or Wildfly app server instance is running before you start these steps!
.clone project
[source]
----
$ git clone git@github.com:jboss-developer/rh-sso-quickstarts.git
$ cd rh-sso-quickstarts/app-profile-jee-vanilla
$ mvn clean wildfly:deploy
----
You should see some text scroll down in the app server console window. After the app is successfully deployed go to:
http://localhost:8080/vanilla
.app login page
image:../../{{book.images}}/app-login-page.png[]
If you open up the application's _web.xml_ file you would see that the application is secured via `BASIC` authentication.
If you click on the login button on the login page, the browser
will pop up a BASIC auth login dialog.
.app login dialog
image:../../{{book.images}}/client-auth-required.png[]
The app is not secured by any identity provider, so anything you enter in the dialog will result in a `Forbidden` message being
sent back by the server. The next section describes how you can take this existing deployed app and secure it.

View file

@ -0,0 +1,35 @@
=== Install the Client Adapter
Download the JBoss EAP 7 or Wildfly 10 distribution you are going to use to run your example application and unzip
it into a directory of your choosing on your machine. Next download the {{book.clientadapter}} distribution. Unzip
this file into the root directory of your JBoss EAP or Wildfly 10 distribution. Next perform the following actions
.Linux/Unix
[source]
----
$ cd bin
$ ./jboss-cli.sh --file=adapter-install-offline.cli
----
.Windows
[source]
----
> cd bin
> jboss-cli.bat --file=adapter-install-offline.cli
----
This script will make the appropriate edits to the _.../standalone/configuration/standalone.xml_ file of your app
server distribution. Finally, just boot the application server.
.Linux/Unix
[source]
----
$ .../bin/standalone.sh
----
.Windows
[source]
----
> ...\bin\standalone.bat
----

View file

@ -0,0 +1,50 @@
=== Configure Subsystem
Now that you have copied the XML template from the `Installation` tab, you need to paste this into the _standalone.xml_ file
that lives in the _standalone/configuration_ directory of the application server instance your application is deployed on.
Open this file and search for the following text:
[source,xml]
----
<subsystem xmlns="urn:jboss:domain:keycloak:1.1"/>
----
Modify this a little bit to prepare it for pasting in your template from the `Installation` tab.
[source,xml]
----
<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
</subsystem>
----
Within the `subsystem` element, paste in the template. It will look something like this:
[source,xml]
----
<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
<secure-deployment name="WAR MODULE NAME.war">
<realm>demo</realm>
<realm-public-key>MIIBIjANBgkqhkiG9B</realm-public-key>
<auth-server-url>http://localhost:8180/auth</auth-server-url>
<public-client>true</public-client>
<ssl-required>EXTERNAL</ssl-required>
<resource>vanilla</resource>
</secure-deployment>
</subsystem>
----
Change the `WAR MODULE NAME` text to be `vanilla` as follows:
[source,xml]
----
<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
<secure-deployment name="vanilla.war">
...
</subsystem>
----
Reboot your application's server and now when visit http://localhost:8080/vanilla and hit the login button, you should
get the {{book.project.name}} login page.