Package io.jenkins.plugins.authcommons

Class PrincipalSearchProvider

java.lang.Object

io.jenkins.plugins.authcommons.PrincipalSearchProvider

All Implemented Interfaces:

ExtensionPoint

public abstract class PrincipalSearchProvider
extends Object
implements ExtensionPoint

Looks up users and groups in a directory, so that authorization strategies can offer autocompletion when choosing who gets access.

Typically implemented by plugins that provide a SecurityRealm, and consumed by authorization strategy plugins through PrincipalSearch. Implementations do not need to check permissions; callers are responsible for that.

Nested Class Summary

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Constructor Summary

Constructors

Constructor	Description
PrincipalSearchProvider()

Method Summary

Modifier and Type	Method	Description
static ExtensionList<PrincipalSearchProvider>	all()
abstract boolean	isApplicable(SecurityRealm realm)	Whether this provider can search the given security realm.
Principal	lookup(String sid, PrincipalType type)	Look up a single principal by SID, so that a friendly name can be shown for SIDs that are not meaningful by themselves (such as object ids).
abstract List<Principal>	search(String query, Set<PrincipalType> types, int limit)	Search for principals matching a query.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

PrincipalSearchProvider

public PrincipalSearchProvider()

Method Details

isApplicable

public abstract boolean isApplicable(@NonNull
 SecurityRealm realm)

Whether this provider can search the given security realm.

Parameters:

realm - the currently configured security realm

search

@NonNull
public abstract List<Principal> search(@NonNull
 String query,
 @NonNull
 Set<PrincipalType> types,
 int limit)
                                throws Exception

Search for principals matching a query.

Parameters:

query - free text entered by the user, at least PrincipalSearch.MIN_QUERY_LENGTH characters

types - the kinds of principals to return, never empty

limit - the maximum number of results to return

Returns:

matching principals, best matches first

Throws:

Exception - if the directory could not be searched

lookup

@CheckForNull
public Principal lookup(@NonNull
 String sid,
 @NonNull
 PrincipalType type)
                 throws Exception

Look up a single principal by SID, so that a friendly name can be shown for SIDs that are not meaningful by themselves (such as object ids).

Returns:

the principal, or null if it is unknown or this provider does not support lookups

Throws:

Exception - if the directory could not be queried

all

public static ExtensionList<PrincipalSearchProvider> all()