keycloak

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 30, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const ProtocolSAML = "saml"

ProtocolSAML 은 SAML 로 로그인하는 도구의 프로토콜이다. 비어 있으면 OIDC 다.

Variables

This section is empty.

Functions

func NewStackSSOFactory 

func NewStackSSOFactory(kc *KeycloakClient) stackport.SSOProvisionerFactory

NewStackSSOFactory 는 스택별 provisioner 를 만드는 팩토리를 돌려준다.

Types

type BootstrapClientSpec 

type BootstrapClientSpec struct {
	ClientID string
	// Secret 은 호출자가 생성해 넘긴다. Keycloak 이 만든 값을 읽어오지 않는 것은
	// OSS 클라이언트와 같은 이유다 — 생성 주체를 Nullus 로 통일한다.
	Secret string
	// Roles 는 service account 사용자에게 매핑할 realm role 이다.
	// Admin API 호출에는 admin 이 필요하다.
	Roles []string
}

BootstrapClientSpec 은 부트스트랩 service account 클라이언트 정의다.

type KeycloakClient 

type KeycloakClient struct {
	// contains filtered or unexported fields
}

func NewKeycloakClient 

func NewKeycloakClient(baseURL, realm, adminUser, adminPass string) *KeycloakClient

func (*KeycloakClient) DeleteOIDCClient 

func (kc *KeycloakClient) DeleteOIDCClient(ctx context.Context, clientID string) error

func (*KeycloakClient) EnsureBootstrapClient 

func (kc *KeycloakClient) EnsureBootstrapClient(ctx context.Context, spec BootstrapClientSpec) (string, error)

EnsureBootstrapClient 는 부트스트랩 클라이언트를 만들거나 갱신하고 사용할 secret 을 돌려준다. 멱등하다.

func (*KeycloakClient) IssueBootstrapToken 

func (kc *KeycloakClient) IssueBootstrapToken(ctx context.Context, clientID, clientSecret string) (string, error)

IssueBootstrapToken 은 client_credentials grant 로 access token 을 받는다.

이 토큰 자체는 수명이 짧아 별도 폐기가 필요 없다. 실제 폐기 대상은 클라이언트(=지속되는 자격)다.

func (*KeycloakClient) ListClients 

func (kc *KeycloakClient) ListClients(ctx context.Context) ([]OIDCClient, error)

func (*KeycloakClient) RealmSigningCertificate added in v0.6.0 

func (kc *KeycloakClient) RealmSigningCertificate(ctx context.Context) (string, error)

RealmSigningCertificate 는 렐름이 서명에 쓰는 활성 RS256 키의 인증서다(머리말 없는 base64 DER).

Keycloak 은 SAML 응답에 이 키로 서명한다. 키를 회전하면 도구에 넣은 인증서도 바꿔야 한다 — 회전 전 인증서로는 서명 검증이 실패한다.

func (*KeycloakClient) RegisterOIDCClient 

func (kc *KeycloakClient) RegisterOIDCClient(ctx context.Context, clientID string, redirectURIs []string, name string) error

func (*KeycloakClient) RevokeBootstrapClient 

func (kc *KeycloakClient) RevokeBootstrapClient(ctx context.Context, clientID string) error

RevokeBootstrapClient 는 부트스트랩 클라이언트를 삭제한다.

이미 없으면 성공으로 처리한다 — 설치 스크립트가 여러 번 돌아도 안전해야 한다.

func (*KeycloakClient) UpsertOIDCClient 

func (kc *KeycloakClient) UpsertOIDCClient(ctx context.Context, spec OIDCClientSpec) error

UpsertOIDCClient 는 클라이언트를 생성하거나 갱신한다.

갱신이 필수다. 이전 구현은 409 Conflict 를 성공으로 처리해 기존 클라이언트가 그대로 남았고, 그 결과 client secret 을 회전해도 Keycloak 에 반영되지 않아 로그인이 깨졌다. 증상이 "회전 후 SSO 실패" 로만 나타나 추적이 어렵다.

func (*KeycloakClient) UpsertSAMLClient added in v0.6.0 

