Skip to content

Latest commit

 

History

History
238 lines (176 loc) · 10.7 KB

README.adoc

File metadata and controls

238 lines (176 loc) · 10.7 KB
Raw

Keycloak Project

Set Up (version 15.0.2)

Firewall

Open firewall ports:

Tip
 It is not mandatory to perform this step unless you have compatibility issues
with yor firewall. 
firewall-cmd --add-port 8090/tcp --permanent
firewall-cmd --add-port 8043/tcp --permanent

Create a podman for keyclock

Important
 It is necessary to map two ports since one is needed for the keycloak console.
In this case, you need to map the 8090 with the 8080 because Quarkus is currently using the 8080. 
podman pod create -p 8090:8080 -p 8543:8443 --name trikora_keycloak_quarkus_example_pod

Delete the previous pod

podman pod rm trikora_keycloak_quarkus_example_pod
Note
 You can see if there is any pod process active with the command:
podman pod ps --all, therefore, you can get the name of the pods which are running in order to kill them.

Run the pod

Firstly it is necessary to copy the realm.json in the tmp/keycloak_tmp/ (local) directory. As this directory is volatile, you have to do this operation each time you restart your PC.
You need to be located in your project root directory in order to perform the following commands.

mkdir /tmp/keycloak_tmp/
cp src/test/resources/trikora-realm.json /tmp/keycloak_tmp/

Then you can execute:

Note
 In the current version of keycloak, it is not possible to run keycloak with an initial database, so you have to run the pod with an empty keycloak and then
import the realm.json with the command line (see below). For that reason the flag -e KEYCLOAK_IMPORT=/tmp/trikora-realm.json has been removed from the run command. 
podman run --name trikora_keycloak_quarkus_example --security-opt label=disable \
  --rm --pod trikora_keycloak_quarkus_example_pod \
  -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin  \
  -v /tmp/keycloak_tmp/:/tmp/ \
  quay.io/keycloak/keycloak:15.0.2
Note
 the --rm flag is set for deleting the pod after the execution. You can kill the process with ^C. Another option would be to launch the command with the -d
flag instead of the --rm one. The -d option will launch the pod as a daemon.

Actions in the keycloak console

Roles

User Management

  • In the user section, you can edit all the information regarding the user such as the email, password …​
    but indeed you have the possibility of assigning new roles to the user as well as enroll them to different groups.

Security Management

  • In this section we will describe how keycloak filter the URLs with the proper permissions.

  • Firstly, you have to locate in Clients → backend-service → Authorization → Settings → Resources.
    Link: https://localhost:8543/auth/admin/master/console/#/realms/trikorasolutions/clients/0ac5df91-e044-4051-bd03-106a3a5fb9cc/authz/resource-server/resource

  • Then, you have to create a new resource where you will establish the URLs that are going to be restricted. For doing so, there is a button Create in the upper-right side of the main layout.

  • After that, it is necessary to add an Associated Permission to the Resource, now you have to decide who is going to have access to the service by creating a new policy. A policy, may be a Role, Group, Client scope or even a single user.
    Once you have linked the policy to the resource, just the desired users could access to the services.

  • If a user without the proper permissions tries to access the service, keycloak will return a http response with status 403 (FORBIDDEN).

How to give an Admin access to the real management endpoints

It is important to have at least one user with enough privileges to communicate with keycloak through the REST endpoints, in order to develop such a thing you
can create a new group and then in the "role-mappings" section of the desired group, then click on "client-roles" after that select the "realm-management" client.

At this point, you should see the roles in the "Available Roles" window. Select the roles you want give to the group and click on "Add selected".

Lastly, do not forget to add the admin user to the group in the Users section of the keycloak console.

Backup and Restore

  • As the keycloak admin console does not allow exporting users, we highly recommend using the command line solution in order to fully export your project.

Export

  • In this section we will describe how to export a realm.json in a single file from a running container using podman.

[podman | docker] exec -it <pod_name> opt/jboss/keycloak/bin/standalone.sh
        -Djboss.socket.binding.port-offset=<interger_value> Docker recommend  an offset of 100 at least
        -Dkeycloak.migration.action=[export | import]
        -Dkeycloak.migration.provider=[singleFile | dir]
        -Dkeycloak.migration.dir=<DIR TO EXPORT TO> Use only iff .migration.provider=dir
        -Dkeycloak.migration.realmName=<REALM_NAME_TO_EXPORT>
        -Dkeycloak.migration.usersExportStrategy=[DIFFERENT_FILES | SKIP | REALM_FILE | SAME_FILE]
        -Dkeycloak.migration.usersPerFile=<integer_value> Use only iff .usersExportStrategy=DIFFERENT_FILES
        -Dkeycloak.migration.file=<FILE TO EXPORT TO>
