Skip to main content

Dynamic 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.

Objective​

Objective of this document is to guide user step by step how to configure KeyCloak with OPNBI and how users and roles can be created dynamically.

info

User & Role can be created Dynamically in OPNBI if and only if that user is available in KeyCload and not in OPNBI. This feature is usefull when a user is created in KeyCloak and it is required that that user should be logged in OPNBI. But for a user to logged in into OPNBI, user should be created in OPNBI then and only then a user can logged in to OPNBI application. But this process fource admin user to create user in both KeyCloak and in OPNBI which means admin user has to perform same task 2 times.

To save time and effort, OPNBI will intelligently check user availability in KeyCloak and create new user & Role during login process if match found in KeyCloak. Thus OPNBI intelligently reduces the Admin efforts and create user and role on the fly.

Docusaurus Slash Introduction

Figure: Dynamic User & Role creation Flow diagram

Prerequisites​

  • Download sample project and dependency files from here..

  • insertuser_enabled should be added in config.json file inside sso property. If you do not find this property in you cofig.json file, please copy property from below;

    {
        "name" : "insertuser_enabled",
        "displayName" : "Insert User",
        "defaultValue" : true,
        "type" : "checkbox"
    }

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

    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 passowrd

    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 passowrd button to save this password. You will see passowrd 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 opnbi URL in following fields,

    Root URL:http://localhost:9090/opnbi/

    Valid Redirect URIs : *

    Base URL:http://localhost:9090/opnbi/

    Admin URL : http://localhost:9090/opnbi/

    Web Origins : *

    Backchannel Logout URL : http://localhost:9090/opnbi/v5/api/logout

    info

    You can provide your opnbi URL and port number but make sure opnbi 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 opnbiadmin

    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.

    Docusaurus Slash Introduction

  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 opnbi. this is located at (your_directory)/OPNBI/tomcat/webapps/opnbi/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 OPNBI. to add these jar files go to lib folder located at (your_directory)/OPNBI/tomcat/Webapps/opnbi/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 opnbi lib folder. First we need to stop opnbi tomcat server if running. Go to OPNBI folder and execute stop_opnbi.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)/OPNBI/tomcat/webapps/opnbi/WEB-INF/lib/

  7. Place project jar file here and start tomcat server.

  8. Once server is started, enter url to open OPNBI. Here OPNBI is running in local machine and port number is 9090.

    http://localhost:9090/opnbi

    info

    Make sure you clear your browser history before openning opnbi

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

  1. Go to (your directory)/OPNBI/tomcat/webapps/opnbi/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)/OPNBI/tomcat/webapps/opnbi/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 OPNBI 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;

    warning

    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.

    <filter> 

      <filter-name>opnbi</filter-name> 

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

    </filter> 

    <filter-mapping> 

      <filter-name> opnbi </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>

  4. Add KeyCloak jar file in to lib folder of OPNBI. This lib folder can be founded at (your_directory)/OPNBI/tomcat/webapps/opnbi/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)/OPNBI/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 defaultValue is class path for KeyCloak project file. if you are creating your own project provide project path here.

    Docusaurus Slash Introduction

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 OPNBI. Now you will not see OPNBI 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 OPNBI Admin user

    Docusaurus Slash Introduction

Task 5. Create User and Role On Fly​

To check this feature, lets create a new user in KeyCloak which is not available in OPNBI as well. Go through Create new user and Assign role to user steps from Task 1 to create and configure new user in KeyCloak,

  • Create new user

  • Assign role to user

  1. Once user is created, open OPNBI login page in browser. Provide user name and password you have just created and click on sign in button.

  2. As this user is not available in OPNBI, SSO code will take care of User & role creation in OPNBI.

  3. It will fetch userOptions and roleOptions from the SSO code and create a new User & Assign role to user.

  4. Once all these operations completed, SSO will fetch user info and navigate user to landing page of OPNBI.

info

If user want to provide default user and role options for new user, he can configure this in SSO code provided. This userOptions & roleOptions are set to provide new user Read only access.

This rights provided can be modified by Admin user afterwards from User section.

  1. Validate user created in OPNBI by logged in to OPNBI application with admin user and check user and assigned role from User section.

  2. Also Check in repository, folder created or not for that user