scim

package
v1.19.0 Latest Latest
Warning

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

 Go to latest Published: Oct 10, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package scim is the SCIM 2.0 wire format (RFC 7643, RFC 7644) AuthKit speaks both ways: the User resource, list, patch and error messages, bulk requests, discovery documents, the filter subset its service providers answer, and the client its provisioning pushes with.

Index

Constants

View Source 
const (
	MaxSubject = 255 // OpenID Connect Core §2: sub is at most 255 ASCII characters
	MaxName    = 256
	MaxEmail   = 320
)

The limits of a directory User's attributes, in characters.

View Source 
const (
	SchemaUser                  = "urn:ietf:params:scim:schemas:core:2.0:User"
	SchemaListResponse          = "urn:ietf:params:scim:api:messages:2.0:ListResponse"
	SchemaError                 = "urn:ietf:params:scim:api:messages:2.0:Error"
	SchemaBulkRequest           = "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
	SchemaPatchOp               = "urn:ietf:params:scim:api:messages:2.0:PatchOp"
	SchemaBulkResponse          = "urn:ietf:params:scim:api:messages:2.0:BulkResponse"
	SchemaServiceProviderConfig = "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
	SchemaResourceType          = "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
	SchemaSchema                = "urn:ietf:params:scim:schemas:core:2.0:Schema"
)

Schema URNs.

View Source 
const MaxResults = 200

MaxResults caps one page of AuthKit's GET /Users.

View Source 
const MediaType = "application/scim+json"

MediaType is SCIM's content type.

Variables

View Source 
var ErrInvalidFilter = errors.New("scim: invalid filter")

ErrInvalidFilter is a filter outside the subset; its message is the response's detail.

View Source 
var ErrNoTenant = errors.New("scim: the credential provisions no remote application's users")

ErrNoTenant is a credential that provisions no directory.

Functions

func IsStatus 

func IsStatus(err error, status int) bool

IsStatus reports whether err is a StatusError with status.

func LocationID 

func LocationID(location string) string

LocationID is the last path segment of a resource location.

Types

type Attribute 

type Attribute struct {
	Name          string      `json:"name"`
	Type          string      `json:"type"`
	MultiValued   bool        `json:"multiValued"`
	Description   string      `json:"description,omitempty"`
	Required      bool        `json:"required"`
	CaseExact     bool        `json:"caseExact"`
	Mutability    string      `json:"mutability"`
	Returned      string      `json:"returned"`
	Uniqueness    string      `json:"uniqueness"`
	SubAttributes []Attribute `json:"subAttributes,omitempty"`
}

Attribute describes one attribute of a schema.

type AuthScheme 

type AuthScheme struct {
	Type        string `json:"type"`
	Name        string `json:"name"`
	Description string `json:"description"`
	SpecURI     string `json:"specUri,omitempty"`
	Primary     bool   `json:"primary,omitempty"`
}

AuthScheme is how a client authenticates.

type BulkOperation 

type BulkOperation struct {
	Method string `json:"method"`
	BulkID string `json:"bulkId,omitempty"`
	Path   string `json:"path"`
	Data   any    `json:"data,omitempty"`
}

BulkOperation is one operation of a bulk request.

type BulkRequest 

type BulkRequest struct {
	Schemas      []string        `json:"schemas"`
	FailOnErrors *int            `json:"failOnErrors,omitempty"`
	Operations   []BulkOperation `json:"Operations"`
}

BulkRequest is a bulk request (RFC 7644 §3.7).

type BulkResponse 

type BulkResponse struct {
	Schemas    []string     `json:"schemas"`
	Operations []BulkResult `json:"Operations"`
}

BulkResponse answers a bulk request.

type BulkResult 

type BulkResult struct {
	Location string          `json:"location,omitempty"`
	Method   string          `json:"method,omitempty"`
	BulkID   string          `json:"bulkId,omitempty"`
	Status   Status          `json:"status"`
	Response json.RawMessage `json:"response,omitempty"`
}

BulkResult is one operation's outcome. Response holds an error's detail.

type BulkSupport 

type BulkSupport struct {
	Supported      bool `json:"supported"`
	MaxOperations  int  `json:"maxOperations"`
	MaxPayloadSize int  `json:"maxPayloadSize"`
}

BulkSupport is the bulk feature and its limits.

type Client 

type Client struct {
	Base string
	HTTP *http.Client
}

Client calls a SCIM service provider at Base (".../scim/v2") through HTTP, which carries the credential.

func (*Client) Bulk 

func (c *Client) Bulk(ctx context.Context, ops []BulkOperation) (BulkResponse, error)

