Authentication

Natsuneko Laboratory Platform では、 accounts.natsuneko.com から Passkey を登録後、同一ページ「開発者向け」から、アプリケーションを発行することが可能です。アプリケーションを発行後、 RFC 8252 - OAuth 2.0 for Native Apps の要領でアプリケーションからユーザーの認証を行うことが可能です。認証後、アプリケーションはアクセストークン、リフレッシュトークンを保存、使用することで、ユーザーの代わりに操作を行うことが可能です。

まず、 https://accounts.natsuneko.com/authorize をベースとして、 OAuth 2.0 認証 URL を取得します。通常、以下の形式になります：

https://accounts.natsuneko.com/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=read%2Cwrite&response_type=code&code_challenge_method=S256&code_challenge=PKCE_CHALLENGE_CODE&state=STATE

ユーザー認証が完了、かつ認可が完了したら、アプリケーションへとリダイレクトされます。その後、得られた code を元に、次のエンドポイントへ application/x-www-form-urlencoded でデータを送信します：

POST https://api.natsuneko.com/token
Content-Type: application/x-www-form-urlencoded

client_id=CLIENT_ID&code=CODE&code_verifier=CODE_VERIFIER&grant_type=authorization_code&redirect_uri=REDIRECT_URI

レスポンスとして次のデータが得られるので、 access_token および refresh_token を保存してください。

{
  "access_token": "586178bd-37c7-4b4a-be87-911812842be3",
  "refresh_token": "6def193e-3f16-4408-9492-4f5337cbae63",
  "scope": "read write",
  "token_type": "Bearer",
  "expires_at": "2025-02-28T16:51:19.247Z",
  "expires_in": 604800
}

リフレッシュトークンも同様に入手が可能です：

POST https://api.natsuneko.com/token
Content-Type: application/x-www-form-urlencoded

client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

以下は公式 Swift クライアントによる Custom URI Scheme を用いて認証を行う実装例です：

// App.swift
import AuthenticationService
import CatalystSwift
import SwiftUI

@Environment(\.webAuthenticationSession) var webAuthenticationSession

private func authenticate() async throws -> Token {
    let client = CatalystSwift(clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET")
    let redirectUri = "YOUR_REDIRECT_URI"
    let callback = ASWebAuthenticationSession.Callback.customScheme("YOUR_CUSTOM_SCHEME")
    let state = UUID().uuidString
    let pkce = try PKCE()
    let url = try client.oauth.getAuthorizeURL(callback: callback, redirectUri: redirectUri, pkce: pkce, state: state)
    let responseUrl = try await webAuthenticationSession.authenticate(using: url, callback: callback, preferredBrowserSession: .ephemeral, additionalHeaderFields: [:])
    let code = try client.oauth.getAuthorizationCode(from: responseUrl, expectedState: state, expectedRedirectUri: redirectUri)
    
    return try await client.oauth.getAccessToken(using: code, redirectUri: redirectUri, pkce: pkce)
}

同様に、 Swift クライアントによるリフレッシュトークンを用いたアクセストークンの更新例です：

private func refreshTokens() async throws -> Token {
    let client = ...
    let refreshToken = token.refreshToken
    
    return try await client.oauth.refreshAccessToken(using: refreshToken)
}

アクセストークンの有効期限は 604800秒 (約1週間)、リフレッシュトークンの期限はありません。リフレッシュトークンは一度のみ使用可能で、アクセストークンを更新する度に更新が必要です。アクセストークンを入手後、以下のようにリクエストを送信することで API を使用することが可能です。

GET https://api.natsuneko.com/egeria/v1/me
Authorization: Bearer ACCESS_TOKEN

参考文献：

ネイティブアプリOAuthベストプラクティス iOS編

Last modified: 16 3月 2025