build(deps): bump @babel/traverse from 7.22.5 to 7.23.2 in /example/frontend

README.md

@@ -4,32 +4,67 @@
 
 ## Usage
 
-在某个神秘的地方注册好 Client，配置 redirect url 并获取 id 和 secret
-
 ```go
 import(
     "github.com/BingyanStudio/oidc-cli/oidc"
 )
 
-var oidcConfig = oidc.Config{
-    ClientID:     "xxxx-xx-xxxxxxx-xxxx",
-    ClientSecret: "xxxxxxxxx",
-    RedirectURL:  "http://example-client.com/callback",
-}
+var oidcCli = oidc.NewClient(
+	&oidc.Config{
+		ClientID:     "CLIENT_ID",
+		ClientSecret: "CLIENT_SECRET",
+		RedirectURL:  "", // Frontend Callback URI
+	},
+)
 
-func OidcCallbackHandler(c echo.Context) error {
-    code := c.QueryParam("code")
-    callbackRes, err := oidc.Callback(oidcConfig, code)
+func UserTokenHandler(c echo.Context) error {
+	code := c.QueryParam("code")
+	tokens, err := oidcCli.RetrieveTokens(code)
     if err != nil {
         ...
     }
 
-    log.Println(callbackRes.IDToken);
-    log.Println(callbackRes.Claims.Subject);
-    log.Println(callbackRes.Claims.Phone);
-
+    log.Println(tokens)
+
     ... // use the token & claims to further authorization
 }
-
 ```
 
+具体用法参见 [example](example)
+
+对于获取的返回值`ResponseTokens`：
+
+- IDToken 的 Claims 已解析至 `ResponseTokens.IDTokenClaims`
+
+  字段如下
+
+  ```go
+  type IDTokenClaims struct {
+  	Issuer    string `json:"iss,omitempty"`
+  	IssuedAt  int64  `json:"iat,omitempty"` // issue time of token
+  	ExpiresAt int64  `json:"exp,omitempty"` // expire time of token
+
+  	Audience  string `json:"aud,omitempty"`     // client id
+  	Nounce    string `json:"nounce,omitempty"`  // ramdom generated by client
+  	ATHash    string `json:"at_hash,omitempty"` // access token hash - for client to validate the access token
+  	Subject   string `json:"sub,omitempty"`     // user id
+  	Role      string `json:"rol,omitempty"`     // role of user
+  	SessionId string `json:"sid,omitempty"`
+
+  	Nickname string `json:"nickname,omitempty"`
+  	Picture  string `json:"picture,omitempty"`
+  	Gender   string `json:"gender,omitempty"`
+
+  	Email         string `json:"email,omitempty"`
+  	EmailVerified bool   `json:"email_verified,omitempty"`
+  	Phone         string `json:"phone,omitempty"`
+  	PhoneVerified bool   `json:"phone_verified,omitempty"`
+  	Group         string `json:"group,omitempty"`
+  }
+  ```
+
+  其中，`sub` 为用户的身份唯一标识符；身份信息的返回取决于  Scope 的设置。
+
+- 库中封装的 Scope 默认为 `[]string{oidc.ScopeOpenID, ScopeProfile, ScopePhone, ScopeEmail}`
+
+- 若要实现用户令牌的刷新，需以适当的方法存储 `ResponseTokens.IDToken` 与 `ResponseTokens.RefreshToken`。当刷新 RP 的 Token 时需确定 IDToken 的有效性。