{"id":30047699,"url":"https://github.com/tmax-cloud/hyperauth_v2","last_synced_at":"2025-08-07T09:57:52.157Z","repository":{"id":219898870,"uuid":"750207744","full_name":"tmax-cloud/hyperauth_v2","owner":"tmax-cloud","description":"HyperAuth based on keycloak 23.0.6","archived":false,"fork":false,"pushed_at":"2024-06-19T02:41:28.000Z","size":20346,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-19T10:10:07.560Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/tmax-cloud.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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":"2024-01-30T07:36:46.000Z","updated_at":"2024-11-24T18:35:17.000Z","dependencies_parsed_at":"2024-06-19T09:59:49.598Z","dependency_job_id":null,"html_url":"https://github.com/tmax-cloud/hyperauth_v2","commit_stats":null,"previous_names":["tmax-cloud/hyperauth-18"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/tmax-cloud/hyperauth_v2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmax-cloud%2Fhyperauth_v2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmax-cloud%2Fhyperauth_v2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmax-cloud%2Fhyperauth_v2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmax-cloud%2Fhyperauth_v2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tmax-cloud","download_url":"https://codeload.github.com/tmax-cloud/hyperauth_v2/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmax-cloud%2Fhyperauth_v2/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269236777,"owners_count":24383241,"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-08-07T02:00:09.698Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","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":[],"created_at":"2025-08-07T09:57:28.168Z","updated_at":"2025-08-07T09:57:52.130Z","avatar_url":"https://github.com/tmax-cloud.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HyperAuth v2 설치 가이드\n## 개요\n* Hyperauth v2\n  * Based on Keycloak 23.0.6 (2024.02.06 기준)\n## 구성 요소 및 버전\n* hyperauth\n    * [hyperregistry.tmaxclouod.org/hyperauth/hyperauth:b2.x.x](https://hyperregistry.tmaxcloud.org/harbor/projects/20/repositories/hyperauth)\n* postgres\n    * postgres:14-alpine\n\n\n## 설치 가이드  \n\n### Step 1. 초기화 작업 및 yaml 수정\n* 목적 : `HyperAuth 구축을 위한 초기화 작업, Secret생성 및 DB 구축, Yaml 버전 수정`\n* 생성 순서 :\n   * [1.initialization.yaml](manifest/1.initialization.yaml) 실행 `ex) kubectl apply -f 1.initialization.yaml`)\n* 비고 : 아래 명령어 수행 후, Postgre Admin 접속 확인\n```bash\n    $ kubectl exec -it $(kubectl get pods -n hyperauth | grep postgre | cut -d ' ' -f1) -n hyperauth -- bash\n    $ psql -U keycloak keycloak\n ```\n\n### Step 2. SSL 인증서 생성\n* 목적 : `HTTPS 인증을 위한 인증서, kafka와의 통신을 위한 keystore, truststore를 생성하고 secret으로 변환`\n* 생성 순서 :\n  * cert-manager가 설치되어 있고, tmaxcloud-issuer (ClusterIssuer) 가 생성되어 있다고 가정한다.\n    * cert-manager 설치는 https://cert-manager.io/docs/installation\n    * 생성이 안되어 있는 경우, [tmaxcloud-issuer.yaml](manifest/tmaxcloud-issuer.yaml) 실행 `ex) kubectl apply -f tmaxcloud-issuer.yaml`)\n  * [hyperauth_certs.yaml](manifest/hyperauth_certs.yaml) 의 변수를 상황에 맞게 치환한다. 안쓰는 변수 부분은 지워준다.\n    * Hyperauth\n      * Hyperauth를 IP로 노출하는 경우, {HYPERAUTH_EXTERNAL_IP} 세팅, dnsName 부분 전체 삭제\n      * Hyperauth를 DNS로 노출하는 경우, {HYPERAUTH_EXTERNAL_DNS} 세팅, ipAddresses 부분 전체 삭제\n  *  [hyperauth_certs.yaml](manifest/hyperauth_certs.yaml) 실행 `ex) kubectl apply -f hyperauth_certs.yaml`)\n  *  Hyperauth Namespace에 hyperauth-https-secret이 생성된걸 확인한다.\n```bash\n    $ kubectl get secrets -n hyperauth\n ``` \t \t  \t\t \t\n \t* hyperauth-https-secret으로 부터 root-ca, hyperauth 인증서를 추출해서 kubernetes pki 에 위치한다.\n```bash\n    $ kubectl get secret hyperauth-https-secret -n hyperauth -o jsonpath=\"{['data']['tls\\.crt']}\" | base64 -d \u003e ./hyperauth.crt\n    $ kubectl get secret hyperauth-https-secret -n hyperauth -o jsonpath=\"{['data']['ca\\.crt']}\" | base64 -d \u003e ./hypercloud-root-ca.crt\n    $ cp ./hyperauth.crt /etc/kubernetes/pki/hyperauth.crt\n    $ cp ./hypercloud-root-ca.crt /etc/kubernetes/pki/hypercloud-root-ca.crt\n ``` \n* 비고 :\n  * Kubernetes Master가 다중화 된 경우, hypercloud-root-ca.crt, hyperauth.crt를 각 Master 노드들의 /etc/kubernetes/pki/hypercloud-root-ca.crt, /etc/kubernetes/pki/hyperauth.crt 로 cp\n\n### Step 3. HyperAuth Deployment 배포\n* 목적 : `HyperAuth 설치`\n  * 생성 순서 : \n    * External-OIDC-provider 또는 외부 인증자와의 mTLS를 사용하지 않을 시, env에서 아래와 같은 주석을 가진 truststore/keystore 관련 설정을 삭제\n    ```yaml\n    # Enable If use External-oidc-provider or use mTLS (for initech)\n    ```\n  * [2.hyperauth_deployment.yaml](manifest/2.hyperauth_deployment.yaml) 실행 `ex) kubectl apply -f 2.hyperauth_deployment.yaml`\n  * HyperAuth Admin Console에 접속 확인\n    * `kubectl get svc hyperauth -n hyperauth` 명령어로 IP 확인\n    * 계정 : admin/admin\n* 비고 :\n  * K8s admin 기본 계정 정보 : hc-admin@tmax.co.kr/Tmaxadmin1!\n  * HyperAuth User 메뉴에서 비밀번호는 변경 가능, ID를 위해서는 clusterrole도 변경 필요\n\n### Step 4. Client 등록\n* 목적 : `HyperAuth 와 연동할 Client 등록`\n  * 생성된 Client에서 사용하는 Credential로 Client에 client_secret을 등록  \n  * Step 5에서 import한 초기 설정파일에는 다음과 같은 client들이 기 생성되어있다. \n    * hypercloud5, hyperregistry, gitlab, argocd, grafana\n  * 해당 client module의 install guide에 따라서 oidc 연동을 수행한다.\n    * hyperauth v2 에서는 oidc 연동 url이 다음과 같이 변경됨.\n      * auth url : {hyperauth-external-dns}__/realms/tmax/protocol/openid-connect/auth__\n      * token url : {hyperauth-external-dns}__/realms/tmax/protocol/openid-connect/token__\n      * userinfo url : hyperauth-external-dns}__/realms/tmax/protocol/openid-connect/userinfo__ \n    * client 별로 생성된 credential을 사용하여 oidc 연동을 수행한다.\n\n## 기타\n### Ingress를 사용해서 hyperauth를 노출하려고 하는 경우\n* hyperauth_traefik_ingress.yaml 에서 host 및 hosts를 환경에 맞는 dns로 수정하고 apply한다.\n* 모든 마스터 노드에 관해서 self-signed 인증서의 경우, os의 ca store에 등록하는 과정을 거쳐야 k8s가 공인 인증서로 써 신뢰한다.\n  * hypercloud-root-ca.crt, hyperauth.crt를 /etc/pki/ca-trust/source/anchors/ 밑에 복사한다. (centOS 기준)\n  * update-ca-trust\n \n### External-OIDC-Provider 사용\n* 목적 : `External-OIDC-Provider 연동 또는 외부 인증자와의 mTLS 통신을 위한 keystore, truststore를 생성하고 secret으로 변환, truststore/keystore는 pkcs12 로 생성한다`\n* 생성 순서 :\n  1. [Truststore]\n     * External-OIDC-Provider : Provider가 기 설치되어있어야 하며, 설치를 통해 생성된 external-oidc-provider-https-secret의 truststore.p12를 이용한다. \n     * 기타 외부 인증 서버 : 인증서버의 truststore.p12를 사용한다.\n  2. [keystore]\n     * Step 2.SSL 인증서 생성 에서 생성한 hyperauth.crt를 이용하여 keystore.p12를 생성한다.\n     ```bash\n         $  keytool -importcert -file hyperauth.crt -keystore keystore.p12 -alias hyperauth_keystore\n     ```\n     * keystore 생성 시 비밀번호를 입력하게 되는데, 해당 비밀번호를 기억해둔다.\n     * 생성된 keystore.p12를 secret으로 변환한다.\n     ```bash  \n         $  kubectl create secret generic hyperauth-keystore -n hyperauth --from-file=keystore.p12 \n     ```\n  3. 2.Deployment에 mTLS 설정\n      * 2에서 생성한 keystore의 비밀번호를 env로 설정\n    ```yaml\n      - name: KC_HTTPS_KEY_STORE_PASSWORD\n        value: \"keystore_password\"\n    ```\n    \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmax-cloud%2Fhyperauth_v2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftmax-cloud%2Fhyperauth_v2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmax-cloud%2Fhyperauth_v2/lists"}