Documentation
¶
Overview ¶
Package scimproto is the SCIM 2.0 wire protocol Hikyo implements: the closed resource set, the closed filter grammar, the closed PATCH operation x path matrix, the RFC 7644 error shapes, and the discovery documents.
It is deliberately free of storage and authorization. Everything here is a pure function of bytes, which is what lets the closed matrix and the closed error mapping have one fixture per cell rather than one end-to-end test per guess (#73 §8).
Nothing generic is implemented. The ADR's posture is "each advertised absent in ServiceProviderConfig, each refused with the RFC 7644 error shape, never half-implemented", so an unimplemented feature is a named refusal here and an honest `false` in the discovery document — never a silent partial answer.
Index ¶
- Constants
- Variables
- func Declares(declared []ExtensionDecl, urn string) bool
- func DecodeGroup(raw []byte) (Group, *Error)
- func DecodeUser(raw []byte) (User, *Error)
- func ListResponse(total int, page Page, resources []any) map[string]any
- func ParseFilter(raw string, res Resource) (Filter, *Error)
- func ParsePage(startIndex, count string, bound int) (Page, *Error)
- func ParsePatch(raw []byte, res Resource) ([]ParsedPatch, *Error)
- func ResourceTypes(declared []ExtensionDecl) map[string]any
- func Schemas(declared []ExtensionDecl) map[string]any
- func SchemasFor(attributes map[string]any, declared []ExtensionDecl) []string
- func ServiceProviderConfig(maxResults int) map[string]any
- func UndeclaredExtension(attributes map[string]any, declared []ExtensionDecl) string
- type Error
- func AsError(err error) (*Error, bool)
- func CheckMembers(members []Member) *Error
- func Conflict(detail string) *Error
- func ErrInvalidSyntax(detail string) *Error
- func ErrInvalidValue(detail string) *Error
- func ErrMutability(detail string) *Error
- func ErrNoTarget(detail string) *Error
- func NormalizeActive(v any) (bool, *Error)
- func NotFound() *Error
- func NotImplemented(what string) *Error
- func Unauthorized() *Error
- type ExtensionDecl
- type Filter
- type FilterShape
- type Group
- type GroupRef
- type Member
- type Meta
- type Page
- type ParsedPatch
- type PatchActivePayload
- type PatchGroupObjectPayload
- type PatchMemberRemovalPayload
- type PatchMemberSetPayload
- type PatchOp
- type PatchPayload
- type PatchPlainPayload
- type PatchRequest
- type PatchUserObjectPayload
- type PathKind
- type Resource
- type User
Constants ¶
const ( SchemaUser = "urn:ietf:params:scim:schemas:core:2.0:User" SchemaGroup = "urn:ietf:params:scim:schemas:core:2.0:Group" SchemaListResponse = "urn:ietf:params:scim:api:messages:2.0:ListResponse" SchemaPatchOp = "urn:ietf:params:scim:api:messages:2.0:PatchOp" SchemaError = "urn:ietf:params:scim:api:messages:2.0:Error" SchemaSPConfig = "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig" SchemaResourceType = "urn:ietf:params:scim:schemas:core:2.0:ResourceType" SchemaSchemaRes = "urn:ietf:params:scim:schemas:core:2.0:Schema" SchemaEnterpriseExt = "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" )
Schema URIs, the only ones this server speaks.
const ( TypeInvalidFilter = "invalidFilter" TypeInvalidPath = "invalidPath" TypeInvalidValue = "invalidValue" TypeInvalidSyntax = "invalidSyntax" TypeMutability = "mutability" TypeUniqueness = "uniqueness" TypeNoTarget = "noTarget" TypeTooMany = "tooMany" )
scimType values, the closed 400-class discriminator set (§8).
const MediaType = "application/scim+json"
MediaType is the SCIM content type. Responses use it; requests are accepted with it or with plain JSON, because real IdPs send both.
Variables ¶
var ErrBodyTooLarge = &Error{ Status: http.StatusRequestEntityTooLarge, Detail: "The request body exceeds this service provider's bound.", }
ErrBodyTooLarge is the named bound refusal (§9's admission entry).
Functions ¶
func Declares ¶
func Declares(declared []ExtensionDecl, urn string) bool
Declares reports whether a URN is in a declared set.
func DecodeGroup ¶
DecodeGroup parses a Group resource.
func DecodeUser ¶
DecodeUser parses a User resource under the parse-don't-cast discipline: IdP-supplied strings are attacker-influencable free text at a trust boundary, so they are bounded and UTF-8-checked here and nowhere later.
The `password` attribute is refused BY NAME (§5.2) rather than dropped: silently ignoring it would let an administrator believe provisioning had set a credential, and the credential-establishment contract is the only path to one.
func ListResponse ¶
ListResponse renders the RFC-shaped list envelope.
func ParseFilter ¶
ParseFilter accepts exactly the four probes Okta and Entra issue — `userName eq "..."` and `externalId eq "..."` on Users, `displayName eq "..."` and `externalId eq "..."` on Groups — and refuses everything else with `invalidFilter`. Both discover a group by `displayName eq` before creating or updating it, which is why that one is not optional.
It is a hand-written recognizer rather than a general SCIM filter parser on purpose: a general parser would accept expressions the storage layer cannot answer, and every one of those is a filter silently returning the wrong set.
func ParsePage ¶
ParsePage reads `startIndex` and `count`, clamping to the server's bound. RFC 7644 §3.4.2.4 makes `count` a request, so a larger one is answered with the bound rather than refused; an out-of-range page returns an empty `Resources` with a truthful `totalResults`, which the caller handles.
func ParsePatch ¶
func ParsePatch(raw []byte, res Resource) ([]ParsedPatch, *Error)
ParsePatch decodes and validates a whole PATCH request against the matrix.
It validates every operation's matrix cell and value payload before returning, because a PATCH is atomic: any invalid operation fails the whole request with nothing committed. Resource-to-command conversion may impose additional resource rules, and also completes before any command is applied.
func ResourceTypes ¶
func ResourceTypes(declared []ExtensionDecl) map[string]any
ResourceTypes is the closed resource set: User and Group, and nothing else. The User type declares its supported schema EXTENSION, because a binding whose subject source is an extension path is describing an attribute a connector can only learn about from here.
func Schemas ¶
func Schemas(declared []ExtensionDecl) map[string]any
Schemas lists the schema URIs this server speaks, WITH their attribute definitions. The definitions are not decoration: `userName` is advertised `caseExact: false` (which is why it is refused as a subject source), `externalId` byte-exact, and the subject-source attribute immutable — every one of those is a refusal this server actually makes.
func SchemasFor ¶
func SchemasFor(attributes map[string]any, declared []ExtensionDecl) []string
SchemasFor returns the schema URIs a rendered User must declare: the core one plus every DECLARED extension present among its round-tripped attributes.
The declared set and the discovery documents are built from the SAME list, so a resource can never claim conformance to a schema `/Schemas` does not describe — and an UNDECLARED extension never reaches here at all, because ingest refuses it by name.
func ServiceProviderConfig ¶
ServiceProviderConfig advertises the implemented subset. Every `supported` below is false for a reason stated at the refusal site: no Bulk, no filter beyond the four `eq` probes, no sorting, no ETag, and no change-password — provisioning never establishes credentials.
func UndeclaredExtension ¶
func UndeclaredExtension(attributes map[string]any, declared []ExtensionDecl) string
UndeclaredExtension returns the first `urn:`-keyed top-level attribute that no declared extension covers, or "". A resource carrying one is refused: this server's discovery is "the closed truth of what it implements" (§8), and storing an attribute under a schema it never described would make that claim false the moment the resource were read back.
Types ¶
type Error ¶
type Error struct {
Status int
// SCIMType is the 400-class discriminator. It is EMPTY for anything that is
// not a 400-class refusal — notably the 501s, where the ADR says so by name:
// scimType is a 400-class discriminator and putting one on a 501 would
// invent a code the RFC does not define.
SCIMType string
Detail string
}
Error is an RFC 7644 error body plus the status it must be rendered with.
func AsError ¶
AsError unwraps an *Error from an error chain, so a transport can render the protocol shape without type-switching on every call site.
func CheckMembers ¶
CheckMembers applies §6's two named member refusals: a group-typed member (nested groups: v1 is flat, and Okta and Entra provision direct user members) and an empty reference. Both are `invalidValue`, 400.
func ErrInvalidSyntax ¶
ErrInvalidSyntax is the RFC's `invalidSyntax`: a body that is not a valid resource at all. It is the shape the transport hands back when the request could not even be bound — the same refusal DecodeUser makes, rendered from one place so the two cannot disagree.
func ErrInvalidValue ¶
ErrInvalidValue is the type / missing-required refusal.
func ErrMutability ¶
ErrMutability is the write-once refusal (§5.1's subject change, and any other immutable attribute).
func ErrNoTarget ¶
ErrNoTarget is the RFC's `noTarget`: a PATCH path that resolved to nothing.
func NormalizeActive ¶
NormalizeActive reads the `active` attribute, tolerating Entra's stringified booleans ("True"/"False") — a NAMED tolerance, not a general string-to-bool coercion: anything else is `invalidValue`.
func NotFound ¶
func NotFound() *Error
NotFound is the RFC's 404 for a resource id this binding did not mint.
func NotImplemented ¶
NotImplemented is the refusal for the four endpoint classes this server does not implement — Bulk, /Me, sorting and .search. HTTP 501, and NO scimType.
func Unauthorized ¶
func Unauthorized() *Error
Unauthorized is the credential-versus-binding-path mismatch and every other authentication failure — NEVER a SCIM 400 (§8).
func (*Error) Unwrap ¶
Unwrap makes an RFC error answer the domain sentinel a caller outside the wire would test for. The two vocabularies have to coexist: a refusal is a SCIM error on the wire and an invalid request everywhere else, and without this a service returning one would be unclassifiable off the wire.
type ExtensionDecl ¶
type ExtensionDecl struct {
// URN is the extension schema.
URN string
// Attribute is the one attribute the binding names at that URN. It is
// empty for the built-in enterprise extension, whose attribute set is
// fixed and fully described.
Attribute string
}
ExtensionDecl is one schema extension a binding DECLARES. §5.1 admits `externalId` or "a declared enterprise/custom extension path" as a subject source, and declaration at binding creation is what closes the set: an extension is describable in discovery precisely because a binding named it.
func EnterpriseExtension ¶
func EnterpriseExtension() ExtensionDecl
EnterpriseExtension is declared by every binding: it is built in, its attributes are the RFC's, and a connector may send them whether or not this binding's subject source lives there.
type Filter ¶
type Filter struct {
Shape FilterShape
Value string
}
Filter is a parsed filter: the shape and the single compared value.
type FilterShape ¶
type FilterShape string
FilterShape is the closed set of filters this server answers, and doubles as the audit payload's `filter_shape` enum.
const ( FilterNone FilterShape = "none" FilterUserNameEq FilterShape = "userName_eq" FilterExternalIDEq FilterShape = "externalId_eq" FilterDisplayNameEq FilterShape = "displayName_eq" )
type Group ¶
type Group struct {
Schemas []string `json:"schemas"`
ID string `json:"id,omitempty"`
ExternalID string `json:"externalId,omitempty"`
DisplayName string `json:"displayName,omitempty"`
Members []Member `json:"members"`
Meta *Meta `json:"meta,omitempty"`
Extra map[string]any `json:"-"`
}
Group is the subset of RFC 7643's Group this server implements.
type GroupRef ¶
type GroupRef struct {
Value string `json:"value"`
Display string `json:"display,omitempty"`
Type string `json:"type,omitempty"`
}
GroupRef is the response-only `groups` member on a User (RFC 7643 makes it read-only; membership is authored exclusively through Group operations).
type Member ¶
type Member struct {
Value string `json:"value"`
Display string `json:"display,omitempty"`
Type string `json:"type,omitempty"`
Ref string `json:"$ref,omitempty"`
}
Member is one member reference. `Type` carries the IdP's own claim about what the reference points at; a group-typed one is refused by name.
type Meta ¶
type Meta struct {
ResourceType string `json:"resourceType"`
Created string `json:"created,omitempty"`
LastModified string `json:"lastModified,omitempty"`
Location string `json:"location,omitempty"`
Version string `json:"version,omitempty"`
}
Meta is the RFC common attribute block.
type ParsedPatch ¶
type ParsedPatch struct {
Op string
Payload PatchPayload
}
ParsedPatch is one validated operation with the typed payload for its accepted matrix cell.
type PatchActivePayload ¶
type PatchActivePayload struct {
Active bool
}
PatchActivePayload is a normalized Users active assignment.
func (PatchActivePayload) Kind ¶
func (PatchActivePayload) Kind() PathKind
type PatchGroupObjectPayload ¶
type PatchGroupObjectPayload struct {
Group Group
}
PatchGroupObjectPayload is a validated pathless Groups merge.
func (PatchGroupObjectPayload) Kind ¶
func (PatchGroupObjectPayload) Kind() PathKind
type PatchMemberRemovalPayload ¶
type PatchMemberRemovalPayload struct {
MemberID string
}
PatchMemberRemovalPayload is the member ID named by a filtered remove.
func (PatchMemberRemovalPayload) Kind ¶
func (PatchMemberRemovalPayload) Kind() PathKind
type PatchMemberSetPayload ¶
type PatchMemberSetPayload struct {
Members []Member
}
PatchMemberSetPayload is a validated Groups members assignment or clear. Members is nil only for a remove operation.
func (PatchMemberSetPayload) Kind ¶
func (PatchMemberSetPayload) Kind() PathKind
type PatchOp ¶
type PatchOp struct {
Op string `json:"op"`
// Path is the RFC's attribute path. It is named `Path` on the wire because
// RFC 7644 names it that; nothing derived from it ever reaches an audit
// payload field of that name, which the registry forbids.
Path string `json:"path"`
Value json.RawMessage `json:"value"`
}
PatchOp is one decoded PATCH operation.
type PatchPayload ¶
type PatchPayload interface {
Kind() PathKind
// contains filtered or unexported methods
}
PatchPayload is the closed set of decoded values carried by accepted PATCH matrix cells. Keeping raw JSON out of ParsedPatch makes the parser the one owner of operation-value decoding.
type PatchPlainPayload ¶
PatchPlainPayload is an ordinary attribute assignment or removal. Value is nil only for a remove operation.
func (PatchPlainPayload) Kind ¶
func (PatchPlainPayload) Kind() PathKind
type PatchRequest ¶
type PatchRequest struct {
Schemas []string `json:"schemas"`
Operations []PatchOp `json:"Operations"`
}
PatchRequest is a decoded PatchOp message.
type PatchUserObjectPayload ¶
type PatchUserObjectPayload struct {
User User
}
PatchUserObjectPayload is a validated pathless Users merge.
func (PatchUserObjectPayload) Kind ¶
func (PatchUserObjectPayload) Kind() PathKind
type PathKind ¶
type PathKind int
PathKind is the closed set of path shapes the matrix has columns for.
const ( // PathNone is the pathless value object: `{"op":"add","value":{...}}`, // which merges the object's attributes. PathNone PathKind = iota // PathPlain is an ordinary attribute path (`userName`, `displayName`, // `externalId`). PathPlain // PathActive is `active` — a Users-only column. PathActive // PathMembers is `members` — a Groups-only column. PathMembers // PathMemberValue is `members[value eq "..."]` — a Groups-only column, and // the only filtered path the matrix admits. PathMemberValue )
type User ¶
type User struct {
Schemas []string `json:"schemas"`
ID string `json:"id,omitempty"`
ExternalID string `json:"externalId,omitempty"`
UserName string `json:"userName,omitempty"`
// Active is decoded from the generic object rather than by the struct tag:
// Entra sends `"True"`, which fails to unmarshal into a *bool BEFORE
// NormalizeActive could apply the tolerance the ADR mandates.
Active *bool `json:"-"`
Groups []GroupRef `json:"groups,omitempty"`
Meta *Meta `json:"meta,omitempty"`
Extra map[string]any `json:"-"`
}
User is the subset of RFC 7643's User this server implements. Every other member is accepted and round-tripped as opaque display metadata — never matched, never a linking key, never verified authority (§5.2).