No description, website, or topics provided.
Clone or download
Permalink
Failed to load latest commit information.
action-token-authenticator Updated to 4.4.0.Final Sep 5, 2018
action-token-required-action Updated to 4.4.0.Final Sep 5, 2018
app-angular2 Updated to 4.4.0.Final Sep 5, 2018
app-authz-jee-servlet Updated to 4.4.0.Final Sep 5, 2018
app-authz-jee-vanilla Updated to 4.4.0.Final Sep 5, 2018
app-authz-photoz Updated to 4.4.0.Final Sep 5, 2018
app-authz-rest-employee Updated to 4.4.0.Final Sep 5, 2018
app-authz-rest-springboot Updated to 4.4.0.Final Sep 5, 2018
app-authz-spring-security Updated to 4.4.0.Final Sep 5, 2018
app-authz-springboot Updated to 4.4.0.Final Sep 5, 2018
app-authz-uma-photoz Updated to 4.4.0.Final Sep 5, 2018
app-jee-html5 Updated to 4.4.0.Final Sep 5, 2018
app-jee-jsp Updated to 4.4.0.Final Sep 5, 2018
app-profile-jee-html5 Updated to 4.4.0.Final Sep 5, 2018
app-profile-jee-jsp Updated to 4.4.0.Final Sep 5, 2018
app-profile-jee-vanilla Updated to 4.4.0.Final Sep 5, 2018
app-profile-saml-jee-jsp Updated to 4.4.0.Final Sep 5, 2018
app-springboot Updated to 4.4.0.Final Sep 5, 2018
config Quickstarts for RH-SSO 7.0.0.GA Jun 16, 2016
event-listener-sysout Updated to 4.4.0.Final Sep 5, 2018
event-store-mem Updated to 4.4.0.Final Sep 5, 2018
fuse63 Updated to 4.4.0.Final Sep 5, 2018
fuse70 Updated to 4.4.0.Final Sep 5, 2018
scripts KEYCLOAK-7625 Enforcer plugin cleanup Jul 13, 2018
service-jee-jaxrs Updated to 4.4.0.Final Sep 5, 2018
service-nodejs [KEYCLOAK-5798] Move keycloak-nodejs-auth-utils and keycloak-nodejs-c… Nov 7, 2017
service-springboot-rest Updated to 4.4.0.Final Sep 5, 2018
user-storage-jpa Updated to 4.4.0.Final Sep 5, 2018
user-storage-simple Updated to 4.4.0.Final Sep 5, 2018
.gitignore Angular 2 Quickstart May 16, 2017
.travis.yml KEYCLOAK-7625 Enforcer plugin cleanup Jul 13, 2018
LICENSE Quickstarts for RH-SSO 7.0.0.GA Jun 16, 2016
README.md KEYCLOAK-6796 Not able to run tests without -Pwildfly-managed Mar 21, 2018
maven-settings.xml [KEYCLOAK-4869] Integration tests for app-html5 are failing after upg… May 24, 2017
pom.xml Updated to 4.4.0.Final Sep 5, 2018
productize.sh [KEYCLOAK-6593] - Fixes ComparisonFailure in RHSSO tests. Mar 6, 2018
quickstart-realm.json fixing merge conflict and updated the README for service-ee Mar 9, 2017
set-version.sh Fix issues with bumping versions on release Nov 8, 2017
travis-run-tests.sh KEYCLOAK-7422 Quickstarts for Fuse 7 Aug 14, 2018
travis-server.sh Bump version Feb 27, 2018

README.md

Keycloak Quickstarts

The quickstarts demonstrate securing applications with Keycloak. They provide small, specific, working examples that can be used as a reference for your own project.

Introduction

These quickstarts run on WildFly 10.

Prior to running the quickstarts you should read this entire document and have completed the following steps:

Afterwards you should read the README file for the quickstart you would like to deploy. See examples for a list of the available quickstarts.

If you run into any problems please refer to the troubleshooting section.

Use of KEYCLOAK_HOME and WILDFLY_HOME Variables

The quickstart README files use the replaceable value KEYCLOAK_HOME to denote the path to the Keycloak installation and the value WILDFLY_HOME to denote the path to the WildFly installation. When you encounter this value in a README file, be sure to replace it with the actual path to your installations.

System Requirements

The applications these projects produce are designed to be run on WildFly Application Server 10.

All you need to build these projects is Java 8.0 (Java SDK 1.8) or later and Maven 3.1.1 or later.

Start the Keycloak Server

By default the Keycloak Server uses the same ports as the WildFly Server. To run the quickstarts you can either run the Keycloak Server on a separate host (machine, VM, Docker, etc..) or on different ports.

To start the Keycloak server on a separate host:

  1. Open a terminal on the separate machine and navigate to the root of the Keycloak server directory.

  2. The following shows the command to start the Keycloak server:

    For Linux:   KEYCLOAK_HOME/bin/standalone.sh -b 0.0.0.0
    For Windows: KEYCLOAK_HOME\bin\standalone.bat -b 0.0.0.0
    
  3. The URL of the Keycloak server will be http://<HOSTNAME>:8080 (replace <HOSTNAME> with the hostname of the separate host).

To start the Keycloak server on different ports:

  1. Open a terminal and navigate to the root of the Keycloak server directory.

  2. The following shows the command to start the Keycloak server:

    For Linux:   KEYCLOAK_HOME/bin/standalone.sh -Djboss.socket.binding.port-offset=100
    For Windows: KEYCLOAK_HOME\bin\standalone.bat -Djboss.socket.binding.port-offset=100
    
  3. The URL of the Keycloak server will be http://localhost:8180

Add Admin User

Open the main page for the Keycloak server (localhost:8180 or http://<HOSTNAME>:8080). If this is a new installation of Keycloak server you will be instructed to create an initial admin user. To continue with the quickstarts you need to do this prior to continuing.

Create Roles and User

To be able to use the examples you need to create some roles as well as at least one sample user. To do first this open the Keycloak admin console (localhost:8180/auth/admin or http://<HOSTNAME>:8080/auth/admin) and login with the admin user you created in the add admin user section.

Start by creating a user role:

  • Select Roles from the menu
  • Click Add Role
  • Enter user as Role Name
  • Click Save

Next create a user:

  • Select Users from the menu
  • Click Add user
  • Enter any values you want for the user
  • Click Save
  • Select Credentials from the tabs
  • Enter a password in New Password and Password Confirmation
  • Click on the toggle to disable Temporary
  • Click Reset Password
  • Click Role Mappings
  • Select user under Available Roles and click Add selected

As an alternative to manually creating the role and user you can use the partial import feature in the admin console and import the file config/partial-import.json into your realm.

One more step, if you want to access the examples with the admin user you need to add the user role to admin user:

  • Select Users from the menu
  • Click View all users
  • Click Edit for admin user
  • Click Role Mappings
  • Select user under Available Roles and click Add selected

Start and Configure the WildFly Server

Before starting the WildFly Server start by extracting the Keycloak client adapter into it.

For WildFly 10 extract keycloak-wildfly-adapter-${project.version}.zip into WILDFLY_HOME.

If you plan to try the SAML examples you also need the SAML WildFly adapter. To do this for WildFly 10 keycloak-saml-wildfly-adapter-dist-${project.version}.zip into WILDFLY_HOME.

The next step is to start WildFly server:

  1. Open a terminal and navigate to the root of the WildFly server directory.

  2. Use the following command to start the WildFly server:

    For Linux:   EAP_HOME/bin/standalone.sh
    For Windows: EAP_HOME\bin\standalone.bat
    
  3. To install the Keycloak adapter run the following commands:

    For Linux:
    
      WILDFLY_HOME/bin/jboss-cli.sh -c --file=WILDFLY_HOME/bin/adapter-install.cli
      WILDFLY_HOME/bin/jboss-cli.sh -c --command=:reload
    
    For Windows:
    
     WILDFLY_HOME\bin\jboss-cli.bat -c --file=WILDFLY_HOME\bin\adapter-install.cli
     WILDFLY_HOME\bin\jboss-cli.bat -c --command=:reload
    
  4. If you plan to try the SAML examples you also need to install Keycloak SAML adapter:

    For Linux:
    
      WILDFLY_HOME/bin/jboss-cli.sh -c --file=WILDFLY_HOME/bin/adapter-install-saml.cli
      WILDFLY_HOME/bin/jboss-cli.sh -c --command=:reload
    
    For Windows:
    
      WILDFLY_HOME\bin\jboss-cli.bat -c --file=WILDFLY_HOME\bin\adapter-install-saml.cli
      WILDFLY_HOME\bin\jboss-cli.bat -c --command=:reload
    

Integration tests

By default, the integration tests for each quickstart, expect this initial admin user to have admin as username and admin as password. This is configurable in each ArquillianTest class.

static {
    try {
        importTestRealm("admin", "admin", "/quickstart-realm.json");
    } catch (IOException e) {
        e.printStackTrace();
    }
}

If you don't have access to admin's credentials, please import the quickstart-realm.json from src/test/resources.

To run integration tests for Wildfly managed quickstarts use the following command:

mvn clean install -Pwildfly-managed -Denforcer.skip=true

If you want to run the tests for a quickstart that doesn't need Wildfly, you have to use appropriate profile. See a particular quickstart's README for more details.

Examples

  • app-angular2 - Angular 2 application that invokes the example service. Requires service example to be deployed.
  • app-jee-html5 - HTML5 application that invokes the example service. Requires service example to be deployed.
  • app-jee-jsp - JSP application packaged that invokes the example service. Requires service example to be deployed.
  • app-profile-jee-html5 - HTML5 application that displays user profile and token details.
  • app-profile-jee-jsp - JSP application that displays user profile and token details.
  • app-profile-jee-vanilla - JSP application configured with basic authentication. Shows how to secure an application with the client adapter subsystem.
  • app-profile-saml-jee-jsp - JSP application that uses SAML and displays user profile.
  • service-jee-jaxrs - JAX-RS Service with public and protected endpoints.

Troubleshooting

Problem Probable Cause Possible Solution
Some required files are missing / Some Enforcer rules have failed Client adapter config is missing Add client adapter installation file to config directory as specified in quickstart README.md
Unknown authentication mechanism KEYCLOAK OpenID Connect client adapter missing Install OpenID Connect adapter as specified in the Start and Configure the WildFLy Server section
Unknown authentication mechanism KEYCLOAK-SAML SAML client adapter missing Install SAML adapter as specified in the Start and Configure the WildFLy Server section
Failed to invoke service: 404 Not Found Service not deployed, or service URL not correct Deploy service or change the URL for the service as specified in the quickstart README
Failed to invoke service: Request failed message with no error code CORS not enabled Most likely cause is that you've deployed the HTML5 application to a different host than the service, if so the solution is to add CORS support to the service. See the README for the service for how to enable.
Page displays: Forbidden Authenticated user is missing a role required to access the url This can happen if you fail to add user role to admin user as instructed in Create Roles and User.

Reporting security vulnerabilities

If you've found a security vulnerability, please look at the instructions on how to properly report it