Skip to main content

SSO with KeyCloak

Keycloak is an open source software product to allow single sign-on with Identity and Access Management aimed at modern applications and services

KeyCloak SSO: This Video shows how to configure and use KeyCloak SSO with AIV

Objective​

Objective of this document is to guide user step by step how to configure KeyCloak with AIV

Prerequisites​

  • Download sample project and dependency files from here..

Task 1. Setup and configure keycloak​

  1. Download docker and start docker in you machine. Go through this link to know more about docker installation.

  2. Open PowerShell and run below command once docker is up and running

    docker run -p 8888:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:18.0.0 start-dev

    where,

    info

    8888:8080 = here 8888 is exposed port number and 8080 is internal port number of keycloak.

    Provide keycloak admin user at KEYCLOAK_ADMIN=admin [I have used admin here]

    Provide keycloak admin password at KEYCLOAK_ADMIN_PASSWORD=admin

    danger

    In case your AIV application is running on port number 8080 then you need to change the application port number from server.xml file located in tomcat/conf folder.

    Docusaurus Slash Introduction

  3. This command will download and run KeyCloak in docker

    Docusaurus Slash Introduction

  4. Go to docker application and you will find KeyCloak server is running as shown in below image,

    Docusaurus Slash Introduction

  5. You can access KeyCloak application by running URL in browser,

    localhost:8888/admin

  • Here use port number which you have applied while running command of step 3.

    Docusaurus Slash Introduction

  1. You will see KeyCloak console as shown in below image asking for user name and password

    Docusaurus Slash Introduction

  2. Login with user name and password you have provided in step no 3. in this case, User Name and password both are admin.

    Docusaurus Slash Introduction

  3. You will see landing page like below image,

    Docusaurus Slash Introduction

Create new realm​

  1. Add a new realm in KeyCloak. hover on Master dropdown and you can see Add realm button. Click on that button.

    Docusaurus Slash Introduction

  2. When you click on add realm button you will see Add realm screen as shown in below image,

    Docusaurus Slash Introduction

  3. Click on create button to create a new realm. Once realm is created you will see success message and user will landed on screen shown below,

    Docusaurus Slash Introduction

Create new user​

  1. You need to create a new user in KyeCloak. Click on User section and click on Add user button.

    Docusaurus Slash Introduction

  2. In create user window, write Admin in Username field and make sure User Enabled Option is ON

    Docusaurus Slash Introduction

  3. Click on save button to save the changes and create a user named Admin

  4. Once user is created, you will be navigated on User detail page as shown in below image,

    Docusaurus Slash Introduction

  5. Now user is created we have to provide a valid password for this user. click on Credentials tab and provide password in password field. Also confirm password by writing password in password confirmation field. click on set password button to save this password. You will see password confirmation once password is applied.

    Docusaurus Slash Introduction

  6. Click on Role Mapping, select uma_authorization from avilable roles and click on Add Selected button.

    Docusaurus Slash Introduction

  7. You can see uma_authorization is added in to Assigned Roles

    Docusaurus Slash Introduction

Create new client​

  1. Click on Clients from left menu and click on Create button to add a new client

    Docusaurus Slash Introduction

  2. Provide a Client ID and click on Save button

    Docusaurus Slash Introduction

  3. Once client is created, you will landed on client configuration page

    Docusaurus Slash Introduction

  4. In settings tab in Access Type dropdown select confidential

    Docusaurus Slash Introduction

  5. Enable Service Accounts Enabled property

    Docusaurus Slash Introduction

  6. Scroll down and Enable Authorization Enabled property

    Docusaurus Slash Introduction

  7. Provide aiv URL in following fields,

    Root URL:http://localhost:8080/aiv/

    Valid Redirect URIs : *

    Base URL:http://localhost:8080/aiv/

    Admin URL : http://localhost:8080/aiv/

    Web Origins : *

    Backchannel Logout URL : http://localhost:8080/aiv/v5/api/logout

    info

    You can provide your aiv URL and port number but make sure aiv port number do not match with Keycloak docker port number otherwise it will not work.

    Refer below image for your reference,

    Docusaurus Slash Introduction

  8. Leave all other settings and click on save button to save changes.

  9. Select service account roles and add uma_authorization from Available roles to Assigned Roles

    Docusaurus Slash Introduction

