メインコンテンツまでスキップ
プレビュー版
PocketSign Link v2 は現在プレビュー版です。正式提供までに仕様が変更される可能性があります。

KLON SDK のセットアップ

KLON SDK は、PocketSign Link v2 の OIDC 認可フローや Registry API を利用するためのライブラリです。

TypeScript​

パッケージ: @pocketsign/klon-sdk-typescript

KLON IdP と連携するための TypeScript SDK です。oauth4webapi をベースに、KLON 固有のパラメータ（ACR、Authorization Details、Scope）をサポートします。

動作環境​

  • Node.js 18 以降（Web Crypto API が必要）
  • ブラウザ（Web Crypto API 対応）
  • React Native（Expo、customFetch でラッパーが必要）

インストール​

pnpm add @pocketsign/klon-sdk-typescript oauth4webapi

oauth4webapi は peerDependency のため、別途インストールが必要です。

クイックスタート​

Confidential Client（バックエンドでクライアントシークレットを保持する構成）でのセットアップ例です。

import {
  createClient,
  Scopes,
  Resources,
  AcrValues,
  Prompts,
} from "@pocketsign/klon-sdk-typescript";

const client = createClient({
  issuer: "https://id.mock.klon.you",
  clientId: "your-client-id",
  clientSecret: "your-client-secret",
  redirectUri: "https://your-app.example.com/callback",
});

// 1. 認可 URL を生成
const { url, session } = await client.createAuthorizationURL({
  scopes: [Scopes.OPENID, Scopes.PROFILE, Scopes.OFFLINE_ACCESS],
  authorizationDetails: [
    {
      identifiers: [Resources.MERGED_FULL_NAME],
      actions: ["read"],
      required: true,
    },
  ],
  acrValues: [AcrValues.HIGH],
  prompt: [Prompts.CONSENT],
  usePAR: true,
});

// session をセッションストレージに保存してからリダイレクト
// redirect(url.toString())

// 2. コールバックでトークン交換
// code, state はコールバック URL のクエリパラメータ
// const tokenSet = await client.exchangeCode(code, state, session);

// 3. トークンリフレッシュ
// const newTokenSet = await client.refreshToken(tokenSet.refreshToken);

clientSecret を省略すると Public Client として動作します。シークレットを安全に保持できないクライアント（SPA、ネイティブアプリ等）ではこちらを使用してください。

Go​

パッケージ: github.com/pocketsign/klon-sdk-go

KLON IdP と連携するための Go SDK です。go-oidc と golang.org/x/oauth2 をベースに、KLON 固有のパラメータ（ACR、Authorization Details、Scope）をサポートします。

動作環境​

  • Go 1.22 以降

インストール​

go get github.com/pocketsign/klon-sdk-go

クイックスタート​

Confidential Client（バックエンドでクライアントシークレットを保持する構成）でのセットアップ例です。

package main

import (
	"context"
	"fmt"
	"log"

	klon "github.com/pocketsign/klon-sdk-go"
)

func main() {
	client := klon.NewClient(klon.ClientConfig{
		Issuer:       "https://id.mock.klon.you",
		ClientID:     "your-client-id",
		ClientSecret: "your-client-secret",
		RedirectURI:  "http://localhost:8080/callback",
	})

	// 1. 認可 URL を生成
	boolTrue := true
	authURL, session, err := client.CreateAuthorizationURL(context.Background(), klon.AuthorizeOptions{
		Scopes: []string{klon.ScopeOpenID, klon.ScopeProfile, klon.ScopeOfflineAccess},
		AuthorizationDetails: []klon.AuthorizationDetailInput{
			{
				Identifiers: []string{klon.ResourceMergedFullName},
				Actions:     []klon.ResourceAction{klon.ResourceActionRead},
				Required:    &boolTrue,
			},
		},
		AcrValues: []string{klon.AcrHigh},
		Prompt:    []string{klon.PromptConsent},
		UsePAR:    true,
	})
	if err != nil {
		log.Fatal(err)
	}

	// session をセッションストレージに保存してからリダイレクト
	fmt.Println("Redirect to:", authURL)
	_ = session

	// 2. コールバックでトークン交換
	// code, state はコールバック URL のクエリパラメータ
	// tokenSet, err := client.ExchangeCode(ctx, code, state, session)

	// 3. トークンリフレッシュ
	// newTokenSet, err := client.RefreshToken(ctx, tokenSet.RefreshToken)
}

次のステップ​