Bulk sends one bulk request; per-operation failures are in the response.

func (*Client) Create 

func (c *Client) Create(ctx context.Context, u User) (User, error)

Create creates a user and returns it as stored, with the provider's id.

func (*Client) Delete 

func (c *Client) Delete(ctx context.Context, id string) error

Delete deletes the user id; one already gone is no error.

func (*Client) FindByExternalID 

func (c *Client) FindByExternalID(ctx context.Context, id string) (User, bool, error)

FindByExternalID returns the provider's user whose externalId is id.

func (*Client) Get 

func (c *Client) Get(ctx context.Context, id string) (User, error)

Get reads the user id.

func (*Client) List 

func (c *Client) List(ctx context.Context, startIndex, count int) (ListResponse[User], error)

List reads one page of users, startIndex 1-based.

func (*Client) Replace 

func (c *Client) Replace(ctx context.Context, id string, u User) error

Replace replaces the user id.

func (*Client) ServiceProviderConfig 

func (c *Client) ServiceProviderConfig(ctx context.Context) (ServiceProviderConfig, error)

ServiceProviderConfig reads the provider's features and limits.

type DirectoryUser added in v1.18.0 

type DirectoryUser struct {
	Subject, UserName                             string
	DisplayName, Formatted, GivenName, FamilyName string
	Email, EmailType                              string
	Active                                        bool
}

DirectoryUser is the part of a User a directory keeps, checked: what a create or replace stores.

func (DirectoryUser) Name added in v1.18.0 

func (u DirectoryUser) Name() string

Name is how a directory user is named: displayName, else name.formatted, else the given and family names.

type Email 

type Email struct {
	Value   string `json:"value"`
	Type    string `json:"type,omitempty"`
	Primary bool   `json:"primary,omitempty"`
}

Email is one of the User's addresses.

type Error 

type Error struct {
	Schemas  []string `json:"schemas"`
	Status   string   `json:"status"`
	ScimType string   `json:"scimType,omitempty"`
	Detail   string   `json:"detail,omitempty"`
}

Error is an error response (RFC 7644 §3.12). Status is the HTTP status as a string, as the RFC's examples send it.

func NewError 

func NewError(status int, scimType, detail string) Error

NewError is an error response for status.

type Filter 

type Filter struct {
	IDs, ExternalIDs, UserNames, Emails []string
}

Filter is the filter subset AuthKit's service providers answer: equality on id, externalId, userName or emails.value, joined by "or". A user matches when it matches any term.

func ParseFilter 

func ParseFilter(expr string) (Filter, error)

ParseFilter parses expr: `attr eq "value"` terms joined by "or", attribute names and operators matched without regard to case (RFC 7644 §3.4.2.2).

type FilterSupport 

type FilterSupport struct {
	Supported  bool `json:"supported"`
	MaxResults int  `json:"maxResults"`
}

FilterSupport is the filter feature and its result cap.

type ListResponse 

type ListResponse[T any] struct {
	Schemas      []string `json:"schemas"`
	TotalResults int      `json:"totalResults"`
	StartIndex   int      `json:"startIndex"`
	ItemsPerPage int      `json:"itemsPerPage"`
	Resources    []T      `json:"Resources"`
}

ListResponse is a query's page (RFC 7644 §3.4.2).

type Meta 

type Meta struct {
	ResourceType string     `json:"resourceType,omitempty"`
	Created      *time.Time `json:"created,omitempty"`
	LastModified *time.Time `json:"lastModified,omitempty"`
	Location     string     `json:"location,omitempty"`
}

Meta is a resource's metadata.

type Name 

type Name struct {
	Formatted  string `json:"formatted,omitempty"`
	GivenName  string `json:"givenName,omitempty"`
	FamilyName string `json:"familyName,omitempty"`
}

Name is the User's name, as much of it as AuthKit keeps.

type PatchOperation added in v1.18.0 

type PatchOperation struct {
	Op    string          `json:"op"`
	Path  string          `json:"path,omitempty"`
	Value json.RawMessage `json:"value,omitempty"`
}

PatchOperation is one operation: add, replace or remove at path, or at the resource itself when path is empty.

type PatchRequest added in v1.18.0 

type PatchRequest struct {
	Schemas    []string         `json:"schemas"`
	Operations []PatchOperation `json:"Operations"`
}

PatchRequest is a PATCH request (RFC 7644 §3.5.2).

func (PatchRequest) Apply added in v1.18.0 

func (req PatchRequest) Apply(u *User) error

