KEYCLOAK-7127 first set of changes from Getting Started review (#377)
* KEYCLOAK-7127 first set of changes from Getting Started review * further cleaning up and deleted some graphics that are no longer needed
This commit is contained in:
Matthew Helmke
Stian Thorgersen
parent
0b83c74907
commit
a9a5fb0c37
12 changed files with 48 additions and 62 deletions
Binary file not shown.
|
Before Width: | Height: | Size: 20 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 54 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 69 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 23 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 72 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 70 KiB |
|
|
@ -1,7 +1,8 @@
|
|||
|
||||
== Securing a JBoss Servlet Application
|
||||
|
||||
In this section you will learn how to secure a Java Servlet application on the {appserver_name} application server. You will learn how to install the
|
||||
{project_name} Client Adapter onto a {appserver_name} application server distribution. You will create and register a client application in the
|
||||
{project_name} Admin Console. Finally, you will configure the application to be secured by {project_name}.
|
||||
This section describes how to secure a Java servlet application on the {appserver_name} application server by:
|
||||
* Installing the {project_name} client adapter on a {appserver_name} application server distribution
|
||||
* Creating and registering a client application in the {project_name} admin console
|
||||
* Configuring the application to be secured by {project_name}
|
||||
|
||||
|
|
|
|||
|
|
@ -1,15 +1,13 @@
|
|||
|
||||
=== Before You Start
|
||||
|
||||
Before you can participate in this tutorial, you need to complete the installation of {project_name} and create the
|
||||
initial admin user as shown in the <<_install-boot, Installing and Booting>> tutorial. There is one
|
||||
caveat to this. You have to run a separate {appserver_name} instance on the same machine as the
|
||||
{project_name} server. This separate instance will run your Java Servlet application. Because of this you will
|
||||
have to run the {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 {project_name} server.
|
||||
Before you can secure a Java servlet application, you must complete the installation of {project_name} and create the initial admin user as shown in <<_install-boot, Installing and Booting>>.
|
||||
|
||||
To boot the {project_name} server:
|
||||
There is one caveat: you must run a separate {appserver_name} instance on the same machine as the {project_name} server to run your Java servlet application. Run the {project_name} using a different port than the {appserver_name}, to avoid port conflicts.
|
||||
|
||||
To adjust the port used, change the value of the `jboss.socket.binding.port-offset` system property when starting the server from 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 {project_name} server.
|
||||
|
||||
To start the {project_name} server while also adjusting the port:
|
||||
|
||||
.Linux/Unix
|
||||
[source]
|
||||
|
|
@ -23,6 +21,6 @@ $ .../bin/standalone.sh -Djboss.socket.binding.port-offset=100
|
|||
> ...\bin\standalone.bat -Djboss.socket.binding.port-offset=100
|
||||
----
|
||||
|
||||
After booting up {project_name}, you can then access the admin console at http://localhost:8180/auth/admin/
|
||||
After starting {project_name}, go to http://localhost:8180/auth/admin/ to access the admin console.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,32 +1,27 @@
|
|||
|
||||
=== Creating and Registering the Client
|
||||
|
||||
The next step you have to do is to define and register the client in the {project_name} Admin Console.
|
||||
To define and register the client in the {project_name} admin console, complete the following steps:
|
||||
|
||||
. Log into
|
||||
the Admin Console with your admin account as you did in previous tutorials.
|
||||
. Log in to the admin console with your admin account.
|
||||
|
||||
. In the top left dropdown menu select and manage
|
||||
the `demo` realm. Click `Clients` in the left side menu. The Clients page opens.
|
||||
. In the top left drop-down menu select and manage the `Demo` realm. Click `Clients` in the left side menu to open the Clients page.
|
||||
+
|
||||
.Clients
|
||||
image:{project_images}/clients.png[]
|
||||
|
||||
. On the right click *Create*.
|
||||
. On the right side, click *Create*.
|
||||
|
||||
. Complete the fields as shown below:
|
||||
. Complete the fields as shown here:
|
||||
+
|
||||
.Add Client
|
||||
image:{project_images}/add-client.png[]
|
||||
|
||||
. After clicking the `Save` button your client application entry will be created. You now have to go back to the {appserver_name}
|
||||
instance that the application is deployed on and configure it so that this app is secured by {project_name}. You can obtain
|
||||
a template for the configuration you need by going to the `Installation` tab in the client entry in the {project_name} Admin Console.
|
||||
+
|
||||
.Installation Tab
|
||||
image:{project_images}/client-installation.png[]
|
||||
. Click *Save* to create the client application entry.
|
||||
|
||||
. Select *Keycloak OIDC JBoss Subsystem XML*. An XML template is generated that you'll need to cut and paste.
|
||||
. Click the *Installation* tab in the {project_name} admin console to obtain a configuration template.
|
||||
|
||||
. Select *Keycloak OIDC JBoss Subsystem XML* to generate an XML template. Copy the contents for use in the next section.
|
||||
+
|
||||
.Template XML
|
||||
image:{project_images}/client-install-selected.png[]
|
||||
|
|
@ -34,3 +29,5 @@ image:{project_images}/client-install-selected.png[]
|
|||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,22 +1,25 @@
|
|||
|
||||
=== Downloading, Building, and Deploying Application Code
|
||||
|
||||
The project and code for the application you are going to secure is available in link:{quickstartRepo_link}[{quickstartRepo_name}]. You will need the following
|
||||
installed on your machine and available in your PATH before you can continue:
|
||||
You must have the following installed on your machine and available in your PATH before you continue:
|
||||
|
||||
* Java JDK 8
|
||||
* Apache Maven 3.1.1 or higher
|
||||
* Git
|
||||
|
||||
ifeval::[{project_community}==true]
|
||||
You can obtain the code by cloning the repository at {quickstartRepo_link}. The quickstarts are designed to work with the most recent Keycloak release.
|
||||
NOTE: You can obtain the code by cloning the {quickstartRepo_name} repository at {quickstartRepo_link}. The quickstarts are designed to work with the most recent Keycloak release.
|
||||
|
||||
endif::[]
|
||||
|
||||
ifeval::[{project_product}==true]
|
||||
You can obtain the code by cloning the repository at {quickstartRepo_link}. Use the branch matching the version of {project_name} in use.
|
||||
NOTE: You can obtain the code by cloning the repository at {quickstartRepo_link}. Use the branch matching the version of {project_name} in use.
|
||||
|
||||
endif::[]
|
||||
|
||||
Follow these steps to download the code, build it, and deploy it. Make sure your {appserver_name} application server is started before you run these steps.
|
||||
Make sure your {appserver_name} application server is started before you continue.
|
||||
|
||||
To download, build, and deploy the code, complete the following steps.
|
||||
|
||||
.Clone Project
|
||||
[source, subs="attributes"]
|
||||
|
|
@ -26,21 +29,9 @@ $ cd {quickstartRepo_dir}/app-profile-jee-vanilla
|
|||
$ mvn clean wildfly:deploy
|
||||
----
|
||||
|
||||
You should see some text scroll down in the application server console window. After the application is successfully deployed go to:
|
||||
During installation, you will see some text scroll by in the application server console window.
|
||||
|
||||
http://localhost:8080/vanilla
|
||||
To confirm that the application is successfully deployed, go to http://localhost:8080/vanilla and a login page should appear.
|
||||
|
||||
.Application Login Page
|
||||
image:{project_images}/app-login-page.png[]
|
||||
NOTE: If you click *Login*, the browser will pop up a BASIC auth login dialog. However, the application is not yet secured by any identity provider, so anything you enter in the dialog box will result in a `Forbidden` message being sent back by the server. You can confirm that the application is currently secured via `BASIC` authentication by finding the setting in the application's `web.xml` file.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.Application Login Dialog
|
||||
image:{project_images}/client-auth-required.png[]
|
||||
|
||||
|
||||
The application is not secured by any identity provider, so anything you enter in the dialog box will result in a `Forbidden` message being
|
||||
sent back by the server. The next section describes how you can take this deployed application and secure it.
|
||||
|
|
|
|||
|
|
@ -1,20 +1,19 @@
|
|||
|
||||
=== Installing the Client Adapter
|
||||
|
||||
Download the {appserver_name} distribution and unzip
|
||||
it into a directory on your machine.
|
||||
Download the {appserver_name} distribution and extract it from the compressed file into a directory on your machine.
|
||||
|
||||
ifeval::[{project_community}==true]
|
||||
Next download the WildFly OpenID Connect adapter distribution from link:https://www.keycloak.org/downloads.html[keycloak.org].
|
||||
Download the WildFly OpenID Connect adapter distribution from link:https://www.keycloak.org/downloads.html[keycloak.org].
|
||||
endif::[]
|
||||
|
||||
ifeval::[{project_product}==true]
|
||||
Next download the RH-SSO-{project_version}-eap7-adapter.zip distribution.
|
||||
Download the RH-SSO-{project_version}-eap7-adapter.zip distribution.
|
||||
endif::[]
|
||||
|
||||
Unzip this file into the root directory of your {appserver_name} distribution.
|
||||
Extract the contents of this file into the root directory of your {appserver_name} distribution.
|
||||
|
||||
Next perform the following actions:
|
||||
Run the appropriate script for your platform:
|
||||
|
||||
.WildFly 10 and Linux/Unix
|
||||
[source]
|
||||
|
|
@ -46,8 +45,9 @@ $ ./jboss-cli.sh --file=adapter-elytron-install-offline.cli
|
|||
----
|
||||
endif::[]
|
||||
|
||||
This script will make the appropriate edits to the _.../standalone/configuration/standalone.xml_ file of your app
|
||||
server distribution. Finally, boot the application server.
|
||||
NOTE: This script will make the necessary edits to the `.../standalone/configuration/standalone.xml` file of your app server distribution.
|
||||
|
||||
Start the application server.
|
||||
|
||||
.Linux/Unix
|
||||
[source]
|
||||
|
|
|
|||
|
|
@ -1,17 +1,16 @@
|
|||
|
||||
=== Configuring the Subsystem
|
||||
|
||||
Now that you have copied the XML template from the Installation page, you need to paste this into the _standalone.xml_ file
|
||||
that resides in the _standalone/configuration_ directory of the application server instance on which your application is deployed.
|
||||
To configure the {appserver_name} instance that the application is deployed on so that this app is secured by {project_name}, complete the following steps.
|
||||
|
||||
. Open the standalone/configuration/standalone.xml file and search for the following text:
|
||||
. Open the `standalone/configuration/standalone.xml` file in the {appserver_name} instance that the application is deployed on and search for the following text:
|
||||
+
|
||||
[source,xml]
|
||||
----
|
||||
<subsystem xmlns="urn:jboss:domain:keycloak:1.1"/>
|
||||
----
|
||||
|
||||
. Modify this to prepare it for pasting in your template from the Installation page:
|
||||
. Modify this text to prepare the file for pasting in contents from the *Keycloak OIDC JBoss Subsystem XML* template we obtained {project_name} admin console *Installation* tab by changing the XML entry from self-closing to using a pair of opening and closing tags:
|
||||
+
|
||||
[source,xml]
|
||||
----
|
||||
|
|
@ -19,7 +18,7 @@ that resides in the _standalone/configuration_ directory of the application serv
|
|||
</subsystem>
|
||||
----
|
||||
|
||||
. Within the <subsystem> element, paste in the template. It will look something like this:
|
||||
. Paste the contents of the template within the `<subsystem>` element, as shown in this example:
|
||||
+
|
||||
[source,xml]
|
||||
----
|
||||
|
|
@ -34,7 +33,7 @@ that resides in the _standalone/configuration_ directory of the application serv
|
|||
</subsystem>
|
||||
----
|
||||
|
||||
. Change the *WAR MODULE NAME* text to *vanilla* as follows:
|
||||
. Change the `name` to `vanilla.war`:
|
||||
+
|
||||
[source,xml]
|
||||
----
|
||||
|
|
@ -44,8 +43,8 @@ that resides in the _standalone/configuration_ directory of the application serv
|
|||
</subsystem>
|
||||
----
|
||||
|
||||
. Reboot your application server.
|
||||
. Reboot the application server.
|
||||
|
||||
. Go to http://localhost:8080/vanilla and click *login*. The {project_name} login page opens. You can log in using the user you created in the <<_create-new-user, Creating a New User>> chapter.
|
||||
. Go to http://localhost:8080/vanilla and click *Login*. When the {project_name} login page opens, log in using the user you created in <<_create-new-user, Creating a New User>>.
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue