scimproto

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: MPL-2.0 Imports: 10 Imported by: 0

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

View Source
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.

View Source
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).

View Source
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

View Source
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

func DecodeGroup(raw []byte) (Group, *Error)

DecodeGroup parses a Group resource.

func DecodeUser

func DecodeUser(raw []byte) (User, *Error)

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

func ListResponse(total int, page Page, resources []any) map[string]any

ListResponse renders the RFC-shaped list envelope.

func ParseFilter

func ParseFilter(raw string, res Resource) (Filter, *Error)

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

func ParsePage(startIndex, count string, bound int) (Page, *Error)

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

func ServiceProviderConfig(maxResults int) map[string]any

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

func AsError(err error) (*Error, bool)

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

func CheckMembers(members []Member) *Error

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 Conflict

func Conflict(detail string) *Error

Conflict maps a uniqueness violation.

func ErrInvalidSyntax

func ErrInvalidSyntax(detail string) *Error

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

func ErrInvalidValue(detail string) *Error

ErrInvalidValue is the type / missing-required refusal.

func ErrMutability

func ErrMutability(detail string) *Error

ErrMutability is the write-once refusal (§5.1's subject change, and any other immutable attribute).

func ErrNoTarget

func ErrNoTarget(detail string) *Error

ErrNoTarget is the RFC's `noTarget`: a PATCH path that resolved to nothing.

func NormalizeActive

func NormalizeActive(v any) (bool, *Error)

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

func NotImplemented(what string) *Error

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) Body

func (e *Error) Body() map[string]any

Body renders the error as the RFC 7644 wire object.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

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 Page

type Page struct {
	StartIndex int
	Count      int
}

Page is a 1-based RFC 7644 page request.

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

type PatchGroupObjectPayload

type PatchGroupObjectPayload struct {
	Group Group
}

PatchGroupObjectPayload is a validated pathless Groups merge.

func (PatchGroupObjectPayload) Kind

type PatchMemberRemovalPayload

type PatchMemberRemovalPayload struct {
	MemberID string
}

PatchMemberRemovalPayload is the member ID named by a filtered remove.

func (PatchMemberRemovalPayload) Kind

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

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

type PatchPlainPayload struct {
	Attribute string
	Value     any
}

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

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 Resource

type Resource string

Resource discriminates which attribute set a filter may name.

const (
	ResourceUser  Resource = "user"
	ResourceGroup Resource = "group"
)

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).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL