Skip to content

Latest commit

 

History

History
191 lines (157 loc) · 10.1 KB

keycloak_local_setup.md

File metadata and controls

191 lines (157 loc) · 10.1 KB
Raw

Local setup of keycloak for Sunbird

This readme file provides instructions for setting up keycloak for sunbird in a local machine.

System Requirements

Prerequisites

  • Java 11
  • Latest Docker

Steps for local setup

To set up the keyloak for sunbird in local, follow the steps below:

  1. Clone the latest branch of the user-org service using the following command:
git clone https://github.com/Sunbird-Lern/sunbird-lms-service.git
  1. Execute the shell script present in the path <project-base-path>/sunbird-lms-service/keycloak-local-setup/keycloak_v701:
sh keycloak_docker.sh

Note: Modify 'keycloak_docker.sh' file using a text editor to prepend 'sudo ' to all docker commands if you don't have root user permissions. Example:

sudo docker network create keycloak-postgres-network
  1. Wait for the script to complete execution and make sure the keycloak container and postgres container creation is successful before proceeding to the next step using the below command:
docker ps -a

Note: Prepend 'sudo ' to above command if you don't have root user permissions.

Verify docker containers exists with names 'kc_local' and 'kc_postgres' and are running.

  1. Command to connect to postgres database:
docker exec -it kc_postgres sh
psql postgresql://kcpgadmin:kcpgpassword@kc_postgres:5432/quartz

  1. To verify if keycloak for sunbird is configured,

    • login to keycloak ( http://localhost:8080/auth - use keycloak credentials mentioned in 'keycloak_docker.sh').
    • Check if 'Sunbird' realm is selected. img_1.jpg
    • Check if 'sunbird' is available as an option under 'Themes' realm sub-menu for 'Login Theme' and 'Email Theme'. img_2.jpg
    • Check if 'cassandra-storage-provider' is present under 'User Federation' configuration menu. Open 'Cassandra-storage-provide' and copy the 'Provider ID' value. This is the value to be saved for 'sunbird_keycloak_user_federation_provider_id' config variable while integration with user-org service. img_11.png spi_provider_id.png
    • Check if clients (portal, lms, android, etc.) are available img_4.jpg

  2. Open 'LMS' client from 'Clients' Menu. Go to 'Service Account Roles' tab and add 'admin' role in 'Realm Roles' as shown img_5.jpg

  3. In 'Client Roles' drop down of 'LMS' client, select 'realm-management' and add 'manage-users' role as shown img_6.jpg

  4. In 'Settings' tab of 'LMS' client, enable 'Direct Access Grants Enabled' img.png

  5. In 'Credentials' tab of 'LMS' client, click on 'Regenerate Secret' button with 'Client Authenticator' as 'Client Id and Secret'. This is the value to be saved for 'sunbird_sso_client_secret' config variable while integration with user-org service. (sunbird_sso_client_id = lms, sunbird_sso_client_secret = newly generated secret)

  6. Local user-org setup keycloak related configurations will be as follows:

sunbird_keycloak_user_federation_provider_id = #Cassandra-storage-provider - Provider Id value. 
sunbird_sso_url = http://localhost:8080/auth/
sunbird_sso_realm = sunbird
sunbird_sso_client_id = lms
sunbird_sso_client_secret = #newly generated secret of 'lms' client
sunbird_sso_publickey = #publickey value from Sunbird realm, 'Keys' tab RS256 algorithm
sunbird_sso_username = admin
sunbird_sso_password = sunbird
sunbird_pg_db=quartz
sunbird_pg_user=kcpgadmin
sunbird_pg_password=kcpgpassword

Shell script docker commands description

Shell script contains docker commands to create postgres v11.2 database container and keycloak v7.0.1 container. It also has commands to copy sunbird keycloak artifacts viz SPI provider jar, themes, postgres driver module, realm and configuration changes to keycloak.

  • "-p 32769:5432" maps the host's port 32769 to the container's port 5432, allowing access to the postgres database.
  • "-p 8080:8080" maps the host's port 8080 to the container's port 8080, allowing access to the keycloak application. Update the host's port to unused port number if the '8080' port is already used by another application.
  • "--name <container_name>" assigns a name to the container, which can be used to reference it in other Docker commands.
  • "-v $sunbird_dbs_path/keycloak/realm:/opt/jboss/keycloak/imports" mounts the host's directory "$sunbird_dbs_path/keycloak/realm" containing sunbird realm to container's "/opt/jboss/keycloak/imports"
  • "-v $sunbird_dbs_path/keycloak/spi:/opt/jboss/keycloak/providers" mounts the host's directory "$sunbird_dbs_path/keycloak/spi" containing sunbird-auth keycloak SPI jar to container's "/opt/jboss/keycloak/providers"
  • "-v $sunbird_dbs_path/keycloak/modules:/opt/jboss/keycloak/modules/system/layers/keycloak/org/postgresql/main" mounts the host's directory "$sunbird_dbs_path/keycloak/modules" containing postgres driver module to container's "/opt/jboss/keycloak/modules/system/layers/keycloak/org/postgresql/main"
  • "-e KEYCLOAK_IMPORT="/opt/jboss/keycloak/imports/sunbird-realm.json -Dkeycloak.profile.feature.upload_scripts=enabled"" sets an environment variables necessary for keycloak to import sunbird realm.
  • "--net <network_name>" assigns the container to a Docker network, which is used to connect the container to other containers in the same network.
  • "-d" runs the container in detached mode, which allows it to run in the background.

Latest sunbird keycloak artifacts repositories

Understanding keycloak on Sunbird

Please refer to https://project-sunbird.atlassian.net/l/cp/St3y353z for understanding keycloak on sunbird and user authentication flows.

Steps for integrating local keycloak setup with local user-org service setup

  1. Ensure postgres and keycloak containers are up and running.
  2. Ensure environment variables are exported with values from keycloak as mentioned above in 'Step 10'
  3. Ensure public key from 'sunbird' realm is copied as file under 'keys' folder with 'kid' as file name. Run below command after updating '$PATH_TO_WORKSPACE' value in the command.
env "accesstoken.publickey.basepath=$PATH_TO_WORKSPACE/keys/" bash

img_13.pngimg_12.png 4. Add CORS filter to 'application.conf' in controller folder of user-org service.

  enabled += "play.filters.cors.CORSFilter"

img_7.png 5. Ensure local user-org service is restarted after above steps 6. Create a default organisations 'custodian' and 'sunbird' in your local setup. (with property 'channel_registration_disabled=true' in externalresource.properties). Save organisation Ids from response. 7. export 'custodian' organisation id value from response to 'custodianRootOrgId' and 'custodianOrgId' environment variables. 8. Restart user-org service.

Steps to create default system admin user and other tenant users

  1. Login to keycloak and go to 'Users' menu. Click 'Add user' button. Enter user details and 'Save'. img_8.png img_9.png
  2. As default user gets created, go to 'Role Mappings' sub menu of the user. Add 'admin' to 'Assigned Roles'. img_18.png
  3. Under 'Client Roles', select 'realm management' and add 'manage-users' to 'Assigned Roles'. img_19.png
  4. Go to 'Credentials' menu and set password for the default user. img_20.png
  5. Now you can generate token for creating users via below CURL with default system admin user token.
    • CURL TO GENERATE USER TOKEN. Copy "access_token" value from the response and use as create user CURL 'x-authenticated-user-token' header's value. img_21.png
curl --location --request POST 'localhost:8080/auth/realms/sunbird/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=lms' \
--data-urlencode 'client_secret=#newly generated secret of 'lms' client' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=Systemadminuser' \
--data-urlencode 'password=Test@123'
  • CURL TO CREATE USER.
    img_22.png
curl --location --request POST 'localhost:9000/v1/ssouser/create' \
--header 'Content-Type: application/json' \
--header 'x-authenticated-user-token: #'access_token' value from above CURL response' \
--data-raw '{
    "request": {
        "firstName": "Test",
        "lastName": "user",
        "channel": "sunbird",
        "userName": "testuser",
        "email":"testuser@test.com",
        "emailVerified": true,
        "password": "Test@123",
        "userType": "teacher"
    }
}'

img_15.png 6. login to keycloak. Go to user's menu and search for the user using username img_14.png img_16.png 7. Ensure you are able to generate user token for the newly created user

curl --location --request POST 'localhost:8080/auth/realms/sunbird/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=lms' \
--data-urlencode 'client_secret= #newly generated secret of 'lms' client' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=testuser' \
--data-urlencode 'password=Test@123'

img_17.png

Note: Always create an admin user belonging to a tenant and assign 'ORG_ADMIN' role. Org Admin has ability to create other users via application.

Steps to perform token validation

For server side token validation, please refer to https://project-sunbird.atlassian.net/wiki/spaces/DevOps/pages/3274276929/Adminutils+on+Sunbird