auth

Documentation

Index

• Constants
• Variables
• func BuildVerificationURL(baseURL, cliVersion string) string
• func GetValidAccessToken(httpClient *http.Client, opts UATCallOptions) (string, error)
• func MaskToken(token string) string
• func MissingScopes(storedScope string, required []string) []string
• func RemoveStoredToken(appId, userOpenId string) error
• func SetStoredToken(token *StoredUAToken) error
• func TokenStatus(token *StoredUAToken) string
• func VerifyUserToken(ctx context.Context, sdk *lark.Client, accessToken string) error
• type AppRegUserInfo
• type AppRegistrationResponse
  • func RequestAppRegistration(httpClient *http.Client, brand core.LarkBrand, errOut io.Writer) (*AppRegistrationResponse, error)
• type AppRegistrationResult
  • func PollAppRegistration(ctx context.Context, httpClient *http.Client, brand core.LarkBrand, ...) (*AppRegistrationResult, error)
• type DeviceAuthResponse
  • func RequestDeviceAuthorization(httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, ...) (*DeviceAuthResponse, error)
• type DeviceFlowResult
  • func PollDeviceToken(ctx context.Context, httpClient *http.Client, appId, appSecret string, ...) *DeviceFlowResult
• type DeviceFlowTokenData
• type NeedAuthorizationError
  • func (e *NeedAuthorizationError) Error() string
• type OAuthEndpoints
  • func ResolveOAuthEndpoints(brand core.LarkBrand) OAuthEndpoints
• type SecurityPolicyError
  • func (e *SecurityPolicyError) Error() string
  • func (e *SecurityPolicyError) Unwrap() error
• type SecurityPolicyTransport
  • func (t *SecurityPolicyTransport) RoundTrip(req *http.Request) (*http.Response, error)
• type StoredUAToken
  • func GetStoredToken(appId, userOpenId string) *StoredUAToken
• type UATCallOptions
  • func NewUATCallOptions(cfg *core.CliConfig, errOut io.Writer) UATCallOptions
• type UATStatus

Constants

const (
	LarkErrBlockByPolicy        = 21001 // access denied by access control policy
	LarkErrBlockByPolicyTryAuth = 21000 // access denied by access control policy; challenge is required to be completed by user in order to gain access
)

Variables

var RefreshTokenRetryable = map[int]bool{
	output.LarkErrRefreshServerError: true,
}

RefreshTokenRetryable contains error codes that allow one immediate retry. All other refresh errors clear the token immediately.

var TokenRetryCodes = map[int]bool{
	output.LarkErrTokenInvalid: true,
	output.LarkErrTokenExpired: true,
}

TokenRetryCodes contains error codes that allow retry after token refresh.

Functions

func BuildVerificationURL

func BuildVerificationURL(baseURL, cliVersion string) string

BuildVerificationURL appends CLI tracking parameters to the verification URL.

func GetValidAccessToken

func GetValidAccessToken(httpClient *http.Client, opts UATCallOptions) (string, error)

GetValidAccessToken obtains a valid access token for the given user.

func MaskToken

func MaskToken(token string) string

MaskToken masks a token for safe logging.

func MissingScopes

func MissingScopes(storedScope string, required []string) []string

MissingScopes returns the elements of required that are absent from storedScope. storedScope is a space-separated list of granted scope strings (as stored in the token).

func RemoveStoredToken

func RemoveStoredToken(appId, userOpenId string) error

RemoveStoredToken removes a stored UAT.

func SetStoredToken

func SetStoredToken(token *StoredUAToken) error

SetStoredToken persists a UAT.

func TokenStatus

func TokenStatus(token *StoredUAToken) string

TokenStatus determines the freshness of a stored token.

func VerifyUserToken

func VerifyUserToken(ctx context.Context, sdk *lark.Client, accessToken string) error

VerifyUserToken calls /authen/v1/user_info to confirm the token is accepted server-side. Returns nil on success or an error describing why the server rejected the token.

Types

type AppRegUserInfo

type AppRegUserInfo struct {
	OpenID      string
	TenantBrand string // "feishu" or "lark"
}

AppRegUserInfo contains user info returned from app registration.

type AppRegistrationResponse

type AppRegistrationResponse struct {
	DeviceCode              string
	UserCode                string
	VerificationUri         string
	VerificationUriComplete string
	ExpiresIn               int
	Interval                int
}

AppRegistrationResponse is the response from the app registration begin endpoint.

func RequestAppRegistration

func RequestAppRegistration(httpClient *http.Client, brand core.LarkBrand, errOut io.Writer) (*AppRegistrationResponse, error)

RequestAppRegistration initiates the app registration device flow.

type AppRegistrationResult

type AppRegistrationResult struct {
	ClientID     string
	ClientSecret string
	UserInfo     *AppRegUserInfo
}

AppRegistrationResult is the result of a successful app registration poll.

func PollAppRegistration

func PollAppRegistration(ctx context.Context, httpClient *http.Client, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) (*AppRegistrationResult, error)

PollAppRegistration polls the app registration endpoint until the app is created or the flow times out. If the result has ClientSecret == "" and UserInfo.TenantBrand == "lark", the caller should retry with BrandLark to get the secret from accounts.larksuite.com.

type DeviceAuthResponse

type DeviceAuthResponse struct {
	DeviceCode              string `json:"device_code"`
	UserCode                string `json:"user_code"`
	VerificationUri         string `json:"verification_uri"`
	VerificationUriComplete string `json:"verification_uri_complete"`
	ExpiresIn               int    `json:"expires_in"`
	Interval                int    `json:"interval"`
}

DeviceAuthResponse is the response from the device authorization endpoint.

func RequestDeviceAuthorization

func RequestDeviceAuthorization(httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, scope string, errOut io.Writer) (*DeviceAuthResponse, error)

RequestDeviceAuthorization requests a device authorization code.

type DeviceFlowResult

type DeviceFlowResult struct {
	OK      bool
	Token   *DeviceFlowTokenData
	Error   string
	Message string
}

DeviceFlowResult is the result of polling the token endpoint.

func PollDeviceToken

func PollDeviceToken(ctx context.Context, httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *DeviceFlowResult

PollDeviceToken polls the token endpoint until authorization completes or times out.

type DeviceFlowTokenData

type DeviceFlowTokenData struct {
	AccessToken      string
	RefreshToken     string
	ExpiresIn        int
	RefreshExpiresIn int
	Scope            string
}

DeviceFlowTokenData contains the token data from a successful device flow.

type NeedAuthorizationError

type NeedAuthorizationError struct {
	UserOpenId string
}

NeedAuthorizationError is thrown when no valid UAT exists.

func (*NeedAuthorizationError) Error

func (e *NeedAuthorizationError) Error() string

type OAuthEndpoints

type OAuthEndpoints struct {
	DeviceAuthorization string
	Token               string
}

OAuthEndpoints contains the OAuth endpoint URLs.

func ResolveOAuthEndpoints

func ResolveOAuthEndpoints(brand core.LarkBrand) OAuthEndpoints

ResolveOAuthEndpoints resolves OAuth endpoint URLs based on brand.

type SecurityPolicyError

type SecurityPolicyError struct {
	Code         int
	Message      string
	ChallengeURL string
	CLIHint      string
	Err          error
}

SecurityPolicyError is returned when a request is blocked by access control policies.

func (*SecurityPolicyError) Error

func (e *SecurityPolicyError) Error() string

func (*SecurityPolicyError) Unwrap

func (e *SecurityPolicyError) Unwrap() error

type SecurityPolicyTransport

type SecurityPolicyTransport struct {
	Base http.RoundTripper
}

SecurityPolicyTransport is an http.RoundTripper that intercepts all responses and checks for security policy errors.

func (*SecurityPolicyTransport) RoundTrip

func (t *SecurityPolicyTransport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper.

type StoredUAToken

type StoredUAToken struct {
	UserOpenId       string `json:"userOpenId"`
	AppId            string `json:"appId"`
	AccessToken      string `json:"accessToken"`
	RefreshToken     string `json:"refreshToken"`
	ExpiresAt        int64  `json:"expiresAt"`        // Unix ms
	RefreshExpiresAt int64  `json:"refreshExpiresAt"` // Unix ms
	Scope            string `json:"scope"`
	GrantedAt        int64  `json:"grantedAt"` // Unix ms
}

StoredUAToken represents a stored user access token.

func GetStoredToken

func GetStoredToken(appId, userOpenId string) *StoredUAToken

GetStoredToken reads the stored UAT for a given (appId, userOpenId) pair.

type UATCallOptions

type UATCallOptions struct {
	UserOpenId string
	AppId      string
	AppSecret  string
	Domain     core.LarkBrand
	ErrOut     io.Writer // diagnostic/status output (caller injects f.IOStreams.ErrOut)
}

UATCallOptions contains options for UAT API calls.

func NewUATCallOptions

func NewUATCallOptions(cfg *core.CliConfig, errOut io.Writer) UATCallOptions

NewUATCallOptions creates UATCallOptions from a CLI config.

type UATStatus

type UATStatus struct {
	Authorized       bool   `json:"authorized"`
	UserOpenId       string `json:"userOpenId"`
	Scope            string `json:"scope,omitempty"`
	ExpiresAt        int64  `json:"expiresAt,omitempty"`
	RefreshExpiresAt int64  `json:"refreshExpiresAt,omitempty"`
	GrantedAt        int64  `json:"grantedAt,omitempty"`
	TokenStatus      string `json:"tokenStatus,omitempty"`
}

UATStatus represents the status of a user access token.