{"id":13820896,"url":"https://github.com/asatrya/keycloak-traefik-tutorial","last_synced_at":"2025-05-16T10:33:32.650Z","repository":{"id":59195196,"uuid":"220918105","full_name":"asatrya/keycloak-traefik-tutorial","owner":"asatrya","description":"Tutorial how to use Keycloak for authentication and Traefik for API gateway in Microservices architecture","archived":false,"fork":false,"pushed_at":"2019-11-12T04:30:32.000Z","size":7688,"stargazers_count":83,"open_issues_count":2,"forks_count":16,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-19T20:46:52.954Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asatrya.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-11-11T06:44:32.000Z","updated_at":"2024-11-09T11:59:55.000Z","dependencies_parsed_at":"2022-09-13T03:52:01.799Z","dependency_job_id":null,"html_url":"https://github.com/asatrya/keycloak-traefik-tutorial","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asatrya%2Fkeycloak-traefik-tutorial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asatrya%2Fkeycloak-traefik-tutorial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asatrya%2Fkeycloak-traefik-tutorial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asatrya%2Fkeycloak-traefik-tutorial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asatrya","download_url":"https://codeload.github.com/asatrya/keycloak-traefik-tutorial/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254512903,"owners_count":22083478,"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","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":[],"created_at":"2024-08-04T08:01:11.215Z","updated_at":"2025-05-16T10:33:30.545Z","avatar_url":"https://github.com/asatrya.png","language":null,"funding_links":[],"categories":["Others","[🎛️ yunohost](https://github.com/stars/ketsapiwiq/lists/yunohost)"],"sub_categories":[],"readme":"# Keycloak and Traefik Tutorial\n\nThis repo is made based on https://github.com/ibuetler/docker-keycloak-traefik-workshop\n\nFor the sake of this tutorial I have chosen the whoami Docker image we want to add authentication using Keycloak. The whoami application is a tiny Go webserver that prints os information and HTTP request to output. The whoami sample application is not asking for a username and password. You can grab the whoami docker from https://hub.docker.com/r/containous/whoami . The whoami web port is listening on port `80`.\n\n## Test Running Application\n\n```sh\ndocker pull containous/whoami\ndocker run --rm -i -p 80:80 containous/whoami\nCTRL+C will stop the docker\n```\n\nSee the screenshot below how to pull and run and test whoami\n\n![whoami1](images/whoami.png)\n\nOnce you're good, please stop the docker in the same terminal you have executed \"docker run...\" by pressing CTRL-C. This will shutdown the whoami docker service. It must be shutdown for the next steps.\n\n## Step 1: Add three hosts into /etc/hosts\n\nBefore you can test the traefik and whoami daemon, you must add three host entries into the /etc/hosts file. This is, because we do the demo without real DNS names.\n\n```sh\necho \"127.0.0.1       service1.lab.com\" \u003e\u003e /etc/hosts\necho \"127.0.0.1       auth.lab.com\" \u003e\u003e /etc/hosts\necho \"127.0.0.1       traefik.lab.com\" \u003e\u003e /etc/hosts\n```\n\n## Step 2: Run via Docker Compose\n\nThis command will run Traefik, Keycloak (and it's database), Keycloak-gateway, and Whoami service.\n\n```sh\ndocker-compose up -d\n```\n\n## Step 3: Keycloak Setup\n\nFor the sake of this tutorial I use keycloak, an open-source identity provider `IdP` that runs smoothly with docker. If you don’t know keycloak, I encourage you to get into this project. It is the open source version of the RedHat RH-SSO solution.\n\nAfterwards, you should be able to use Firefox to reach your newly created IdP.\n\n* https://auth.lab.com/\n\nTraefik is issuing another self-signed TLS certificate.\n\n![ktls](images/ktls.png)\n\nPlease proceed again and you should see the IdP login prompt.\n\n![keycloakauth](images/keycloakauth.png)\n\n```txt\nusername: admin\npassword: password\n```\n\n![keycloaklogin](images/keycloaklogin.png)\n\nAnd voilà, your keycloak IdP should be up and working\n\n![keycloakok](images/keycloakok.png)\n\n### Create New Realm in Keycloak\n\nFollow steps below:\n\n1. Click \"Add realm\" button on the top left of the admin dashboard. Create a new realm with this data:\n   * Name = `demo-realm`\n1. Click \"Login\" tab, then configure this value:\n   * User registration = `ON`\n1. Click \"Create\"\n\n### Create New Client in Keycloak\n\nFollow steps below:\n\n1. Click on \"Clients\" in the left menu\n1. Click on \"Create\", then configure these values:\n   * Client ID = `demo-client`\n1. Click \"Save\"\n1. Edit this field:\n   * Access Type = `confidential`\n   * Valid Redirect URIs = `https://service1.lab.com/*`\n1. After saving, please click the \"Credentials\" menu item where you will find the secret we need for keycloak-gatekeeper. Copy the Secret as you need it later when configuring `keycloak-gatekeeper`\n\n### Create Client Audience and Scope\n\nWith the new Keycloak software, a user must be assigned to a valid audience and scope before he or she can use a keycloak enabled service. Thus, let's configure the audience and scope.\n\nFollow steps below:\n\n1. Click on \"Client Scopes\" in the left menu and press \"Create\"\n1. Use this data:\n   * Name = `demo-scopes`\n1. Click \"save\"\n1. Click on \"Mappers\" tab and click \"Create\" button. Please configure the mapper the same as in the list below.\n   * Name = `demo-client-mapper`\n   * Mapper Type = `Audience`\n   * Included Client Audience = `demo-client`\n   * Add to ID token = `ON`\n   * Add to access token = `ON`\n\n### Apply Mapper to Client\n\nLast, you must apply the newly created mapper to your `demo-client` client configuration.\n\nFollow steps below:\n\n1. Click on \"Clients\" in the left menu\n1. Click \"Edit\" button next to `demo-client`\n1. Click \"Client Scopes\" tab\n1. On \"Default Client Scopes\" section, select `demo-scopes` on \"Available Client Scopes\" list and click \"Add selected\" button so that it will move to \"Assigned Default Client Scopes\" list\n\nNow you have successfully finished the keycloak configuration for the new client application.\n\n### Testing User Self-Registration\n\nPlease start in Firefox a \"New Private Window\" and connect to the following URL\n\nhttps://auth.lab.com/auth/realms/demo-realm/account\n\n\n![kc11](images/kc11.png)\n\nPlease register a new account\n\n![kc12](images/kc12.png)\n\nEnter your data here\n\n![kc13](images/kc13.png)\n\nUse your Firefox instance where you are logged-in as `admin` and check if the user has been created. \n\nPS: you can setup the user directly within keycloak, if you want. This steps were more to say: \"hey, users can self-register in keycloak\"\n\n![kc14](images/kc14.png)\n\n## Step 4: Keycloak Gatekeeper Setup\n\n### Configure Client Secret\n\nPlease configure your keycloak-gatekeeper with your client secret.\n\n```sh\nnano keycloak-gatekeeper.conf\n```\n\nPlease specify:\n\n* discovery-url: https://auth.lab.com/auth/realms/demo-realm\n* client-id: `demo-client`\n* client-secret: `\u003cyour-client-secret\u003e`\n* redirection-url: https://service1.lab.com\n* upstream-url: http://service_1:80/\n\nIf you don't remember, the client secret comes from the client configuration tab. Copy your value from there.\n\n## Step 5: Refresh `keycloak-gatekeeper` Service\n\nThe `keycloak-gatekeeper` needs to read new configuration file. So, we have to restart the service using this command\n\n```sh\ndocker-compose restart keycloak-gatekeeper\n```\n\n## Step 6: Testing whoami via traefik\n\nOk, then let's see how it works using the browser.\n\nPlease open Firefox and point your browser to https://service1.lab.com\n\nFollow registration step and then login using the new username and password.\n\nYou can see the `whoami` service is running and also displaying the token information.\n\n![whoami_authenticated](images/whoami_authenticated.png)\n\n## Step 7: Authenticate Using API Endpoint\n\nUse Postman and make this request\n\n```curl\ncurl -X POST \\\n  https://auth.lab.com/auth/realms/demo-realm/protocol/openid-connect/token \\\n  -H 'Accept: */*' \\\n  -H 'Accept-Encoding: gzip, deflate' \\\n  -H 'Cache-Control: no-cache' \\\n  -H 'Connection: keep-alive' \\\n  -H 'Content-Length: 127' \\\n  -H 'Content-Type: application/x-www-form-urlencoded' \\\n  -H 'Host: auth.lab.com' \\\n  -H 'Postman-Token: 24099870-cba6-41a8-8d85-dde5408faa2b,963f8ac0-23e1-430d-b69a-aadf452959bb' \\\n  -H 'User-Agent: PostmanRuntime/7.19.0' \\\n  -H 'cache-control: no-cache' \\\n  -d 'client_id=demo-client\u0026grant_type=password\u0026username=asatrya\u0026password=password\u0026client_secret=2a3d0e8d-d605-49ce-b65d-c244399d15e3'\n```\n\nYou will get `access_token` as the response. Copy this token as you will need in next steps.\n\n## Step 8: Access Service Using Endpoint API\n\nUse Postman to make this request:\n\n```curl\ncurl -X GET \\\n  https://service1.lab.com \\\n  -H 'Accept: */*' \\\n  -H 'Accept-Encoding: gzip, deflate' \\\n  -H 'Authorization: Bearer YOUR-ACCESS-TOKEN' \\\n  -H 'Cache-Control: no-cache' \\\n  -H 'Connection: keep-alive' \\\n  -H 'Host: service1.lab.com' \\\n  -H 'Postman-Token: e77b0a50-42df-4503-9d34-34262f1bc61d,6547e1d8-4af4-455f-a72d-dcbe3ae6c5b7' \\\n  -H 'User-Agent: PostmanRuntime/7.19.0' \\\n  -H 'cache-control: no-cache'\n```\n\n## Debugging Notes\n\n### Accees to Keycloak Dabatabse\n\nUse this credentials to access\n\n* Host: `auth.lab.com`\n* Port: 5432\n* Database: `keycloak`\n* User: `keycloak`\n* Password: `password`\n\n## THE END\n\nAfter this tutorial you should have an application (whoami) that comes without authentication and authorization secured using traefik, keycloak and keycloak-gateeeper. The steps taken in this tutorial hopefully have guided you to the end - to a working setup.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasatrya%2Fkeycloak-traefik-tutorial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasatrya%2Fkeycloak-traefik-tutorial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasatrya%2Fkeycloak-traefik-tutorial/lists"}