Documentation
¶
Overview ¶
Package adapter holds the provider-specific rules of SCIM connections.
Shared SCIM code never infers provider behavior from names, prefixes, or identifier shapes. The registry maps an auth provider name to its adapter when a connection is created, and the connection persists the adapter's type, which selects the provider-specific rules from then on. Supporting another provider means registering another adapter.
Index ¶
- Constants
- func ConnectionAdapterType(conn *types.SCIMConnection) string
- func LocalizedDirectoryDescription(authProviderName, parameterName, description, locale string) (string, bool)
- func PendingProviderUserID(nativeUserID string) string
- func RegisterForTest(tb testing.TB, authProviderName string, a Adapter)
- func SCIMChosen(a Adapter, config map[string]string) bool
- func SupportsSCIM(authProviderName string, manifest types2.AuthProviderManifest) bool
- type Adapter
- type DirectoryParameter
- type ErrorHints
- type GroupKey
- type Identity
- type InvalidGroupError
- type InvalidUserError
- type Parameters
- type PatchRules
- type ProviderState
- type Rules
- type SCIMChoiceParameter
- type User
- type UserKey
Constants ¶
const ( // UserKeyProviderUserID matches the identity's hashed provider user ID, which sign-in keys identities by. UserKeyProviderUserID UserKey = 0 // UserKeyGroupLookupID matches the identity's hashed group lookup ID, for an identity provider whose sign-in // subject is not an ID that its SCIM client can send. UserKeyGroupLookupID UserKey = 1 // GroupKeyDisplayName binds a pushed group to the unbound group with the same normalized name. GroupKeyDisplayName GroupKey = 0 // GroupKeyExternalID binds a pushed group to the group whose ID carries the native group ID that its externalId // holds. GroupKeyExternalID GroupKey = 1 )
Variables ¶
This section is empty.
Functions ¶
func ConnectionAdapterType ¶
func ConnectionAdapterType(conn *types.SCIMConnection) string
ConnectionAdapterType returns the adapter type of conn, an auth provider's SCIM connection, or an empty string when conn is nil, as ProviderState.ConnectionAdapterType takes it.
func LocalizedDirectoryDescription ¶
func LocalizedDirectoryDescription(authProviderName, parameterName, description, locale string) (string, bool)
LocalizedDirectoryDescription returns localized text only for descriptions generated by an adapter: those of its directory parameters and of its SCIM choice parameter.
func PendingProviderUserID ¶ added in v0.28.0
PendingProviderUserID returns the provider user ID of an identity that SCIM creates for an adapter with UserKeyGroupLookupID, whose sign-in subject SCIM does not know. The user's first sign-in finds the identity by it, and replaces it with the subject.
func RegisterForTest ¶ added in v0.28.0
RegisterForTest registers a for the named auth provider and under its type until the test ends, and then restores whatever it replaced. Tests of shared code use it for rules that no registered adapter has, such as those of adaptertest.Adapter. Tests that register an adapter must not run in parallel with tests that look adapters up.
func SCIMChosen ¶ added in v0.28.0
SCIMChosen reports whether config, a submitted configuration of an auth provider that has no SCIM connection, chooses SCIM-first setup. For an adapter with a SCIM choice parameter, that parameter must be "true". Otherwise, providing any of the adapter's directory parameters chooses directory synchronization, and omitting them all chooses SCIM. Empty values count as absent.
func SupportsSCIM ¶
func SupportsSCIM(authProviderName string, manifest types2.AuthProviderManifest) bool
SupportsSCIM reports whether the named auth provider can have a SCIM connection: the registry has an adapter for it, and its manifest declares a group ID prefix, which groups created through SCIM keep.
Types ¶
type Adapter ¶
type Adapter interface {
// Type is the adapter's persisted type.
Type() string
// DirectoryParameters are the auth provider configuration parameters that only login-time directory
// synchronization uses.
DirectoryParameters() []DirectoryParameter
// SCIMChoiceParameter returns the parameter that chooses SCIM-first setup, for an auth provider without directory
// parameters. Its Name is empty when omitting the directory parameters chooses SCIM.
SCIMChoiceParameter() SCIMChoiceParameter
// IssuerConfigurationParameter names the auth provider configuration parameter that holds the identity
// provider's issuer URL.
IssuerConfigurationParameter() string
// NativeUserID returns the identity provider's immutable ID for a SCIM user. A user binds to the existing
// identity of the connection's auth provider that stores the same ID.
NativeUserID(user User) (string, error)
// NativeUserIDFromExternalID returns the native user ID that a SCIM user's externalId holds, as NativeUserID would
// for a user with that externalId, without the checks of other attributes. It answers externalId filters. It
// returns an *InvalidUserError for an externalId that holds none.
NativeUserIDFromExternalID(externalID string) (string, error)
// UserKey returns which identity column a SCIM user's native ID matches.
UserKey() UserKey
// NewUserIdentity returns the Obot username and identity fields for a user that SCIM creates, so that the user's
// later sign-ins find the same identity.
NewUserIdentity(nativeUserID string) Identity
// GroupKey returns how a pushed group finds an existing Obot group.
GroupKey() GroupKey
// NativeGroupIDFromExternalID validates a pushed group's externalId and returns the native group ID it holds, for
// GroupKeyExternalID. It returns an *InvalidGroupError for an externalId that holds none.
NativeGroupIDFromExternalID(externalID string) (string, error)
// NewGroupID returns the Obot ID for a group that SCIM creates. nativeGroupID is the native group ID that
// NativeGroupIDFromExternalID returned, for GroupKeyExternalID, and empty otherwise. For GroupKeyExternalID, the
// ID depends on nativeGroupID alone, so that a pushed group's ID can be found from its externalId.
NewGroupID(groupIDPrefix, scimID, nativeGroupID string) string
// NativeGroupID returns the identity provider's own ID of the group with the given Obot ID, or an empty string
// when the Obot ID does not carry one, such as the ID of a group that SCIM created.
NativeGroupID(groupIDPrefix, groupID string) string
// GroupConsoleURL returns the address of a group in the identity provider's admin console, or an empty string
// when it cannot be built from the issuer.
GroupConsoleURL(issuer, nativeGroupID string) string
// PatchRules returns how the identity provider's PATCH requests depart from RFC 7644.
PatchRules() PatchRules
// Rules returns the identity provider's choices among shared behaviors.
Rules() Rules
// ErrorHints returns the provider-specific text that the details of some SCIM errors carry.
ErrorHints() ErrorHints
}
Adapter holds the rules that differ between identity providers.
func ForAuthProvider ¶
ForAuthProvider returns the adapter of the named auth provider, and whether the provider supports SCIM.
type DirectoryParameter ¶
type DirectoryParameter struct {
Name string
// SetupDescription describes the parameter while the auth provider is being configured, when providing it
// chooses directory synchronization and omitting it chooses SCIM.
SetupDescription string
SetupTranslations map[string]string
// UnusedDescription describes the parameter once a SCIM connection has replaced directory synchronization.
UnusedDescription string
UnusedTranslations map[string]string
}
DirectoryParameter is a configuration parameter that only login-time directory synchronization uses, with the descriptions the configuration form shows for it.
type ErrorHints ¶ added in v0.28.0
type ErrorHints struct {
// Retry is appended to the detail of a failure that may succeed when the request is retried, such as a request
// that took too long or arrived while the endpoint was unavailable.
Retry string
// UserDelete replaces the detail of the refusal of a user DELETE, for an adapter whose Rules do not delete users.
// The shared detail asks for a deactivation instead. An identity provider that sends a DELETE unless it is set up
// otherwise names the setting here.
UserDelete string
// ValuelessFilteredAdd is appended to the detail of the refusal of an add whose path has a value filter and that
// has no value, as in {"op":"add","path":"members[value eq \"id\"]"}.
ValuelessFilteredAdd string
// ExternalIDChanged is appended to the detail of the refusal of a change to a provisioned user's externalId, which
// the user is bound by.
ExternalIDChanged string
}
ErrorHints holds provider-specific text for SCIM error details. An identity provider that shows a failed request's detail to its admin, and never retries the request on its own, needs the detail to say what to change in the identity provider and how to recover. An empty field leaves the shared detail as it is. A failure whose cause the adapter itself finds, such as a user without the attributes it needs, says so in its InvalidUserError instead.
type GroupKey ¶ added in v0.28.0
type GroupKey int
GroupKey is how a pushed group finds an existing Obot group.
type Identity ¶
type Identity struct {
Username string
ProviderUsername string
ProviderUserID string
ProviderGroupLookupID string
}
Identity holds the Obot user and identity fields for a user that SCIM creates.
type InvalidGroupError ¶ added in v0.28.0
type InvalidGroupError struct {
Message string
}
InvalidGroupError reports a pushed group whose externalId holds no native group ID.
func (*InvalidGroupError) Error ¶ added in v0.28.0
func (e *InvalidGroupError) Error() string
type InvalidUserError ¶
type InvalidUserError struct {
Message string
}
InvalidUserError reports a SCIM user that lacks the attributes the adapter needs.
func (*InvalidUserError) Error ¶
func (e *InvalidUserError) Error() string
type Parameters ¶
type Parameters struct {
Required []types2.ProviderConfigurationParameter
Optional []types2.ProviderConfigurationParameter
// Dropped names the parameters that a submitted configuration must not keep.
Dropped []string
// SCIMChoice names the adapter's SCIM choice parameter, which Dropped lists, or is empty when there is none. A
// configuration is staged with it, so that the provider configuration change makes the choice that the API checked.
SCIMChoice string
// Together names optional parameters that a configuration must hold all of or none of, because the auth
// provider refuses to start with only some of them.
Together []string
}
Parameters are an auth provider's effective configuration parameters, which depend on its SCIM setup. Every check of whether the provider is configured uses Required, and the configuration form shows Required and Optional.
func EffectiveParameters ¶
func EffectiveParameters(manifest types2.AuthProviderManifest, state ProviderState) Parameters
EffectiveParameters returns an auth provider's effective configuration parameters, from its manifest, its adapter, its SCIM connection, and its stored configuration.
Only the adapter's directory parameters and SCIM choice parameter differ from the manifest:
- A provider that is being configured or staged, and has no connection, may omit the directory parameters: providing them sets up directory synchronization, and omitting them sets up SCIM. They are optional, described as that choice, and must be provided together.
- A configured provider without a connection synchronizes its directory at sign-in, so they are required as the manifest lists them.
- With a connection, they are never required. If the stored configuration still holds them, they are optional and described as unused, so they can be removed. Otherwise they are absent, and dropped if submitted.
- The SCIM choice parameter, of a provider with one, is always dropped, so it is never stored. A provider that is being configured or staged, and has no connection, also lists it as a hidden optional parameter, described as the choice it makes.
func (Parameters) IncompleteGroup ¶
func (p Parameters) IncompleteGroup(config map[string]string) []string
IncompleteGroup returns the parameters of Together that config lacks when it holds some but not all of them, and nothing otherwise. Empty values count as absent.
type PatchRules ¶
type PatchRules struct {
// ReplaceAddsUnmatched makes a replace whose value filter selects no value do what an add does and create the
// value, where RFC 7644 section 3.5.2.3 fails it with noTarget. Microsoft Entra ID sends a replace of
// emails[type eq "work"].value for a user who has no work email.
ReplaceAddsUnmatched bool
}
PatchRules holds how an identity provider's PATCH requests depart from RFC 7644. The SCIM endpoint accepts such a request only from the connections of that provider.
type ProviderState ¶
type ProviderState struct {
// AuthProviderName names the auth provider. Without a SCIM connection, it selects the provider's adapter.
AuthProviderName string
// Configured is set when the configuration being described is the provider's active one: for the configured
// auth provider, and for every check of whether a stored configuration is complete. Without a SCIM connection,
// such a provider synchronizes its directory at sign-in.
Configured bool
// ConnectionAdapterType is the adapter type of the provider's SCIM connection, or empty when it has none.
ConnectionAdapterType string
// Stored is the provider's stored configuration, or nil when it has none.
Stored map[string]string
}
ProviderState is what an auth provider's effective configuration parameters depend on, besides its manifest.
type Rules ¶ added in v0.28.0
type Rules struct {
// DeletesUsers makes DELETE /Users/{id} delete the user and their data, instead of refusing it with 501.
DeletesUsers bool
}
Rules holds an identity provider's choices among shared behaviors, which take no arguments.
type SCIMChoiceParameter ¶ added in v0.28.0
SCIMChoiceParameter is a configuration parameter that chooses SCIM-first setup when it is "true", with the description the configuration form shows for it. Obot reads it and drops it, so it is never stored, and the auth provider never sees it.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package adaptertest provides a SCIM adapter for tests of shared code that need rules no registered adapter has.
|
Package adaptertest provides a SCIM adapter for tests of shared code that need rules no registered adapter has. |