setup

package
v0.28.0-alpha1 Latest Latest
Warning

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

Go to latest
Published: Oct 20, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package setup sets up and administers the SCIM connections of auth providers.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CleanUpGroupSubjects

func CleanUpGroupSubjects(ctx context.Context, gateway *gclient.Client, storage kclient.Client) error

CleanUpGroupSubjects runs the cleanups of group subjects that no replica is running. A cleanup that fails is retried once its claim expires.

func EnableConnection

func EnableConnection(ctx context.Context, storage kclient.Reader, gateway *gclient.Client, authProvider v1.AuthProvider) (*types.SCIMConnection, error)

EnableConnection creates the SCIM connection that permanently replaces the login-time directory synchronization of an auth provider, and returns it. The connection has no bearer token; CompleteEnable issues it. A provider that already has a connection created this way has it returned, so that a retried provider configuration change finds the connection an earlier attempt created.

It is refused with *EnableBlockedError when the provider does not support SCIM, another connection exists, an auth provider cleanup is pending for the provider's name or group ID prefix, or two referenced groups of the provider have the same name. The caller must be serialized with provider configuration changes, which are the only creators of auth provider cleanups, and must have checked that the provider is the configured auth provider and that no replacement is staged. storage must read without a cache.

func EnsureSCIMFirstConnection

func EnsureSCIMFirstConnection(ctx context.Context, storage kclient.Reader, gateway *gclient.Client, authProvider v1.AuthProvider, config map[string]string) (*types.SCIMConnection, error)

EnsureSCIMFirstConnection makes sure that an auth provider being configured or staged without directory credentials has its SCIM connection, and returns it. A provider that already has one keeps it, which is also how a retried configuration change reuses the connection an earlier attempt created. Otherwise the connection is created in the connected state, with no token, before any sign-in through the provider can ask it for groups.

It is refused with *IneligibleError, *CleanupPendingError, or *ResidualGroupDataError when the provider does not support SCIM, another connection exists, an auth provider cleanup is pending for the provider's name or group ID prefix, or the provider has residual group data. The caller must be serialized with provider configuration changes, which are the only creators of auth provider cleanups, and must not be the configured provider. storage must read without a cache, and config is the submitted configuration, which holds the issuer.

func ResidualGroupData

func ResidualGroupData(ctx context.Context, storage kclient.Reader, gateway *gclient.Client, authProvider v1.AuthProvider) (*types2.ResidualGroupData, error)

ResidualGroupData returns what remains of an auth provider's groups from an earlier configuration: exactly the data that its auth provider cleanup removes. That is its groups; the memberships, group role assignments, and access policy subjects of group IDs with its group ID prefix. storage must read without a cache.

func RunGroupSubjectCleanups

func RunGroupSubjectCleanups(ctx context.Context, gateway *gclient.Client, storage kclient.Client)

RunGroupSubjectCleanups removes the subjects of groups that a SCIM DELETE deleted from access policies, until ctx is done. Every replica runs it, and claims keep replicas from usually running the same cleanup.

func StoredConfiguration

func StoredConfiguration(ctx context.Context, gateway *gclient.Client, authProvider v1.AuthProvider) (map[string]string, error)

StoredConfiguration returns the configuration that an auth provider has stored, active or staged, or nil when it has none.

Types

type Actor

type Actor struct {
	UserID                uint
	AuthProviderNamespace string
	AuthProviderName      string
	Owner                 bool
	Bootstrap             bool
}

Actor is the user making a request, as far as SCIM administration cares.

type AuthProviders

type AuthProviders interface {
	GetConfiguredAuthProvider(ctx context.Context) (string, error)
	GetStagedAuthProvider(ctx context.Context) (string, error)
}

AuthProviders reports which auth provider serves sign-ins, and which one is staged to replace it.

type CleanupPendingError

type CleanupPendingError struct {
	AuthProviderName string
	CleanupName      string
	Locale           string
}

CleanupPendingError reports that a SCIM connection was not created, because an auth-provider cleanup is pending for the auth provider or its group ID prefix.

func (*CleanupPendingError) Error

func (e *CleanupPendingError) Error() string

type ConfigurationError

type ConfigurationError struct {
	Message string
}