Create new Role​

  1. Click on Roles tab and create a role by clicking on Add Role button

    Docusaurus Slash Introduction

  2. Provide a role name and Click on save button to save changes

    Docusaurus Slash Introduction

Assign role to user​

  1. Now assign role for Admin user we have created, click on user option from left side menu. click on View all users to see all users

    Docusaurus Slash Introduction

  2. Click on ID for that user to open user settings

    Docusaurus Slash Introduction

  3. Click on Role mapping tab and click on Client Roles to see list of available roles

    Docusaurus Slash Introduction

  4. Select role we have created form the list and add that role to Assigned Roles box

    Docusaurus Slash Introduction

  5. Validate user assigned to this role, click on Clients option from left hand side menu.

  6. Click on client ID you have created and here in this example it is aivadmin

    Docusaurus Slash Introduction

  7. Click on Roles section and click on Role name

    Docusaurus Slash Introduction

  8. Click on Users in Role and here you should find admin user liked with this role

    Docusaurus Slash Introduction

Generate KeyCloak.json​

  1. After this setup, you need to download KeyCloak.json file from client section. Click on client option from left side menu and select Client ID we have created.

  2. Click on Installation tab, from Format Option select Keycloak OIDC JSON option. As soon as you select this option JSON data will be displayed on the bottom screen. you need to click on Download button to download this json file.

    Docusaurus Slash Introduction

  3. Place this downloaded json file inside WEB-INF folder of aiv. this is located at (your_directory)/aiv/tomcat/webapps/aiv/WEB-INF/

    Docusaurus Slash Introduction

Task 2. Create java code for SSO and external security​

  1. Download sample project file from link provided in prerequisites.

  2. Open downloaded KeyCloak project in eclipse and go to configure build path.

    Docusaurus Slash Introduction

  3. There are Total 12 jar files whose path you need to reconfigure. amoung of 12 jar files, you will find 8 jar files inside KeyCloak folder in depnedency zip folder provided.

    Docusaurus Slash Introduction

  4. Remove all 12 jars from form build path and add 8 jars provided using Add external jars option.

    Docusaurus Slash Introduction

  5. Remaining 4 Jar files you will find within aiv. to add these jar files go to lib folder located at (your_directory)/aiv/tomcat/Webapps/aiv/WEB-INF/lib folder. Search for below jar file and add in build path one by one;

1. external.jar

2. json-20090211.jar

3. javax.servlet-api-3.0.1.jar

4. log4j-1.2.17.jar

  1. Once all 12 jars are added, click on Apply and Close button to save the changes. you will notice now project has no errors.

  2. Create a jar file of this project by exporting this project. right click on project and click on Export option from the menu.

    Docusaurus Slash Introduction

  3. From export window, select JAR file and click on next button.

    Docusaurus Slash Introduction

  4. In the next window, select export destination, provide jar file name and click on finish button. In case you see any prompt click on ok and finish export operation.

    Docusaurus Slash Introduction

  5. Now we need to add this jar file in aiv lib folder. First we need to stop aiv tomcat server if running. Go to aiv folder and execute stop_aiv.bat file to shut down tomcat server.

  6. After tomcat server is shut down, go to the lib folder and paste newly created project jar file. you can find lib folder at (your_directory)/aiv/tomcat/webapps/aiv/WEB-INF/lib/

  7. Place project jar file here and follow next steps.

Task 3. Configure aiv server for SSO and external security​

  1. Go to (your directory)/aiv/tomcat/webapps/aiv/WEB-INF/classes/ folder and create create com folder under classes and keycloak folder under com folder to match with project path.In resource data you have downloaded there is sso.properties file. Place this file at (your directory)/aiv/tomcat/webapps/aiv/WEB-INF/classes/com/keycloak/ folder.

    info

    This path will not be there by default in all cases, if you do not find the classes folder and its sub folders, create manually

  2. Open sso.properties in text editor and Change These highlighted properties as per your aiv installation. Save the changes after update.

    info

    logPath : Provide path for sso.log file

    Docusaurus Slash Introduction

  3. Add below code snippets in web.xml above AuthenticationFilter property;

    <filter> 

      <filter-name>aiv</filter-name> 

      <filter-class>org.keycloak.adapters.servlet.KeycloakOIDCFilter</filter-class> 

    </filter> 

    <filter-mapping> 

      <filter-name> aiv </filter-name> 

      <url-pattern>/*</url-pattern> 

    </filter-mapping>  

    <filter> 

      <filter-name>AuthenticationKeycloakFilter</filter-name> 

      <filter-class>com.keycloak.AuthenticationKeycloakFilter</filter-class> 

    </filter> 

    <filter-mapping> 

      <filter-name>AuthenticationKeycloakFilter</filter-name> 

      <url-pattern>/*</url-pattern> 

    </filter-mapping>
    danger

    If you are changing project then project path has to be updated in <filter-class> property.

    If you have placed this filter property after AuthenticationFilter property then it will not work.

  4. Add KeyCloak supporting jar file in to lib folder of aiv. This lib folder can be founded at (your_directory)/aiv/tomcat/webapps/aiv/WEB-INF/lib folder. KeyCloak jar files can be found under keycloack folder in the zip file you have downloaded from prerequisites. There should be 8 jar files under keycloack folder.

  5. Configure SSO from config.json file found at (your_directory)/aiv/repository/Config/ folder

  6. Open this file in any text editor and search for sso property.

  • Make following changes in sso property for KeyCloak;

    "checked" : true,

    "defaultValue" : "com.keycloak.KeycloakSSO",
    info

    Here Default value is class path for KeyCloak sso jar file. if you are creating your own project provide project path here.

    • Also add below property in sso properties,
      {
        "name" : "insertuser_enabled",
        "displayName" : "Insert User",
        "defaultValue" : true,
        "type" : "checkbox"
      }

    Docusaurus Slash Introduction

  1. Restart tomcat server. once server is started, enter url in browser to open aiv. Here aiv is running in local machine and port number is 9090.

    http://localhost:8080/aiv

    info

    Make sure you clear your browser history before openning aiv

Task 4. Test end to end flow​

  1. When you run this URL in browser window, it will redirect you to KeyCloak sign in page for aiv. Now you will not see aiv login page any more.

    Docusaurus Slash Introduction

  2. Enter Username and Password we have created in KeyCloak which is Admin in this case. Provide valid user name and password and click on Sign In button.

    Docusaurus Slash Introduction

  3. For the first time Sign In, it will ask you to create new password for sign in user. provide new password in both fields and click on submit button.

    Docusaurus Slash Introduction

  4. If user name and password are correct, it will redirect you on landing page of aiv Admin user

    Docusaurus Slash Introduction

Disable Keycloak​

  1. To disable keycloak, you need to remove keycloak filter properties from web.xml
  • List of properties you need to remove are listed below,
  <filter> 

    <filter-name>aiv</filter-name> 

    <filter-class>org.keycloak.adapters.servlet.KeycloakOIDCFilter</filter-class> 

  </filter> 

  <filter-mapping> 

    <filter-name> aiv </filter-name> 

    <url-pattern>/*</url-pattern> 

  </filter-mapping>  

  <filter> 

    <filter-name>AuthenticationKeycloakFilter</filter-name> 

    <filter-class>com.keycloak.AuthenticationKeycloakFilter</filter-class> 

  </filter> 

  <filter-mapping> 

    <filter-name>AuthenticationKeycloakFilter</filter-name> 

    <url-pattern>/*</url-pattern> 

  </filter-mapping>
  1. You need to Disable sso property from config.json