podman exec -it trikora_keycloak_quarkus_example /opt/jboss/keycloak/bin/standalone.sh \
 -Djboss.socket.binding.port-offset=100 \
 -Dkeycloak.migration.action=export \
 -Dkeycloak.migration.provider=singleFile \
 -Dkeycloak.migration.realmName=trikorasolutions \
 -Dkeycloak.migration.usersExportStrategy=REALM_FILE \
 -Dkeycloak.migration.file=/tmp/trikora-realm.json

Import

 [podman | docker] exec -it <container_name> <PATH_TO_KEYCLOAK_IN_THE_POD>/bin/standalone.sh
 -Djboss.socket.binding.port-offset=100
 -Dkeycloak.migration.action=import
 -Dkeycloak.migration.provider=singleFile
 -Dkeycloak.migration.realmName=quarkus
 -Dkeycloak.migration.usersExportStrategy=REALM_FILE
 -Dkeycloak.migration.file=<FILE_TO_IMPORT>
 -Dkeycloak.profile.feature.upload_scripts=enabled
 -Dkeycloak.profile.feature.scripts=enabled
 -Dkeycloak.migration.strategy=[OVERWRITE_EXISTING | IGNORE_EXISTING]
Important
 When a realm is imported from the command line, the keycloak console is not updated due to a version bug. In order to see the imported realm, it is
necessary to create another realm (empty, only need to enter the realm name). This action will force the console table to be updated, this is a keycloak bug, so
we hope that it could be fixed in futures releases. 
podman exec -it trikora_keycloak_quarkus_example /opt/jboss/keycloak/bin/standalone.sh \
 -Djboss.socket.binding.port-offset=100 \
 -Dkeycloak.migration.action=import \
 -Dkeycloak.migration.provider=singleFile \
 -Dkeycloak.migration.realmName=trikorasolutions \
 -Dkeycloak.migration.usersExportStrategy=REALM_FILE \
 -Dkeycloak.migration.file=/tmp/trikora-realm.json \
 -Dkeycloak.profile.feature.upload_scripts=enabled \
 -Dkeycloak.profile.feature.scripts=enabled \
 -Dkeycloak.migration.strategy=OVERWRITE_EXISTING

Import several files in a single realm

  • If you have stored the data of the project split in several files, you can merge it in a single project just by importing the files as they are a list separated by commas:
    -Dkeycloak.import=/tmp/realm1.json,/tmp/realm2.json

Warning
 You cannot use the keycloak.import parameter with keycloak.migration.X parameters.
If you use these parameters together, keycloak.import parameter will be ignored. The keycloak.import mechanism ignores the realms which already exist in the project.
The keycloak.import mechanism is convenient for development purposes, but if more flexibility is needed, use the keycloak.migration.X parameters.

Open id endpoints

Keycloak allows the user to interact with the system from an OpenID connection which is based on REST, you can see a list of the different endpoints here:
https://localhost:<CONSOLE_PORT>/auth/realms/<REALM_NAME>/.well-known/openid-configuration

Troubleshooting

Permission denied when running the pod

Problem

FATAL [org.keycloak.services] (ServerService Thread Pool -- 58) Error during startup: java.lang.RuntimeException: java.io.FileNotFoundException: /tmp/trikora-realm.json (Permission denied)

Cause
The pod has not enough permissions for accessing the realm.json file.

Solution
When running the pod, you should add the --security-opt label=disable flag.

Cannot import a realm when running the pod

Problem

07:37:13,702 WARN  [org.keycloak.services] (ServerService Thread Pool -- 68) KC-SERVICES0005: Unable to import realm trikorasolutions from file /tmp/trikora-realm.json.: java.lang.RuntimeException: Script upload is disabled
	at org.keycloak.keycloak-authz-policy-common@15.0.2//org.keycloak.authorization.policy.provider.js.JSPolicyProviderFactory.updatePolicy(JSPolicyProviderFactory.java:125)
	at org.keycloak.keycloak-authz-policy-common@15.0.2//org.keycloak.authorization.policy.provider.js.JSPolicyProviderFactory.onImport(JSPolicyProviderFactory.java:70)

Cause
From keycloak version 7.0.1 onwards, it is not possible to import a realm.json file since it is considered a deprecated way.

Solution
Adding the flag "-e -Dkeycloak.profile.feature.upload_scripts=enabled" does not work, so the only solution is to run podman with an empty master realm and then
import ours from the command line.

Other possible solution to try would be launch keycloak in version 6.0.0 with the realm and then update keycloak.
Or using: https://www.keycloak.org/docs/latest/server_development/#_script_providers