Class AuthDomain

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.soup.AuthDomain

All Implemented Interfaces:

Proxy

Direct Known Subclasses:

AuthDomain.AuthDomain$Impl, AuthDomainBasic, AuthDomainDigest

@Generated("org.javagi.JavaGI")
public abstract class AuthDomain
extends GObject

Server-side authentication.

A AuthDomain manages authentication for all or part of a Server. To make a server require authentication, first create an appropriate subclass of AuthDomain, and then add it to the server with Server.addAuthDomain(AuthDomain).

In order for an auth domain to have any effect, you must add one or more paths to it (via addPath(String)). To require authentication for all ordinary requests, add the path "/". (Note that this does not include the special "*" URI (eg, "OPTIONS *"), which must be added as a separate path if you want to cover it.)

If you need greater control over which requests should and shouldn't be authenticated, add paths covering everything you might want authenticated, and then use a filter (setFilter(AuthDomainFilter) to bypass authentication for those requests that don't need it.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	AuthDomain.AuthDomain$Impl	The AuthDomain$Impl type represents a native instance of the abstract AuthDomain class.
static class	AuthDomain.AuthDomainClass
static class	AuthDomain.Builder<B extends AuthDomain.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.

Nested classes/interfaces inherited from class GObject

GObject.NotifyCallback, GObject.ObjectClass

Constructor Summary

Constructors

Constructor	Description
AuthDomain()	Create a new AuthDomain.
AuthDomain(MemorySegment address)	Create a AuthDomain instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
@Nullable String	accepts(ServerMessage msg)	Checks if msg contains appropriate authorization for this AuthDomain to accept it.
protected String	accepts(ServerMessage msg, String header)
void	addPath(String path)	Adds path to domain.
protected AuthDomain	asParent()	Return this instance as if it were its parent type.
String	challenge(ServerMessage msg)	Adds a "WWW-Authenticate" or "Proxy-Authenticate" header to msg.
boolean	checkPassword(ServerMessage msg, String username, String password)	Checks if msg authenticates to this AuthDomain via username and password.
boolean	covers(ServerMessage msg)	Checks if this AuthDomain requires msg to be authenticated (according to its paths and filter function).
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
String	getRealm()	Gets the realm name associated with domain.
static @Nullable Type	getType()	Get the GType of the AuthDomain class.
void	removePath(String path)	Removes path from domain.
void	setFilter(@Nullable AuthDomainFilter filter)	Adds filter as an authentication filter to domain.
void	setGenericAuthCallback(@Nullable AuthDomainGenericAuthCallback authCallback)	Sets authCallback as an authentication-handling callback for domain.

Methods inherited from class GObject

addToggleRef, addWeakPointer, bindProperty, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, builder, compatControl, connect, connect, connect, constructed, disconnect, dispatchPropertiesChanged, dispose, dupData, dupQdata, emit, emitNotify, finalize_, forceFloating, freezeNotify, get, getData, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, newv, notify, notify, notifyByPspec, onNotify, ref, refSink, removeToggleRef, removeWeakPointer, replaceData, replaceQdata, runDispose, set, setData, setDataFull, setProperty, setProperty, setProperty, setQdata, setQdataFull, setv, stealData, stealQdata, takeRef, thawNotify, unref, watchClosure, weakRef, weakUnref, withProperties

Methods inherited from class TypeInstance

callParent, callParent, cast, getPrivate, readGClass, writeGClass

Methods inherited from class ProxyInstance

equals, handle, hashCode

Methods inherited from class Object

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

Constructor Details

AuthDomain

public AuthDomain(MemorySegment address)

Create a AuthDomain instance for the provided memory address.

Parameters:

address - the memory address of the native object

AuthDomain

public AuthDomain()

Create a new AuthDomain.

Method Details

getType

public static @Nullable Type getType()

Get the GType of the AuthDomain class.

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

asParent

protected AuthDomain asParent()

Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.

Overrides:

asParent in class GObject

Returns:

the instance as if it were its parent type

accepts

public @Nullable String accepts(ServerMessage msg)

Checks if msg contains appropriate authorization for this AuthDomain to accept it.

Mirroring covers(ServerMessage), this does not check whether or not this AuthDomain cares if msg is authorized.

This is used by Server internally and is probably of no use to anyone else.

Parameters:

msg - a SoupServerMessage

Returns:

the username that msg has authenticated as, if in fact it has authenticated. null otherwise.

addPath

public void addPath(String path)

Adds path to domain.

Requests under path on domain's server will require authentication (unless overridden by removePath(String) or setFilter(AuthDomainFilter)).

Parameters:

path - the path to add to this AuthDomain

challenge

public String challenge(ServerMessage msg)

Adds a "WWW-Authenticate" or "Proxy-Authenticate" header to msg.

It requests that the client authenticate, and sets msg's status accordingly.

This is used by Server internally and is probably of no use to anyone else.

Parameters:

msg - a SoupServerMessage

checkPassword

public boolean checkPassword(ServerMessage msg,
 String username,
 String password)

Checks if msg authenticates to this AuthDomain via username and password.

This would normally be called from a AuthDomainGenericAuthCallback.

Parameters:

msg - a SoupServerMessage

username - a username

password - a password

Returns:

whether or not the message is authenticated

covers

public boolean covers(ServerMessage msg)

Checks if this AuthDomain requires msg to be authenticated (according to its paths and filter function).

This does not actually look at whether msg is authenticated, merely whether or not it needs to be.

This is used by Server internally and is probably of no use to anyone else.

Parameters:

msg - a SoupServerMessage

Returns:

true if this AuthDomain requires msg to be authenticated

getRealm

public String getRealm()

Gets the realm name associated with domain.

Returns:

domain's realm

removePath

public void removePath(String path)

Removes path from domain.

Requests under path on domain's server will NOT require authentication.

This is not simply an undo-er for addPath(String); it can be used to "carve out" a subtree that does not require authentication inside a hierarchy that does. Note also that unlike with addPath(String), this cannot be overridden by adding a filter, as filters can only bypass authentication that would otherwise be required, not require it where it would otherwise be unnecessary.

Parameters:

path - the path to remove from this AuthDomain

setFilter

public void setFilter(@Nullable AuthDomainFilter filter)

Adds filter as an authentication filter to domain.

The filter gets a chance to bypass authentication for certain requests that would otherwise require it. Eg, it might check the message's path in some way that is too complicated to do via the other methods, or it might check the message's method, and allow GETs but not PUTs.

The filter function returns true if the request should still require authentication, or false if authentication is unnecessary for this request.

To help prevent security holes, your filter should return true by default, and only return false under specifically-tested circumstances, rather than the other way around. Eg, in the example above, where you want to authenticate PUTs but not GETs, you should check if the method is GET and return false in that case, and then return true for all other methods (rather than returning true for PUT and false for all other methods). This way if it turned out (now or later) that some paths supported additional methods besides GET and PUT, those methods would default to being NOT allowed for unauthenticated users.

You can also set the filter by setting the SoupAuthDomain:filter and AuthDomain:filter-data properties, which can also be used to set the filter at construct time.

Parameters:

filter - the auth filter for this AuthDomain

setGenericAuthCallback

public void setGenericAuthCallback(@Nullable AuthDomainGenericAuthCallback authCallback)

Sets authCallback as an authentication-handling callback for domain.

Whenever a request comes in to this AuthDomain which cannot be authenticated via a domain-specific auth callback (eg, AuthDomainDigestAuthCallback), the generic auth callback will be invoked. See AuthDomainGenericAuthCallback for information on what the callback should do.

Parameters:

authCallback - the auth callback

accepts

protected String accepts(ServerMessage msg,
 String header)