{"id":18429147,"url":"https://github.com/openliberty/sample-keycloak","last_synced_at":"2025-07-21T21:37:35.451Z","repository":{"id":185361664,"uuid":"617557792","full_name":"OpenLiberty/sample-keycloak","owner":"OpenLiberty","description":"Sample app using Open Liberty, Jakarta EE Security, MicroProfile JWT, and Keycloak.","archived":false,"fork":false,"pushed_at":"2023-11-06T21:11:25.000Z","size":99,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-27T23:44:16.957Z","etag":null,"topics":["jakartaee","jwt","keycloak","microprofile","oidc","openliberty"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenLiberty.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-22T16:26:51.000Z","updated_at":"2024-08-07T15:38:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"769edbd9-e5be-40ce-b2d5-7bad2e9a288e","html_url":"https://github.com/OpenLiberty/sample-keycloak","commit_stats":null,"previous_names":["openliberty/sample-keycloak"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/OpenLiberty/sample-keycloak","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLiberty%2Fsample-keycloak","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLiberty%2Fsample-keycloak/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLiberty%2Fsample-keycloak/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLiberty%2Fsample-keycloak/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenLiberty","download_url":"https://codeload.github.com/OpenLiberty/sample-keycloak/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLiberty%2Fsample-keycloak/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266384529,"owners_count":23921069,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-21T11:47:31.412Z","response_time":64,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jakartaee","jwt","keycloak","microprofile","oidc","openliberty"],"created_at":"2024-11-06T05:16:01.612Z","updated_at":"2025-07-21T21:37:35.428Z","avatar_url":"https://github.com/OpenLiberty.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sample App using Jakarta EE Security, MicroProfile JWT, and Keycloak\n\nThis sample app contains a `system` service which has a `GET /api/system/properties/username` endpoint, which returns the `user.name` system property, and a `GET /api/system/properties/os` endpoint, which returns the `os.name` system property. The endpoints are secured with JWT's using the `MicroProfile JWT 2.0` feature. Only users with the `admin` role can access the `GET /api/system/properties/username` endpoint, while users with either the `admin` or `user` role can access the `GET /api/system/properties/os` endpoint. The sample app also contains a `gateway` service whose responsibility is to obtain a JWT access token for the user from `Keycloak` and propagate it to the `system` service. This is accomplished using the `Jakarta EE Security 3.0` feature.\n\n## Starting the application\n\n### Start Keycloak\n\nRun from the root directory:\n\n```\ndocker build -t openliberty-keycloak -f keycloak/Dockerfile .\ndocker run --name openliberty-keycloak -p 8080:8080 -d openliberty-keycloak\n```\n\n### Start the System service\n\nRun from the `src/system` directory:\n\n```\nmvn liberty:dev\n```\n\n### Start the Gateway service\n\nIn another shell instance, run from the `src/gateway` directory:\n\n```\nmvn liberty:dev\n```\n\n## Testing the application\n\n### Users\n\n| Username   | Password   | Role        |\n| ---------- | ---------- | ----------- |\n| alice      | alicepwd   | user        |\n| bob        | bobpwd     | admin, user |\n\n### Testing the username endpoint\n\nVisit the username endpoint at the http://localhost:9090/api/system/properties/username URL. Log in as `bob` to view the `user.name` system property. Logging in as `alice` will result in a `403 Forbidden` response because only users with the `admin` role are allowed to access this endpoint.\n\nLog out of the current user by visiting the logout endpoint at the http://localhost:9090/api/auth/logout URL.\n\n### Testing the os endpoint\n\nVisit the os endpoint at the http://localhost:9090/api/system/properties/os URL. Log in as `bob` or `alice` to view the `os.name` system property.\n\nLog out of the current user by visiting the logout endpoint at the http://localhost:9090/api/auth/logout URL.\n\n## How it works\n\n![Token propagation diagram](/assets/diagram.png)\n\n### Keycloak\n\nKeycloak was used as the OpenId Connect Provider (OP) for this sample app. The `openliberty` realm was created in Keycloak. Inside this realm, the `sample-openliberty-keycloak` client was created which has the valid redirect URI's set to `http://localhost:9090/*`, client authentication enabled, and the `microprofile-jwt` client scope enabled. Additionally, the `admin` and `user` roles were created for this realm. Lastly, the `alice` user was created which has the `user` role and the `bob` user was created which has the `admin` role and the `user` role. Visit the http://localhost:8080/admin/master/console/#/openliberty URL and sign in using the `admin` username and `admin` password to view the `openliberty` realm.\n\nThe Keycloak OP's configuration can found at the http://localhost:8080/realms/openliberty/.well-known/openid-configuration URL.\n\n### System Service\n\nThe `system` service secures its endpoints using MicroProfile JWT. By adding the `@RolesAllowed` annotation to a JAX-RS endpoint, the runtime will check `Authentication` HTTP request header for a Bearer token. The Bearer token must be in JWT format and include the specified role in the annotation in the JWT's `roles` claim in order to access the endpoint.\n\nFor the `/username` endpoint, it requires that the Bearer token's `roles` claim include the `admin` role.\n\n[SystemResource.java](https://github.com/OpenLiberty/sample-keycloak/blob/main/src/system/src/main/java/io/openliberty/guides/system/SystemResource.java#L21-L26)\n```java\n@GET\n@Path(\"/username\")\n@RolesAllowed({ \"admin\" })\npublic String getUsername() {\n    return System.getProperties().getProperty(\"user.name\");\n}\n```\n\nThe following lines in the `microprofile-config.properties` file are required for MicroProfile JWT to validate that the Bearer token was issued from the correct source and has not been tampered with.\n\n[microprofile-config.properties](https://github.com/OpenLiberty/sample-keycloak/blob/main/src/system/src/main/webapp/META-INF/microprofile-config.properties#L1-L2)\n```properties\nmp.jwt.verify.issuer=http://localhost:8080/realms/openliberty\nmp.jwt.verify.publickey.location=http://localhost:8080/realms/openliberty/protocol/openid-connect/certs\n```\n\nThe `mp.jwt.verify.issuer` should match the `issuer` value in the Keycloak OP config. The runtime will validate that the Bearer token's `iss` claim matches the `mp.jwt.verify.issuer` value. The `mp.jwt.verify.publickey.location` should match the `jwks_uri` value in the Keycloak OP config. The runtime will validate the Bearer token's signature with the public key found at the Keycloak OP's JSON Web Key (JWK) Set endpoint.\n\n### Gateway Service\n\nThe `gateway` service is used to obtain a JWT access token from Keycloak and propagates it to the MicroProfile JWT secured `system` service.\n\nFor the `gateway` service, an `@OpenIdAuthenticationMechanismDefinition` is defined which has its `providerURI` set to the Keycloak OP's configuration URL, the `clientID` set to the `sample-openliberty-keycloak` client, and the `clientSecret` set to `sample-openliberty-keycloak`'s client secret. The `redirectToOriginalResource` is set to true, so that the browser will redirect to the original resource request after authentication. The `notifyProvider` is set to true, so that the browser will also redirect to the Keycloak OP's `end_session_endpoint` in the event of a logout. The `@DeclareRoles` annotation declares the `admin` role and the `user` role.\n\n[AuthResource.java](https://github.com/OpenLiberty/sample-keycloak/blob/main/src/gateway/src/main/java/io/openliberty/guides/gateway/auth/AuthResource.java#L27-L33)\n```java\n@OpenIdAuthenticationMechanismDefinition(\n        providerURI = \"http://localhost:8080/realms/openliberty/.well-known/openid-configuration\",\n        clientId = \"sample-openliberty-keycloak\",\n        clientSecret = \"x4fRVAhk49TKDqVlzIt4q9oh8DSWfePt\",\n        redirectToOriginalResource = true,\n        logout = @LogoutDefinition(notifyProvider = true))\n@DeclareRoles({ \"admin\", \"user\" })\n```\n\nNow, adding the `@RolesAllowed` annotation to a JAX-RS endpoint will start a new OpenId Connect (OIDC) authorization code flow. The roles specified in the annotation for the `/username` endpoint in the `gateway` service should match the roles for the `/username` endpoint in the `system` service. If successful, an access token is obtained from the `OpenIdContext` and is propagated to the `system` service as a Bearer token in the `Authorization` header via MicroProfile Rest Client.\n\n[SystemResource.java](https://github.com/OpenLiberty/sample-keycloak/blob/main/src/gateway/src/main/java/io/openliberty/guides/gateway/system/SystemResource.java#L32-L37)\n```java\n@GET\n@Path(\"/username\")\n@RolesAllowed({ \"admin\" })\npublic String getUsername() {\n    return systemService.getUsername(openIdContext.getAccessToken().getToken());\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenliberty%2Fsample-keycloak","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenliberty%2Fsample-keycloak","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenliberty%2Fsample-keycloak/lists"}