180 lines
5.1 KiB
Markdown
180 lines
5.1 KiB
Markdown
# API
|
|
|
|
Generated from the package comment and every exported declaration. Do not edit.
|
|
Regenerate with `UPDATE_API_DOCS=1 go test -run TestAPIDoc -count=1`.
|
|
|
|
## Package usertoken
|
|
|
|
Package usertoken mints and checks the short-lived RS256 user token an ExApp sends to Microservices.
|
|
|
|
An ExApp calls [NewSignerFromEnv](#newsignerfromenv) and [Signer.Mint](#signermint) after AppAPI has named the user. A Microservice calls [FromEnv](#fromenv) and [Auth.Middleware](#authmiddleware) or [Auth.UnaryServerInterceptor](#authunaryserverinterceptor). One process trusts either a static public key or an OIDC issuer, not both.
|
|
|
|
The procedure, claims, and environment variables are in knowledge/platforms/nextcloud/exapps/authentication.md.
|
|
|
|
## Variables
|
|
|
|
### ErrUnauthorized
|
|
|
|
```go
|
|
var ErrUnauthorized = errors.New("unauthorized")
|
|
```
|
|
|
|
ErrUnauthorized is wrapped by every failed token check. Startup and configuration failures do not wrap it.
|
|
|
|
## Functions
|
|
|
|
### BearerFromContext
|
|
|
|
```go
|
|
func BearerFromContext(ctx context.Context) (string, bool)
|
|
```
|
|
|
|
BearerFromContext returns the raw JWT [Auth.Middleware](#authmiddleware) stored, without the "Bearer " prefix. Outbound calls send "Bearer " plus this string.
|
|
|
|
## Types
|
|
|
|
### Auth
|
|
|
|
```go
|
|
type Auth struct {
|
|
// contains filtered or unexported fields
|
|
}
|
|
```
|
|
|
|
Auth verifies bearers for one Microservice process.
|
|
|
|
#### FromEnv
|
|
|
|
```go
|
|
func FromEnv(ctx context.Context) (*Auth, error)
|
|
```
|
|
|
|
FromEnv reads the process environment and builds an Auth. Set USER\_TOKEN\_PUBLIC\_KEY\_FILE or OIDC\_ISSUER, not both and not neither. Static mode also reads USER\_TOKEN\_ISSUER and USER\_TOKEN\_AUDIENCE. OIDC mode reads OIDC\_AUDIENCE and optional OIDC\_GROUPS\_CLAIM. Optional USER\_TOKEN\_SKEW is a time.Duration; empty uses 1 minute. It returns an error when the mode is ambiguous, the key file is unreadable, USER\_TOKEN\_SKEW cannot be parsed, or OIDC discovery fails. ctx is used for OIDC discovery.
|
|
|
|
#### New
|
|
|
|
```go
|
|
func New(ctx context.Context, cfg Config) (*Auth, error)
|
|
```
|
|
|
|
New builds an Auth from explicit configuration. ctx is used for OIDC discovery.
|
|
|
|
#### Auth.Middleware
|
|
|
|
```go
|
|
func (a *Auth) Middleware() func(http.Handler) http.Handler
|
|
```
|
|
|
|
Middleware requires a bearer on every path except /health. Success stores the Caller and the raw JWT on the request context.
|
|
|
|
#### Auth.UnaryServerInterceptor
|
|
|
|
```go
|
|
func (a *Auth) UnaryServerInterceptor() grpc.UnaryServerInterceptor
|
|
```
|
|
|
|
UnaryServerInterceptor requires a bearer on every RPC. Success stores the Caller and the raw JWT on the handler context, same as [Auth.Middleware](#authmiddleware). Native clients send metadata key "authorization". The HTTP gateway's forwarded header is "grpcgateway-authorization".
|
|
|
|
#### Auth.Verify
|
|
|
|
```go
|
|
func (a *Auth) Verify(ctx context.Context, raw string) (Caller, error)
|
|
```
|
|
|
|
Verify checks a raw JWT. raw has no "Bearer " prefix. A failed check wraps ErrUnauthorized. Startup and configuration failures do not.
|
|
|
|
### Caller
|
|
|
|
```go
|
|
type Caller struct {
|
|
Subject string
|
|
Username string
|
|
Groups []string
|
|
}
|
|
```
|
|
|
|
Caller is the user a verified token names. Groups is nil when the token omitted the claim, and non-nil (possibly empty) when the claim was present.
|
|
|
|
#### CallerFromContext
|
|
|
|
```go
|
|
func CallerFromContext(ctx context.Context) (Caller, bool)
|
|
```
|
|
|
|
CallerFromContext returns the user [Auth.Middleware](#authmiddleware) stored.
|
|
|
|
### Config
|
|
|
|
```go
|
|
type Config struct {
|
|
PublicKey *rsa.PublicKey
|
|
Issuer string
|
|
Audience string
|
|
OIDCIssuer string
|
|
OIDCAudience string
|
|
GroupsClaim string
|
|
Skew time.Duration
|
|
}
|
|
```
|
|
|
|
Config selects one verify mode. Set PublicKey for static RS256, or OIDCIssuer for discovery. Not both. Skew of zero uses 1 minute. GroupsClaim empty uses "groups" (OIDC only). Audience empty is allowed only for OIDC, where it skips the audience check.
|
|
|
|
### MintInput
|
|
|
|
```go
|
|
type MintInput struct {
|
|
Subject string
|
|
Groups *[]string
|
|
}
|
|
```
|
|
|
|
MintInput is one user token. Groups nil omits the claim. A non-nil pointer includes it, including an empty list.
|
|
|
|
### SignConfig
|
|
|
|
```go
|
|
type SignConfig struct {
|
|
PrivateKey *rsa.PrivateKey
|
|
Issuer string
|
|
Audience string
|
|
TTL time.Duration
|
|
}
|
|
```
|
|
|
|
SignConfig is the ExApp mint configuration. TTL of zero uses 5 minutes.
|
|
|
|
### Signer
|
|
|
|
```go
|
|
type Signer struct {
|
|
// contains filtered or unexported fields
|
|
}
|
|
```
|
|
|
|
Signer mints RS256 user tokens. Only the ExApp should hold one.
|
|
|
|
#### NewSigner
|
|
|
|
```go
|
|
func NewSigner(cfg SignConfig) (*Signer, error)
|
|
```
|
|
|
|
NewSigner checks the key, issuer, and audience. It returns an error when PrivateKey is nil or issuer or audience is empty. A TTL of zero or less uses 5 minutes.
|
|
|
|
#### NewSignerFromEnv
|
|
|
|
```go
|
|
func NewSignerFromEnv() (*Signer, error)
|
|
```
|
|
|
|
NewSignerFromEnv reads USER\_TOKEN\_PRIVATE\_KEY\_FILE, USER\_TOKEN\_ISSUER, USER\_TOKEN\_AUDIENCE, and optional USER\_TOKEN\_TTL. It returns an error when the private-key path is empty, the PEM is not an RSA key, USER\_TOKEN\_TTL is set and is not a time.Duration, or issuer or audience is empty. An empty USER\_TOKEN\_TTL uses 5 minutes.
|
|
|
|
#### Signer.Mint
|
|
|
|
```go
|
|
func (s *Signer) Mint(now time.Time, in MintInput) (string, error)
|
|
```
|
|
|
|
Mint signs one RS256 token at now. Subject becomes both sub and preferred\_username. It returns an error when Subject is empty or the key cannot sign.
|
|
|