func (kc *KeycloakClient) UpsertSAMLClient(ctx context.Context, spec SAMLClientSpec) error

UpsertSAMLClient 는 SAML 클라이언트를 만들거나 갱신하고, 도구가 읽을 사용자 속성을 매퍼로 붙인다. 다시 돌려도 같은 결과다.

type OIDCClient 

type OIDCClient struct {
	ID       string `json:"id"`
	ClientID string `json:"clientId"`
	Name     string `json:"name"`
}

type OIDCClientSpec 

type OIDCClientSpec struct {
	ClientID     string
	Name         string
	Secret       string
	RedirectURIs []string
	// ProtocolMappers 는 토큰에 실을 추가 클레임이다. 클라이언트 표현에 실어
	// 보내도 Keycloak 이 갱신에서 무시하므로 전용 엔드포인트로 따로 등록한다.
	ProtocolMappers []OIDCProtocolMapper
	// PKCEMethod 가 비어 있으면 PKCE 속성을 설정하지 않는다.
	// 도구마다 지원 여부가 달라 일괄 적용할 수 없다.
	PKCEMethod string
}

OIDCClientSpec 은 Keycloak 에 등록할 confidential client 의 정의다.

Secret 은 Nullus 가 생성해 push 한다. Keycloak 이 생성한 값을 읽어오지 않는 이유는 OpenBao 가 Source of Truth 여야 하고, Keycloak 이 유실돼도 OpenBao 에서 복원할 수 있어야 하기 때문이다.

type OIDCProtocolMapper 

type OIDCProtocolMapper struct {
	Name       string
	ClaimName  string
	ClaimValue string
}

OIDCProtocolMapper 는 토큰에 고정 클레임을 싣는 매퍼다.

type OIDCProvider 

type OIDCProvider struct{}

func NewOIDCProvider 

func NewOIDCProvider() *OIDCProvider

func (*OIDCProvider) ExtractRoles 

func (p *OIDCProvider) ExtractRoles(claims jwt.MapClaims) []string

func (*OIDCProvider) Name 

func (p *OIDCProvider) Name() string

type SAMLClientSpec added in v0.6.0 

type SAMLClientSpec struct {
	// ClientID 는 SP 의 entity ID 다. 도구 쪽 설정(SonarQube 의 applicationId)과 같아야
	// 한다 — 다르면 Keycloak 이 "Invalid requester" 로 요청을 거부한다.
	ClientID string
	Name     string
	// ACSURL 은 IdP 가 응답을 POST 할 도구의 주소다.
	ACSURL string
}

SAMLClientSpec 은 Keycloak 에 등록할 SAML 클라이언트의 정의다.

SonarQube Community 처럼 SSO 로 SAML 만 받는 도구에 쓴다. OIDC 클라이언트와 달리 client secret 이 없다 — 신뢰는 렐름의 서명 인증서로 맺는다(RealmSigningCertificate).

type SSOProvisioner 

type SSOProvisioner struct {
	// contains filtered or unexported fields
}

func NewSSOProvisioner 

func NewSSOProvisioner(kc *KeycloakClient) *SSOProvisioner

NewSSOProvisioner creates a provisioner using the default access domain ("nullus.local"). Preserves backward-compatible signature.

func NewSSOProvisionerWithDomain 

func NewSSOProvisionerWithDomain(kc *KeycloakClient, accessDomain string) *SSOProvisioner

NewSSOProvisionerWithDomain creates a provisioner with a custom access domain. redirect URIs are built as https://{subdomain}.{accessDomain}{callbackPath}.

func (*SSOProvisioner) ClientIDFor 

func (p *SSOProvisioner) ClientIDFor(stepName string) (string, bool)

ClientIDFor 는 스택 네임스페이스가 적용된 client ID 를 돌려준다.

func (*SSOProvisioner) DeprovisionSSO 

func (p *SSOProvisioner) DeprovisionSSO(ctx context.Context, stepName string) error

func (*SSOProvisioner) ProvisionSSO 

func (p *SSOProvisioner) ProvisionSSO(ctx context.Context, stepName, clientSecret string) error

ProvisionSSO 는 도구의 IdP 클라이언트를 등록/갱신한다.

secret 은 호출자가 넘긴다. Nullus 가 생성해 OpenBao 에 기록한 값을 그대로 Keycloak 에 push 하므로, Keycloak 이 유실돼도 OpenBao 에서 복원할 수 있다. SAML 도구는 secret 이 없어 무시한다.

func (*SSOProvisioner) SAMLSigningCertificate added in v0.6.0 

func (p *SSOProvisioner) SAMLSigningCertificate(ctx context.Context) (string, error)

SAMLSigningCertificate 는 SAML 도구가 응답 서명을 검증할 렐름 인증서다.

func (*SSOProvisioner) SpecFor 

func (p *SSOProvisioner) SpecFor(stepName string) (ToolSSOSpec, bool)

SpecFor 는 도구 스펙을 돌려준다.

func (*SSOProvisioner) ToolSteps 

func (p *SSOProvisioner) ToolSteps() []string

ToolSteps 는 SSO 대상 스텝 이름 목록이다.

func (*SSOProvisioner) UsesClientSecret added in v0.6.0 

func (p *SSOProvisioner) UsesClientSecret(stepName string) bool

UsesClientSecret 은 도구가 client secret 을 갖는 OIDC 클라이언트인지 알려 준다.

SAML 도구와 등록하지 않는 도구는 client secret 이 없다.

func (*SSOProvisioner) WithStackSlug 

func (p *SSOProvisioner) WithStackSlug(slug string) *SSOProvisioner

WithStackSlug 는 client ID 네임스페이싱에 쓸 스택 식별자를 설정한다.

공용 realm 에 여러 스택이 클라이언트를 등록하면 ID 가 충돌한다. 두 스택의 Grafana 가 같은 clientId 를 두고 redirect URI 를 서로 덮어쓰기 때문에, 스택 단위로 네임스페이스를 나눈다.

type StackSSOAdapter 

type StackSSOAdapter struct {
	// contains filtered or unexported fields
}

StackSSOAdapter 는 SSOProvisioner 를 stack 모듈의 포트에 맞춘다.

stack 모듈은 이 어댑터의 구체 타입을 알지 못하고 포트 인터페이스만 본다.

func NewStackSSOAdapter 

func NewStackSSOAdapter(inner *SSOProvisioner) *StackSSOAdapter

func (*StackSSOAdapter) ClientIDFor 

func (a *StackSSOAdapter) ClientIDFor(stepName string) (string, bool)

func (*StackSSOAdapter) Deprovision 

func (a *StackSSOAdapter) Deprovision(ctx context.Context, stepName string) error

func (*StackSSOAdapter) Provision 

func (a *StackSSOAdapter) Provision(ctx context.Context, spec stackport.SSOClientSpec) error

func (*StackSSOAdapter) SAMLSigningCertificate added in v0.6.0 

func (a *StackSSOAdapter) SAMLSigningCertificate(ctx context.Context) (string, error)

func (*StackSSOAdapter) ToolSteps 

func (a *StackSSOAdapter) ToolSteps() []string

func (*StackSSOAdapter) UsesClientSecret added in v0.6.0 

func (a *StackSSOAdapter) UsesClientSecret(stepName string) bool

type ToolSSOSpec 

type ToolSSOSpec struct {
	ClientID     string
	DisplayName  string
	Subdomain    string
	CallbackPath string
	// PKCEMethod 는 도구가 PKCE 를 요구할 때만 채운다.
	// MinIO/ArgoCD 는 PKCE 를 쓰지 않아 비워 둔다.
	PKCEMethod string
	// ProtocolMappers 는 토큰에 실어야 할 추가 클레임이다.
	//
	// 도구가 특정 클레임을 요구할 때만 채운다 — 불필요한 클레임은 토큰만 키운다.
	ProtocolMappers []OIDCProtocolMapper
	// Protocol 은 도구가 IdP 와 쓰는 프로토콜이다. 비어 있으면 OIDC 다.
	//
	// SAML 도구는 client secret 이 없고, CallbackPath 는 ACS(응답을 받는 주소)다.
	Protocol string
}

ToolSSOSpec defines SSO client parameters for an OSS tool.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.