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 CanRequest
- type Client
- 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) MemberBySubject(ctx context.Context, companyID, subject string) (MemberFact, 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 Config
- type Decision
- 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 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) 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) 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) 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 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 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.