Documentation
¶
Overview ¶
Package sdk is the Go client for an application that runs beside Kiban: the app's backend authenticates as its registered service client, verifies the user tokens Kiban's login issued, asks for access decisions, writes and removes relation tuples on the app's own object types, and looks members up — all through the gateway's public API, never by network position.
client, err := sdk.New(ctx, sdk.Config{GatewayURL: "https://kiban.example", ClientID: "tokidesk-backend", ClientSecret: secret})
sub, err := client.VerifyUserToken(ctx, bearer) // the user behind a request
d, err := client.Can(ctx, bearer, sdk.CanRequest{...}) // may this user do this here?
err = client.Grant(ctx, companyID, sdk.Tuple{...}) // the app owns its own types
Index ¶
- Variables
- type APIError
- type AppManifest
- type Assignment
- type BatchItem
- type BatchResult
- type CanRequest
- type Client
- func (c *Client) BatchCan(ctx context.Context, userBearer string, req CanRequest, items []BatchItem) ([]BatchResult, error)
- func (c *Client) BatchCanService(ctx context.Context, req CanRequest, items []BatchItem) ([]BatchResult, error)
- func (c *Client) Can(ctx context.Context, userBearer string, req CanRequest) (Decision, error)
- func (c *Client) CanService(ctx context.Context, req CanRequest) (Decision, error)
- func (c *Client) Grant(ctx context.Context, companyID string, tuples ...Tuple) error
- func (c *Client) GroupMembers(ctx context.Context, companyID, groupID string) ([]GroupMember, error)
- func (c *Client) MeCompanies(ctx context.Context, userBearer string) ([]Company, error)
- func (c *Client) MemberBySubject(ctx context.Context, companyID, subject string) (MemberFact, error)
- func (c *Client) MemberDirectory(ctx context.Context, companyID, q string, page, pageSize int) (DirectoryPage, error)
- func (c *Client) PositionHolder(ctx context.Context, companyID, positionID string, date time.Time) (Assignment, error)
- func (c *Client) RegisterApp(ctx context.Context, superadminBearer string, m AppManifest) error
- func (c *Client) Revoke(ctx context.Context, companyID string, tuples ...Tuple) error
- func (c *Client) ServiceToken(ctx context.Context) (string, error)
- func (c *Client) VerifyUserToken(ctx context.Context, bearer string) (string, error)
- type Company
- type Config
- type Decision
- type DirectoryEntry
- type DirectoryPage
- type GroupMember
- type MemberFact
- type Tuple
Constants ¶
This section is empty.
Variables ¶
var ErrTokenInvalid = modulekit.ErrTokenInvalid
ErrTokenInvalid is returned by VerifyUserToken for a token Kiban did not issue, or one that expired or names another audience.
Functions ¶
This section is empty.
Types ¶
type AppManifest ¶
type AppManifest struct {
Key string `json:"key"`
DisplayName string `json:"displayName"`
Version string `json:"version"`
ServiceClientID string `json:"serviceClientId"`
Features []string `json:"features,omitempty"`
AuthzFragment json.RawMessage `json:"authzFragment"`
}
AppManifest registers the app: its key, service client, feature keys and object types.
type Assignment ¶ added in v0.1.1
type Assignment struct {
ID string `json:"id"`
PositionID string `json:"positionId"`
MemberID string `json:"memberId"`
ValidFrom string `json:"validFrom"`
ValidTo *string `json:"validTo"`
}
Assignment is a member holding a position for a validity window.
type BatchItem ¶ added in v0.1.1
type BatchItem struct {
Object struct {
Type string `json:"type"`
ID string `json:"id"`
} `json:"object"`
Relation string `json:"relation"`
}
BatchItem is one object-relation pair of a batch check.
func NewBatchItem ¶ added in v0.1.1
NewBatchItem builds a BatchItem.
type BatchResult ¶ added in v0.1.1
type BatchResult struct {
Object struct {
Type string `json:"type"`
ID string `json:"id"`
} `json:"object"`
Relation string `json:"relation"`
Decision Decision `json:"decision"`
}
BatchResult is one item's decision.
type CanRequest ¶
type CanRequest struct {
FeatureKey string `json:"featureKey"`
ModuleKey string `json:"moduleKey,omitempty"`
CompanyID string `json:"companyId,omitempty"`
Scope string `json:"scope,omitempty"` // "company" (default) or "global"
Object *struct {
Type string `json:"type"`
ID string `json:"id"`
} `json:"object,omitempty"`
Relation string `json:"relation,omitempty"`
}
CanRequest asks "may the bearer use featureKey of moduleKey in companyId?", optionally bound to one object relation.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is safe for concurrent use.
func New ¶
New validates cfg and fetches the realm's signing keys once; a gateway that cannot be reached is an error here, not later.
func (*Client) BatchCan ¶ added in v0.1.1
func (c *Client) BatchCan(ctx context.Context, userBearer string, req CanRequest, items []BatchItem) ([]BatchResult, error)
BatchCan asks up to 100 object-relation questions for the user in one call; req carries the feature, module and company, items the objects. One round trip for a page of controls.
func (*Client) BatchCanService ¶ added in v0.1.1
func (c *Client) BatchCanService(ctx context.Context, req CanRequest, items []BatchItem) ([]BatchResult, error)
BatchCanService is BatchCan for the app's own service account.
func (*Client) Can ¶
Can asks for a decision on behalf of the user whose bearer the app received. Kiban answers for that bearer only.
func (*Client) CanService ¶
CanService asks for a decision for the app's own service account (a background job).
func (*Client) Grant ¶
Grant writes tuples on the app's own object types in companyID. Every module object must carry its company anchor; AnchorTuple builds it.
func (*Client) GroupMembers ¶ added in v0.1.1
func (c *Client) GroupMembers(ctx context.Context, companyID, groupID string) ([]GroupMember, error)
GroupMembers lists the current members of groupID in companyID, as the app's service account.
func (*Client) MeCompanies ¶ added in v0.1.1
MeCompanies lists the companies the user behind userBearer may see: their active memberships in active companies. The company switcher's source.
func (*Client) MemberBySubject ¶
func (c *Client) MemberBySubject(ctx context.Context, companyID, subject string) (MemberFact, error)
MemberBySubject asks org whether subject is an active member of companyID.
func (*Client) MemberDirectory ¶ added in v0.1.1
func (c *Client) MemberDirectory(ctx context.Context, companyID, q string, page, pageSize int) (DirectoryPage, error)
MemberDirectory reads one page of companyID's active members, optionally filtered by a substring of display name or email, as the app's service account. The service account must be a member of the company.
func (*Client) PositionHolder ¶ added in v0.1.1
func (c *Client) PositionHolder(ctx context.Context, companyID, positionID string, date time.Time) (Assignment, error)
PositionHolder answers who holds positionID in companyID on date, as the app's service account. A 404 APIError means nobody holds it that day.
func (*Client) RegisterApp ¶
RegisterApp registers (or re-registers) the app with a superadmin's bearer. Typically run once by an operator or at the app's first start.
func (*Client) ServiceToken ¶
ServiceToken returns the app's own access token (client credentials), refreshed before it expires. Callers rarely need it directly; the methods below use it.
type Company ¶ added in v0.1.1
type Company struct {
ID string `json:"id"`
Code string `json:"code"`
Name string `json:"name"`
IsActive bool `json:"isActive"`
}
Company is one company the user may see.
type Config ¶
type Config struct {
// GatewayURL is the gateway's origin, e.g. "https://kiban.example". Login, JWKS and the
// API all hang off it.
GatewayURL string
// Realm defaults to "kiban".
Realm string
// ClientID and ClientSecret are the app's confidential service client.
ClientID string
ClientSecret string
// Audience defaults to "kiban-api".
Audience string
// HTTPClient defaults to one with a 15 s timeout.
HTTPClient *http.Client
}
Config names the Kiban deployment and the app's service client (KIBAN_SERVICE_CLIENTS).
type DirectoryEntry ¶ added in v0.1.1
type DirectoryEntry struct {
ID string `json:"id"`
DisplayName string `json:"displayName"`
Email string `json:"email"`
HasLinkedUser bool `json:"hasLinkedUser"`
Kind string `json:"kind"` // "person" or "service"
}
DirectoryEntry is one member of a company's directory: the least-disclosure view.
type DirectoryPage ¶ added in v0.1.1
type DirectoryPage struct {
Items []DirectoryEntry `json:"items"`
Total int `json:"total"`
Page int `json:"page"`
PageSize int `json:"pageSize"`
TotalPages int `json:"totalPages"`
}
DirectoryPage is one page of a company's directory.
type GroupMember ¶ added in v0.1.1
type GroupMember struct {
GroupID string `json:"groupId"`
MemberID string `json:"memberId"`
MemberDisplayName string `json:"memberDisplayName"`
MemberEmail string `json:"memberEmail"`
AddedBy string `json:"addedBy"`
AddedAt string `json:"addedAt"`
}
GroupMember is one member of a group.
type MemberFact ¶
type MemberFact struct {
IsMember bool `json:"isMember"`
IsActive bool `json:"isActive"`
MemberID *string `json:"memberId"`
}
MemberFact answers "is this subject an active member of this company, and which member".
type Tuple ¶
Tuple is one relation tuple: object#relation@subject (subjectRelation for a userset).
func AnchorTuple ¶
AnchorTuple is the `<objectType>:<objectID>#company_module @ company_module:<companyID>/<appKey>` tuple every object of the app must carry: it binds the object to the company. Write it in the same Grant call as the object's first tuple.