為你的 Go 網頁應用程式新增驗證 (Authentication)

本指南將向你展示如何將 Logto 整合到你的 Go 網頁應用程式中。

提示:

以下示範基於 Gin Web Framework 建立。你也可以依照相同步驟，將 Logto 整合至其他框架。
Go 範例專案可於我們的 Go SDK 儲存庫取得。

先決條件

一個 Logto Cloud 帳戶或自行託管的 Logto。
已建立的 Logto 傳統網頁應用程式。

安裝

在專案根目錄執行：

# 安裝存取預定義值與型別的核心套件
go get github.com/logto-io/go/v2/core

# 安裝與 Logto 互動的 client 套件
go get github.com/logto-io/go/v2/client

將 github.com/logto-io/go/v2/core 與 github.com/logto-io/go/v2/client 套件加入你的應用程式程式碼中：

main.go
// main.go
package main

import (
	"github.com/gin-gonic/gin"
	// 加入相依套件
	"github.com/logto-io/go/v2/core"
	"github.com/logto-io/go/v2/client"
)

func main() {
	router := gin.Default()
	router.GET("/", func(c *gin.Context) {
		c.String(200, "Hello Logto!")
	})
	router.Run(":3000")
}

整合

建立會話儲存

在傳統的網頁應用程式中，使用者驗證 (Authentication) 資訊通常會儲存在使用者的 Session 中。

Logto SDK 提供了一個 Storage 介面，你可以根據自己的網頁框架實作一個 Storage 適配器，讓 Logto SDK 能將使用者驗證 (Authentication) 資訊存放於 Session。

備註:

我們不建議使用基於 Cookie 的 Session，因為 Logto 儲存的使用者驗證 (Authentication) 資訊可能超過 Cookie 的大小限制。本範例採用記憶體型 Session。實際生產環境中，你可以根據需求選擇 Redis、MongoDB 等技術來儲存 Session。

Logto SDK 中的 Storage 型別如下：

storage.go
package client

type Storage interface {
	GetItem(key string) string
	SetItem(key, value string)
}

我們以 github.com/gin-contrib/sessions 中介軟體為例，說明這個流程。

將中介軟體套用到應用程式中，這樣就能在路由處理器中透過請求上下文取得使用者 Session：

main.go
package main

import (
	"github.com/gin-contrib/sessions"
	"github.com/gin-contrib/sessions/memstore"
	"github.com/gin-gonic/gin"
	"github.com/logto-io/go/v2/client"
)

func main() {
	router := gin.Default()

	// 本範例使用記憶體型 Session
	store := memstore.NewStore([]byte("your session secret"))
	router.Use(sessions.Sessions("logto-session", store))

	router.GET("/", func(ctx *gin.Context) {
		// 取得使用者 Session
		session := sessions.Default(ctx)
		// ...
		ctx.String(200, "Hello Logto!")
	})
	router.Run(":3000")
}

建立 session_storage.go 檔案，定義 SessionStorage 並實作 Logto SDK 的 Storage 介面：

session_storage.go
package main

import (
	"github.com/gin-contrib/sessions"
)

type SessionStorage struct {
	session sessions.Session
}

func (storage *SessionStorage) GetItem(key string) string {
	value := storage.session.Get(key)
	if value == nil {
		return ""
	}
	return value.(string)
}

func (storage *SessionStorage) SetItem(key, value string) {
	storage.session.Set(key, value)
	storage.session.Save()
}

現在，在路由處理器中，你可以為 Logto 建立一個 Session Storage：

session := sessions.Default(ctx)
sessionStorage := &SessionStorage{session: session}

初始化 LogtoClient

首先，建立一個 Logto 配置：

main.go
func main() {
	// ...
	logtoConfig := &client.LogtoConfig{
		Endpoint:  "<your-logto-endpoint>", // 例如 http://localhost:3001
		AppId:     "<your-application-id>",
		AppSecret: "<your-application-secret>",
	}
	// ...
}

提示:

你可以在管理控制台的應用程式詳細資訊頁面找到並複製「App Secret」：

接著，你可以為每個使用者請求使用上述的 Logto 配置建立一個 LogtoClient：

main.go
func main() {
	// ...

	router.GET("/", func(ctx *gin.Context) {
		// 建立 LogtoClient
		session := sessions.Default(ctx)
		logtoClient := client.NewLogtoClient(
			logtoConfig,
			&SessionStorage{session: session},
		)

		// 使用 Logto 控制首頁內容
		authState := "你尚未登入此網站。:("

		if logtoClient.IsAuthenticated() {
			authState = "你已登入此網站！:)"
		}

		homePage := `<h1>Hello Logto</h1>` +
			"<div>" + authState + "</div>"

		ctx.Data(http.StatusOK, "text/html; charset=utf-8", []byte(homePage))
	})

	// ...
}

配置你的應用程式

在進入細節之前，這裡先快速說明一下終端使用者的體驗。登入流程可簡化如下：

你的應用程式呼叫登入方法。
使用者被重新導向至 Logto 登入頁面。對於原生應用程式，會開啟系統瀏覽器。
使用者登入後，會被重新導向回你的應用程式（設定為 redirect URI）。

此驗證流程遵循 OpenID Connect (OIDC) 協議，Logto 強制執行嚴格的安全措施以保護使用者登入。
如果你有多個應用程式，可以使用相同的身分提供者 (IdP, Identity provider)（Logto）。一旦使用者登入其中一個應用程式，Logto 將在使用者訪問另一個應用程式時自動完成登入流程。

欲了解更多關於基於重導登入的原理和優勢，請參閱 Logto 登入體驗解析。

備註:

在以下的程式碼片段中，我們假設你的應用程式運行在 http://localhost:3000/。

配置重定向 URI

切換到 Logto Console 的應用程式詳細資訊頁面。新增一個重定向 URI http://localhost:3000/callback。

就像登入一樣，使用者應被重定向到 Logto 以登出共享會話。完成後，將使用者重定向回你的網站會很不錯。例如，將 http://localhost:3000/ 新增為登出後重定向 URI 區段。

然後點擊「儲存」以保存更改。

處理重定向

當使用者在 Logto 登入頁面成功登入後，Logto 會將使用者重定向到 Redirect URI。

由於重定向 URI 是 http://localhost:3000/callback，我們需要新增 /callback 路由來處理登入後的回調。

main.go
func main() {
	// ...

	// 新增路由以處理登入回調請求
	router.GET("/callback", func(ctx *gin.Context) {
		session := sessions.Default(ctx)
		logtoClient := client.NewLogtoClient(
			logtoConfig,
			&SessionStorage{session: session},
		)

		// 登入回調請求由 Logto 處理
		err := logtoClient.HandleSignInCallback(ctx.Request)
		if err != nil {
			ctx.String(http.StatusInternalServerError, err.Error())
			return
		}

		// 跳轉到開發者指定的頁面。
		// 此範例將使用者帶回首頁。
		ctx.Redirect(http.StatusTemporaryRedirect, "/")
	})

	// ...
}

在設定好 redirect URI 後，我們新增一個 sign-in 路由來處理登入請求，並在首頁新增一個登入連結：

main.go
func main() {
	// ...

	// 在首頁新增一個連結來執行登入請求
	router.GET("/", func(ctx *gin.Context) {
		// ...
		homePage := `<h1>Hello Logto</h1>` +
			"<div>" + authState + "</div>" +
			// 新增連結
			`<div><a href="/sign-in">Sign In</a></div>`

		ctx.Data(http.StatusOK, "text/html; charset=utf-8", []byte(homePage))
	})

	// 新增一個路由來處理登入請求
	router.GET("/sign-in", func(ctx *gin.Context) {
		session := sessions.Default(ctx)
		logtoClient := client.NewLogtoClient(
			logtoConfig,
			&SessionStorage{session: session},
		)

		// 登入請求由 Logto 處理。
		// 使用者登入後將被重定向到 Redirect URI。
		signInUri, err := logtoClient.SignIn("http://localhost:3000/callback")
		if err != nil {
			ctx.String(http.StatusInternalServerError, err.Error())
			return
		}

		// 將使用者重定向到 Logto 登入頁面。
		ctx.Redirect(http.StatusTemporaryRedirect, signInUri)
	})

	// ...
}

現在，當你的使用者訪問 http://localhost:3000/sign-in 時，將會被重定向到 Logto 登入頁面。

實作登出路由

類似於登入流程，當使用者登出時，Logto 會將使用者重定向到登出後重定向的 URI。

現在，讓我們新增 sign-out 路由來處理登出請求，並在首頁新增一個登出連結：

main.go
func main() {
	// ...

	// 在首頁新增一個連結以執行登出請求
	router.GET("/", func(ctx *gin.Context) {
		// ...
		homePage := `<h1>Hello Logto</h1>` +
			"<div>" + authState + "</div>" +
			`<div><a href="/sign-in">Sign In</a></div>` +
			// 新增連結
			`<div><a href="/sign-out">Sign Out</a></div>`

		ctx.Data(http.StatusOK, "text/html; charset=utf-8", []byte(homePage))
	})

	// 新增一個路由來處理登出請求
	router.GET("/sign-out", func(ctx *gin.Context) {
		session := sessions.Default(ctx)
		logtoClient := client.NewLogtoClient(
			logtoConfig,
			&SessionStorage{session: session},
		)

		// 登出請求由 Logto 處理。
		// 使用者登出後將被重定向到登出後重定向的 URI。
		signOutUri, signOutErr := logtoClient.SignOut("http://localhost:3000")

		if signOutErr != nil {
			ctx.String(http.StatusOK, signOutErr.Error())
			return
		}

		ctx.Redirect(http.StatusTemporaryRedirect, signOutUri)
	})

	// ...
}

當使用者發出登出請求後，Logto 會清除會話中的所有使用者驗證 (Authentication) 資訊。

檢查點：測試你的應用程式

現在，你可以測試你的應用程式：

執行你的應用程式，你會看到登入按鈕。
點擊登入按鈕，SDK 會初始化登入流程並將你重定向到 Logto 登入頁面。
登入後，你將被重定向回應用程式並看到登出按鈕。
點擊登出按鈕以清除權杖存儲並登出。

獲取使用者資訊

顯示使用者資訊

要顯示使用者的資訊，你可以使用 client.GetIdTokenClaims 方法。例如，新增一個路由：

main.go
func main() {
    //...

    router.GET("/user-id-token-claims", func(ctx *gin.Context) {
      session := sessions.Default(ctx)
      logtoClient := client.NewLogtoClient(logtoConfig, &SessionStorage{session: session})

      idTokenClaims, err := logtoClient.GetIdTokenClaims()

      if err != nil {
        ctx.String(http.StatusOK, err.Error())
      }

      ctx.JSON(http.StatusOK, idTokenClaims)
    })
}

請求額外的宣告 (Claims)

你可能會發現從 client.GetIdTokenClaims() 返回的物件中缺少一些使用者資訊。這是因為 OAuth 2.0 和 OpenID Connect (OIDC) 的設計遵循最小權限原則 (PoLP, Principle of Least Privilege)，而 Logto 是基於這些標準構建的。

預設情況下，僅返回有限的宣告 (Claims)。如果你需要更多資訊，可以請求額外的權限範圍 (Scopes) 以存取更多宣告。

資訊:

「宣告 (Claim)」是對主體所做的斷言；「權限範圍 (Scope)」是一組宣告。在目前的情況下，宣告是關於使用者的一部分資訊。

以下是權限範圍與宣告關係的非規範性範例：

提示:

「sub」宣告表示「主體 (Subject)」，即使用者的唯一識別符（例如使用者 ID）。

Logto SDK 將始終請求三個權限範圍：openid、profile 和 offline_access。

要請求額外的權限範圍 (Scopes)，你可以將權限範圍傳遞給 LogtoConfig 物件。例如：

main.go
logtoConfig := &client.LogtoConfig{
  // ...其他配置
  Scopes: []string{"email", "phone"},
}

然後你可以在 client.GetIdTokenClaims() 的返回值中訪問額外的宣告 (Claims)：

idTokenClaims, error := client.GetIdTokenClaims()
// 現在你可以訪問額外的宣告 `claims.email`、`claims.phone` 等。

需要網路請求的宣告 (Claims)

為了防止 ID 權杖 (ID token) 膨脹，某些宣告 (Claims) 需要透過網路請求來獲取。例如，即使在權限範圍 (Scopes) 中請求了 custom_data 宣告，它也不會包含在使用者物件中。要存取這些宣告，你可以使用 client.FetchUserInfo() 方法：

userInfo, error := client.FetchUserInfo()
// 現在你可以訪問宣告 `userInfo.custom_data`

此方法將透過請求 userinfo 端點來獲取使用者資訊。要了解更多可用的權限範圍 (Scopes) 和宣告 (Claims)，請參閱權限範圍 (Scopes) 和宣告 (Claims) 部分。

權限範圍 (Scopes) 和宣告 (Claims)

Logto 採用 OIDC 權限範圍 (Scopes) 與宣告 (Claims) 慣例來定義從 ID 權杖 (ID token) 及 OIDC userinfo 端點取得使用者資訊時的權限範圍與宣告。無論「權限範圍 (Scope)」還是「宣告 (Claim)」，皆為 OAuth 2.0 與 OpenID Connect (OIDC) 規範中的術語。

對於標準 OIDC 宣告 (Claims)，其是否包含於 ID 權杖 (ID token) 內，完全取決於所請求的權限範圍 (Scopes)。擴充宣告（如 custom_data 與 organizations）則可透過自訂 ID 權杖 (Custom ID token) 設定，額外配置於 ID 權杖中。

以下是支援的權限範圍 (Scopes) 及對應的宣告 (Claims) 清單：

標準 OIDC 權限範圍 (Scopes)

openid（預設）

Claim name	Type	Description
sub	`string`	使用者的唯一識別符 (The unique identifier of the user)

profile（預設）

Claim name	Type	Description
name	`string`	使用者全名 (The full name of the user)
username	`string`	使用者名稱 (The username of the user)
picture	`string`	終端使用者大頭貼的 URL。此 URL 必須指向圖片檔案（如 PNG、JPEG 或 GIF），而非包含圖片的網頁。請注意，此 URL 應明確指向適合描述終端使用者的個人照片，而非任意由終端使用者拍攝的照片。(URL of the End-User's profile picture. This URL MUST refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image. Note that this URL SHOULD specifically reference a profile photo of the End-User suitable for displaying when describing the End-User, rather than an arbitrary photo taken by the End-User.)
created_at	`number`	終端使用者建立時間。以自 Unix epoch（1970-01-01T00:00:00Z）以來的毫秒數表示。(Time the End-User was created. The time is represented as the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).)
updated_at	`number`	終端使用者資訊最後更新時間。以自 Unix epoch（1970-01-01T00:00:00Z）以來的毫秒數表示。(Time the End-User's information was last updated. The time is represented as the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).)

其他標準宣告 (Standard claims) 包含 family_name、given_name、middle_name、nickname、preferred_username、profile、website、gender、birthdate、zoneinfo 及 locale 也會包含在 profile 權限範圍內，無需額外請求 userinfo endpoint。與上表宣告不同的是，這些宣告僅在其值不為空時才會回傳，而上表宣告若值為空則會回傳 null。

備註:

與標準宣告不同，created_at 與 updated_at 宣告使用毫秒而非秒為單位。

email

Claim name	Type	Description
email	`string`	使用者的電子郵件地址 (The email address of the user)
email_verified	`boolean`	電子郵件地址是否已驗證 (Whether the email address has been verified)

phone

Claim name	Type	Description
phone_number	`string`	使用者的電話號碼 (The phone number of the user)
phone_number_verified	`boolean`	電話號碼是否已驗證 (Whether the phone number has been verified)

address

請參閱 OpenID Connect Core 1.0 以瞭解 address 宣告的詳細資訊。

資訊:

標註為 （預設） 的權限範圍 (Scopes) 會由 Logto SDK 自動請求。當請求對應權限範圍時，標準 OIDC 權限範圍下的宣告 (Claims) 會始終包含於 ID 權杖 (ID token) 中，且無法關閉。

擴充權限範圍 (Extended scopes)

以下權限範圍由 Logto 擴充，會透過 userinfo endpoint 回傳宣告 (Claims)。這些宣告也可透過 Console > Custom JWT 設定直接包含於 ID 權杖 (ID token) 中。詳情請參閱自訂 ID 權杖 (Custom ID token)。

custom_data

Claim name	Type	Description	Included in ID token by default
custom_data	`object`	使用者的自訂資料 (The custom data of the user)

identities

Claim name	Type	Description	Included in ID token by default
identities	`object`	使用者的連結身分 (The linked identities of the user)
sso_identities	`array`	使用者的連結 SSO 身分 (The linked SSO identities of the user)

roles

Claim name	Type	Description	Included in ID token by default
roles	`string[]`	使用者的角色 (The roles of the user)	✅

urn:logto:scope:organizations

Claim name	Type	Description	Included in ID token by default
organizations	`string[]`	使用者所屬的組織 ID (The organization IDs the user belongs to)	✅
organization_data	`object[]`	使用者所屬的組織資料 (The organization data the user belongs to)

備註:

這些組織宣告 (Organization claims) 也可在使用不透明權杖 (Opaque token) 時，透過 userinfo endpoint 取得。然而，不透明權杖無法作為組織權杖 (Organization tokens) 來存取組織專屬資源。詳見不透明權杖與組織 (Opaque token and organizations)。

urn:logto:scope:organization_roles

Claim name	Type	Description	Included in ID token by default
organization_roles	`string[]`	使用者所屬組織角色，格式為 `<organization_id>:<role_name>` (The organization roles the user belongs to with the format of `<organization_id>:<role_name>`)	✅

API 資源與組織

我們建議先閱讀 🔐 角色型存取控制 (RBAC, Role-Based Access Control)，以瞭解 Logto RBAC 的基本概念以及如何正確設定 API 資源。

配置 Logto 客戶端

一旦你設定了 API 資源，就可以在應用程式中配置 Logto 時新增它們：

logtoConfig := &client.LogtoConfig{
    // ...other configs
    Resources: []string{"https://shopping.your-app.com/api", "https://store.your-app.com/api"},
}

每個 API 資源都有其自身的權限（權限範圍）。

例如，https://shopping.your-app.com/api 資源具有 shopping:read 和 shopping:write 權限，而 https://store.your-app.com/api 資源具有 store:read 和 store:write 權限。

要請求這些權限，你可以在應用程式中配置 Logto 時新增它們：

logtoConfig := &client.LogtoConfig{
    // ...other configs
    Scopes:    []string{"shopping:read", "shopping:write", "store:read", "store:write"},
    Resources: []string{"https://shopping.your-app.com/api", "https://store.your-app.com/api"},
}

你可能會注意到權限範圍是獨立於 API 資源定義的。這是因為 OAuth 2.0 的資源標示符 (Resource Indicators) 指定請求的最終權限範圍將是所有目標服務中所有權限範圍的笛卡兒積。

因此，在上述情況中，權限範圍可以從 Logto 的定義中簡化，兩個 API 資源都可以擁有 read 和 write 權限範圍而不需要前綴。然後，在 Logto 配置中：

logtoConfig := &client.LogtoConfig{
    // ...other configs
    Scopes:    []string{"read", "write"},
    Resources: []string{"https://shopping.your-app.com/api", "https://store.your-app.com/api"},
}

對於每個 API 資源，它將請求 read 和 write 權限範圍。

備註:

請求未在 API 資源中定義的權限範圍是可以的。例如，即使 API 資源中沒有可用的 email 權限範圍，你也可以請求 email 權限範圍。不可用的權限範圍將被安全地忽略。

成功登入後，Logto 將根據使用者的角色向 API 資源發出適當的權限範圍。

為 API 資源提取存取權杖

要獲取特定 API 資源的存取權杖 (Access token)，你可以使用 GetAccessToken 方法：

accessToken, error := logtoClient.GetAccessToken("https://shopping.your-app.com/api")

此方法將返回一個 JWT 存取權杖 (Access token)，當使用者擁有相關權限時，可以用來存取 API 資源。如果當前快取的存取權杖 (Access token) 已過期，此方法將自動嘗試使用重新整理權杖 (Refresh token) 獲取新的存取權杖 (Access token)。

提取組織權杖

如果你對組織 (Organization) 不熟悉，請閱讀 🏢 組織（多租戶，Multi-tenancy）以開始了解。

在配置 Logto client 時，你需要新增 core.UserScopeOrganizations 權限範圍 (scope)：

logtoConfig := &client.LogtoConfig{
    // ...other configs
    Scopes: []string{core.UserScopeOrganizations},
}

使用者登入後，你可以為使用者獲取組織權杖 (organization token)：

// 將參數替換為有效的組織 (Organization) ID。
// 使用者的有效組織 (Organization) ID 可以在 ID 權杖 (ID token) 宣告 (claim) `organizations` 中找到。
accessToken, error := logtoClient.GetOrganizationToken("organization-id")

// 或
accessTokenClaims, error := logtoClient.GetOrganizationTokenClaims("organization-id")

組織 API 資源 (Organization API resources)

若要取得組織中某個 API 資源的存取權杖 (Access token)，你可以使用 GetAccessTokenWithOptions 方法，並同時傳入 API 資源與組織 ID 作為參數：

accessToken, error := client.GetAccessTokenWithOptions(
  client.GetAccessTokenOptions{
    Resource: 'https://shopping.your-app.com/api',
    OrganizationId: organizationId,
  },
);

延伸閱讀

終端使用者流程：驗證流程、帳號流程與組織流程 (End-user flows: authentication flows, account flows, and organization flows) 設定連接器 (Configure connectors) 授權 (Authorization)

先決條件​

安裝​

整合​

建立會話儲存​

初始化 LogtoClient​

配置你的應用程式​

關於基於重導的登入​

配置重定向 URI​

處理重定向​

實作登入路由​

實作登出路由​

檢查點：測試你的應用程式​

獲取使用者資訊​

顯示使用者資訊​

請求額外的宣告 (Claims)​

需要網路請求的宣告 (Claims)​

權限範圍 (Scopes) 和宣告 (Claims)​

標準 OIDC 權限範圍 (Scopes)​

擴充權限範圍 (Extended scopes)​

API 資源與組織​

配置 Logto 客戶端​

為 API 資源提取存取權杖​

提取組織權杖​

組織 API 資源 (Organization API resources)​

延伸閱讀​