ConfigurationError reports a configuration that the SCIM rules of its auth provider refuse.

func (*ConfigurationError) Error

func (e *ConfigurationError) Error() string

type EnableBlockedError

type EnableBlockedError struct {
	Blockers   []string
	Duplicates []types2.SCIMDuplicateGroupName
	Locale     string
}

EnableBlockedError reports why SCIM cannot be enabled for an auth provider.

func (*EnableBlockedError) Error

func (e *EnableBlockedError) Error() string

type GroupList

type GroupList string

GroupList selects one of the lists of groups in a review.

const (
	// DefaultPageSize is the size of each list in a review, and of a page when none is asked for.
	DefaultPageSize = 50
	// MaxPageSize bounds the page a caller can ask for.
	MaxPageSize = 200

	// GroupListBound selects the groups that SCIM manages.
	GroupListBound GroupList = "bound"
	// GroupListUnboundReferenced selects the referenced groups that the identity provider has not pushed.
	GroupListUnboundReferenced GroupList = "unboundReferenced"
	// GroupListUnreferenced selects the unbound groups that nothing references.
	GroupListUnreferenced GroupList = "unreferenced"
)

type IneligibleError

type IneligibleError struct {
	Message string
}

IneligibleError reports that an auth provider cannot be configured without directory credentials.

func (*IneligibleError) Error

func (e *IneligibleError) Error() string

type Page

type Page struct {
	Offset int
	Limit  int
}

Page selects a page of a list. Offset is zero-based.

func NormalizePage

func NormalizePage(offset, limit int) Page

NormalizePage bounds a requested page.

type ResidualGroupDataError

type ResidualGroupDataError struct {
	AuthProviderName        string
	AuthProviderDisplayName string
	Data                    types2.ResidualGroupData
	Locale                  string
}

ResidualGroupDataError reports that an auth provider cannot be configured without directory credentials, because it still has group data from an earlier configuration. Running the provider's auth provider cleanup removes it.

func (*ResidualGroupDataError) Error

func (e *ResidualGroupDataError) Error() string

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service runs the administration of SCIM connections: enabling SCIM for an auth provider that synchronizes its directory at sign-in, reviewing a connection, deleting its auth provider's unreferenced groups, enforcing it, and managing its bearer token.

func New

func New(gateway *gclient.Client, storage kclient.Reader, providers AuthProviders, serverURL string) *Service

New returns the Service. storage must read without a cache, and serverURL is Obot's public URL, which SCIM base URLs are built from.

func (*Service) CheckEnable

func (s *Service) CheckEnable(ctx context.Context) (string, string, error)

CheckEnable returns the namespace and name of the configured auth provider when SCIM can be enabled for it, and otherwise a bad request that lists everything that blocks enabling it. The provider configuration change that enables SCIM checks it all again under the serialization of such changes.

func (*Service) CompleteEnable

func (s *Service) CompleteEnable(ctx context.Context, namespace, name string) (*types2.SCIMEnableResult, error)

CompleteEnable finishes enabling SCIM for an auth provider, once a provider configuration change created its connection with EnableConnection: it deletes the provider's groups that nothing references, and then issues the connection's first bearer token.

The token cannot be retrieved again, so it is issued last, and nothing that can fail or take long runs between issuing and returning it. A request that ends before then leaves a connection without a token, whose token an Owner generates on the SCIM sub-tab. For the same reason, a failed deletion is reported in the result rather than failing it. The deletion can be retried.

It returns a conflict when the connection has a token already, because SCIM was enabled before, or a concurrent request or an Owner was given the token, and when the connection was not created by enabling SCIM.

func (*Service) Connections

func (s *Service) Connections(ctx context.Context) ([]types2.SCIMConnection, error)

Connections returns every SCIM connection: zero or one.

func (*Service) DeleteUnreferencedGroups

func (s *Service) DeleteUnreferencedGroups(ctx context.Context, id string) (*types2.SCIMGroupDeletionResult, error)

DeleteUnreferencedGroups deletes the unbound groups of the connection's auth provider that nothing references. Such groups grant nothing, so their deletion triggers no cleanup of the resources of their former members.

func (*Service) EnablePreview

func (s *Service) EnablePreview(ctx context.Context) (*types2.SCIMEnablePreview, error)

EnablePreview reports the configured auth provider that SCIM can be enabled for, and what blocks enabling it.

func (*Service) Enforce

func (s *Service) Enforce(ctx context.Context, id string, actor Actor) (*types2.SCIMEnforceResult, error)

Enforce requires a SCIM binding for sign-in with the connection's auth provider, permanently. It disables the provider's users that SCIM has not provisioned, and deletes its unbound groups that nothing references. It is refused unless the provider is the configured auth provider, every referenced group of the provider is bound, and actor is an Owner who signed in through the provider and is provisioned and active.

The unreferenced groups are deleted in two phases, as withUnreferencedGroupsMarked describes. Enforcing keeps any marked group that gained a reference, and blocks if that group is unbound. It clears every mark for deletion, so it is refused with a conflict while another deletion of unreferenced groups holds marks.

func (*Service) Failures

func (s *Service) Failures(ctx context.Context, id string, page Page) (*types2.SCIMRequestFailurePage, error)

Failures returns a page of the connection's recent failed requests, newest first.

func (*Service) Groups

func (s *Service) Groups(ctx context.Context, id string, list GroupList, page Page) (*types2.SCIMSetupGroupPage, error)

Groups returns a page of one of the lists of the connection's groups.

func (*Service) Review

func (s *Service) Review(ctx context.Context, id string, actor Actor, pageSize int) (*types2.SCIMConnectionReview, error)

Review reports the state of a SCIM connection, and what enforcing it would do. Each list holds its first page of pageSize items. actor is the requesting user, whose ability to sign in afterwards is one of Enforce's preconditions.

func (*Service) RevokeCurrentToken

func (s *Service) RevokeCurrentToken(ctx context.Context, id string) (*types2.SCIMConnection, error)

RevokeCurrentToken replaces a leaked bearer token: it issues a new token, which it returns with the connection, and stops accepting both the current and the previous token.

func (*Service) RevokePreviousToken

func (s *Service) RevokePreviousToken(ctx context.Context, id string) (*types2.SCIMConnection, error)

RevokePreviousToken stops accepting the token that the last rotation replaced.

func (*Service) RotateToken

func (s *Service) RotateToken(ctx context.Context, id string) (*types2.SCIMConnection, error)

RotateToken issues a new bearer token for the connection, including its first token, and returns the connection with it. The token it replaces is still accepted for up to a day, but never past its own expiry, or until it is revoked.

func (*Service) Users

func (s *Service) Users(ctx context.Context, id string, provisioned bool, page Page) (*types2.SCIMSetupUserPage, error)

Users returns a page of the connection's provisioned users, or of its auth provider's unprovisioned users.

type Setup

type Setup int

Setup is what a configuration submitted for an auth provider sets up.

const (
	// SetupKept means the configuration keeps how the provider gets its users and groups: through its SCIM
	// connection, by synchronizing its directory at sign-in, or, for a provider without SCIM rules, as always.
	SetupKept Setup = iota
	// SetupSCIMFirst means the configuration omits the directory parameters of a provider that is not configured and
	// has no SCIM connection, so the connection must be created before the provider's credential exists.
	SetupSCIMFirst
)

func CheckConfiguration

func CheckConfiguration(ctx context.Context, gateway *gclient.Client, authProvider v1.AuthProvider, configured func() (bool, error), stored func() (map[string]string, error), secrets map[string]string) (adapter.Parameters, Setup, error)

CheckConfiguration applies the SCIM rules of an auth provider to a configuration submitted for it, and returns the provider's effective parameters and what the configuration sets up. Both the API, which validates a configuration before submitting it, and the provider configuration change, which applies it, check it here, so that they agree.

It first drops from secrets the parameters that the provider no longer uses, so that a provider whose directory is managed through SCIM is configured again without them. It then refuses, with a *ConfigurationError:

  • some but not all of the parameters that the provider needs together;
  • a configuration of a configured provider that synchronizes its directory, without the directory parameters. Moving it to SCIM is Enable and Enforce.

It does not check the provider's other required parameters, which the API checks against the parameters it returns.

Jump to

Keyboard shortcuts

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