Apply applies the operations to u in order (RFC 7644 §3.5.2), all or none. The attributes a directory keeps are changed; any other attribute, another schema's included, is accepted and ignored as a create ignores it (RFC 7644 §3.3). A directory keeps one address, so every emails path addresses it; a value filter is matched against it (§3.5.2: an add whose filter matches nothing adds an address with the filter's type).

type ResourceType 

type ResourceType struct {
	Schemas     []string `json:"schemas"`
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	Endpoint    string   `json:"endpoint"`
	Description string   `json:"description,omitempty"`
	Schema      string   `json:"schema"`
	Meta        *Meta    `json:"meta,omitempty"`
}

ResourceType describes one resource endpoint (RFC 7643 §6).

type SchemaDoc 

type SchemaDoc struct {
	Schemas     []string    `json:"schemas,omitempty"`
	ID          string      `json:"id"`
	Name        string      `json:"name"`
	Description string      `json:"description,omitempty"`
	Attributes  []Attribute `json:"attributes"`
	Meta        *Meta       `json:"meta,omitempty"`
}

SchemaDoc describes a schema's attributes (RFC 7643 §7).

func DirectoryUserSchema added in v1.18.0 

func DirectoryUserSchema() SchemaDoc

DirectoryUserSchema is the User schema a directory serves (RFC 7643 §4.1, §7): the attributes it keeps, all readWrite. externalId, a common attribute (RFC 7643 §3.1), is the user's subject at its issuer and required.

func UserSchema 

func UserSchema() SchemaDoc

UserSchema is the part of the core User schema AuthKit serves.

type ServiceProviderConfig 

type ServiceProviderConfig struct {
	Schemas               []string      `json:"schemas"`
	DocumentationURI      string        `json:"documentationUri,omitempty"`
	Patch                 Supported     `json:"patch"`
	Bulk                  BulkSupport   `json:"bulk"`
	Filter                FilterSupport `json:"filter"`
	ChangePassword        Supported     `json:"changePassword"`
	Sort                  Supported     `json:"sort"`
	ETag                  Supported     `json:"etag"`
	AuthenticationSchemes []AuthScheme  `json:"authenticationSchemes"`
	Meta                  *Meta         `json:"meta,omitempty"`
}

ServiceProviderConfig is the discovery document of RFC 7643 §5.

type Status 

type Status int

Status is an HTTP status a SCIM peer sent as a JSON string or number; AuthKit sends a string, as RFC 7644 §3.7.3's examples do.

func (Status) MarshalText added in v1.18.0 

func (s Status) MarshalText() ([]byte, error)

func (*Status) UnmarshalJSON 

func (s *Status) UnmarshalJSON(b []byte) error

type StatusError 

type StatusError struct {
	Status   int
	ScimType string
	Detail   string
}

StatusError is a response with a status the call did not expect.

func ErrorOf 

func ErrorOf(status int, response []byte) *StatusError

ErrorOf is the StatusError a failed operation's status and response describe.

func Fail added in v1.18.0 

func Fail(status int, scimType, detail string) *StatusError

Fail is a SCIM error to answer (RFC 7644 §3.12).

func (*StatusError) Error 

func (e *StatusError) Error() string

type Supported 

type Supported struct {
	Supported bool `json:"supported"`
}

Supported is a feature a service provider has or lacks.

type Tenant added in v1.18.0 

type Tenant struct {
	GroupID string
	Persona string
	Issuer  string
}

Tenant is the directory a SCIM client provisions (RFC 7644 §6): the users of one issuer that a group trusts.

type User 

type User struct {
	Schemas     []string `json:"schemas"`
	ID          string   `json:"id,omitempty"`
	ExternalID  string   `json:"externalId,omitempty"`
	UserName    string   `json:"userName"`
	Name        *Name    `json:"name,omitempty"`
	DisplayName string   `json:"displayName,omitempty"`
	Emails      []Email  `json:"emails,omitempty"`
	Active      *bool    `json:"active,omitempty"`
	Meta        *Meta    `json:"meta,omitempty"`
}

User is the core User resource, as much of it as AuthKit sends and reads.

func (User) Directory added in v1.18.0 

func (u User) Directory() (DirectoryUser, error)

Directory checks u as a directory stores it (RFC 7644 §3.3, §3.5.1): schemas names the User schema, userName and externalId (the subject at the issuer) are required, the primary address (else the first) is the one kept, active defaults to true. Values are trimmed; an empty one is absent.

func (User) PrimaryEmail 

func (u User) PrimaryEmail() string

PrimaryEmail is the primary address, else the first; "" without one.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.