Package org.forgerock.oauth2.core

Interface OAuth2ProviderSettings

All Known Implementing Classes:

AgentOAuth2ProviderSettings, RealmOAuth2ProviderSettings

public interface OAuth2ProviderSettings

Interface for defining all settings an OAuth2 provider can have and that can be configured.

Method Summary

Modifier and Type	Method	Description
Map<String,String>	additionalDataToReturnFromAuthorizeEndpoint(Map<String,Token> tokens, OAuth2Request request)	Provided as an extension point to allow the OAuth2 provider to return additional data from an authorization request.
void	additionalDataToReturnFromTokenEndpoint(AccessToken accessToken, OAuth2Request request)	Provided as an extension point to allow the OAuth2 provider to return additional data from an access token request.
boolean	clientsCanSkipConsent()	Whether clients can opt to skip resource owner consent during authorization flows.
Map<String,Object>	evaluateScope(AccessToken accessToken)	Gets the specified access token's information.
boolean	exists()	Checks whether the config exists.
long	getAccessTokenLifetime()	Gets the lifetime an access token will have before it expires.
Map<String,AuthenticationMethod>	getAcrMapping()	Returns a mapping from Authentication Context Class Reference (ACR) values (typically a Level of Assurance value) to concrete authentication methods.
Map<String,ResponseTypeHandler>	getAllowedResponseTypes()	Gets the response types allowed by the OAuth2 provider.
Map<String,String>	getAMRAuthModuleMappings()	The mappings between amr values and auth module names.
long	getAuthorizationCodeLifetime()	Gets the lifetime an authorization code will have before it expires.
boolean	getClaimsParameterSupported()	Returns whether this provider supports claims requested via 'claims' parameter.
String	getCompletionUrl()	The URL that the user will be sent to on completion of their OAuth 2 login and consent when using the device code flow.
String	getCreatedTimestampAttributeName()	Gets the created timestamp attribute name.
freemarker.template.Template	getCustomLoginUrlTemplate()	Gets the custom login url template which will create the url to redirect resource owners to for authentication.
String	getDefaultAcrValues()	The default Authentication Context Class Reference (ACR) values to use for authentication if none is specified in the request.
Set<String>	getDefaultScopes()	Gets the default set of scopes to give a client registering with this provider.
int	getDeviceCodeLifetime()	The lifetime of the device code.
int	getDeviceCodePollInterval()	The polling interval for devices waiting for tokens when using the device code flow.
Set<String>	getEndpointAuthMethodsSupported()	Returns the token_endpoint_auth_methods available for clients to register (and subsequently auth) using.
String	getHashSalt()	Returns the salt to use for hashing sub values upon pairwise requests.
org.forgerock.json.JsonValue	getJWKSet()	Gets the JWK Set for this OAuth2 Authorization /OpenID Provider.
String	getJWKSUri()	Gets the JSON Web Key Set URI.
String	getModifiedTimestampAttributeName()	Gets the modified timestamp attribute name.
String	getOpenIDConnectVersion()	Gets the supported version of the OpenID Connect specification.
long	getOpenIdTokenLifetime()	Gets the lifetime an OpenID token will have before it expires.
long	getRefreshTokenLifetime()	Gets the lifetime an refresh token will have before it expires.
Set<String>	getResourceOwnerAuthenticatedAttributes()	Gets the attributes of the resource owner that are used for authenticating resource owners.
ResourceSetStore	getResourceSetStore()	Returns the ResourceSetStore instance for the realm.
KeyPair	getSigningKeyPair(org.forgerock.json.jose.jws.JwsAlgorithm algorithm)	Gets the signing key pair of the OAuth2 provider.
Set<String>	getSupportedClaims()	Gets the supported claims for this provider.
Set<String>	getSupportedClaimsWithTranslations()	Gets the supported claims for this provider as strings with pipe-separated translations.
Set<String>	getSupportedIDTokenEncryptionAlgorithms()	Gets the algorithms that the OAuth2 provider supports for encryptin OpenID tokens.
Set<String>	getSupportedIDTokenEncryptionMethods()	Gets the encryption methods that the OAuth2 provider supports for encryptin OpenID tokens.
Set<String>	getSupportedIDTokenSigningAlgorithms()	Gets the algorithms that the OAuth2 provider supports for signing OpenID tokens.
Set<String>	getSupportedScopes()	Gets the supported scopes for this provider without translations.
Set<String>	getSupportedScopesWithTranslations()	Gets the supported scopes for this provider.
Set<String>	getSupportedSubjectTypes()	Gets the subject types supported by the OAuth2 provider.
String	getTokenHmacSharedSecret()	Gets the Base64 encoded shared secret used to sign stateless access and refresh tokens.
String	getTokenSigningAlgorithm()	Gets the signing algorithm used when issuing stateless access and refresh tokens.
String	getUserDisplayNameAttribute()	The attribute that can be used to obtain a UI-displayable name for a user's AMIdentity.
UserInfoClaims	getUserInfo(ClientRegistration clientRegistration, AccessToken token, OAuth2Request request)	Gets the resource owners information based on an issued access token or request.
String	getVerificationUrl()	The URL that the user will be instructed to visit to complete their OAuth 2 login and consent when using the device code flow.
boolean	isAlwaysAddClaimsToToken()	Whether to always add claims to id_tokens - non-spec compliant.
boolean	isCodeVerifierRequired()	Whether or not to enforce the Code Verifier Parameter.
boolean	isConsentSaved(ResourceOwner resourceOwner, String clientId, Set<String> scope)	Determines whether a resource owner's consent has been saved from a previous authorize request.
boolean	isIdTokenInfoClientAuthenticationEnabled()	Determines whether idtokeninfo endpoint should require client authentication.
boolean	isOpenDynamicClientRegistrationAllowed()	Indicates whether clients may register without providing an access token.
boolean	isOpenIDConnectSSOProviderEnabled()	Whether OpenID Connect ID Tokens are accepted as SSOTokens in this realm or not.
boolean	isRegistrationAccessTokenGenerationEnabled()	Whether to generate access tokens for clients that register without one.
boolean	isSaveConsentEnabled()	Determines if the consent can be saved or not, due to a lack of configuration.
boolean	isStatelessTokensEnabled()	Determines whether access and refresh tokens should be stateless.
boolean	issueRefreshTokens()	Whether the OAuth2 provider should issue refresh tokens when issuing access tokens.
boolean	issueRefreshTokensOnRefreshingToken()	Whether the OAuth2 provider should issue refresh tokens when refreshing access tokens.
boolean	isTokenCompressionEnabled()	Determines whether token compression is enabled for stateless access and refresh tokens.
void	revokeConsent(String userId, String clientId)	Revokes the resource owner's consent for the granting authorization for the specified client.
void	saveConsent(ResourceOwner resourceOwner, String clientId, Set<String> scope)	Saves the resource owner's consent for the granting authorization for the specified client with the specified scope.
boolean	shouldStoreOpsTokens()	Whether to generate and store an ops token in CTS for this OIDC provider.
Set<String>	validateAccessTokenScope(ClientRegistration clientRegistration, Set<String> scope, OAuth2Request request)	Provided as an extension point to allow the OAuth2 provider to customise the scope requested when an access token is requested.
Set<String>	validateAuthorizationScope(ClientRegistration clientRegistration, Set<String> scope, OAuth2Request request)	Provided as an extension point to allow the OAuth2 provider to customise the scope requested when authorization is requested.
Set<String>	validateRefreshTokenScope(ClientRegistration clientRegistration, Set<String> requestedScope, Set<String> tokenScope, OAuth2Request request)	Provided as an extension point to allow the OAuth2 provider to customise the scope requested when a refresh token is requested.
String	validateRequestedClaims(String requestedClaims)	Validates that the requested claims are appropriate to be requested by the given client.

Method Detail

isStatelessTokensEnabled

boolean isStatelessTokensEnabled()
                          throws ServerException

Determines whether access and refresh tokens should be stateless.

Returns:

true if access and refresh tokens are stateless.

Throws:

ServerException - If any internal server error occurs.

isIdTokenInfoClientAuthenticationEnabled

boolean isIdTokenInfoClientAuthenticationEnabled()
                                          throws ServerException

Determines whether idtokeninfo endpoint should require client authentication.

Returns:

true if idtokeninfo endpoint requires client authentication.

Throws:

ServerException - If any internal server error occurs.

getTokenSigningAlgorithm

String getTokenSigningAlgorithm()
                         throws ServerException

Gets the signing algorithm used when issuing stateless access and refresh tokens.

Returns:

The signing algorithm.

Throws:

ServerException - If any internal server error occurs.

isTokenCompressionEnabled

boolean isTokenCompressionEnabled()
                           throws ServerException

Determines whether token compression is enabled for stateless access and refresh tokens.

Returns:

true if compression should be enabled.

Throws:

ServerException - if an error occurs reading the settings.

getTokenHmacSharedSecret

String getTokenHmacSharedSecret()
                         throws ServerException

Gets the Base64 encoded shared secret used to sign stateless access and refresh tokens.

Returns:

The Base64 encoded shared secret.

Throws:

ServerException - If any internal server error occurs.

getAllowedResponseTypes

Map<String,ResponseTypeHandler> getAllowedResponseTypes()
                                                       throws UnsupportedResponseTypeException,
                                                              ServerException

Gets the response types allowed by the OAuth2 provider.

Returns:

The allowed response types and their handler implementations.

Throws:

UnsupportedResponseTypeException - If the requested response type is not supported by either the client or the OAuth2 provider.

ServerException - If any internal server error occurs.

isSaveConsentEnabled

boolean isSaveConsentEnabled()

Determines if the consent can be saved or not, due to a lack of configuration.

Returns:

true if the consent can be saved, false if it is not configured properly.

isConsentSaved

boolean isConsentSaved(ResourceOwner resourceOwner,
                       String clientId,
                       Set<String> scope)

Determines whether a resource owner's consent has been saved from a previous authorize request.

Parameters:

resourceOwner - The resource owner.

clientId - The if of the client making the request.

scope - The requested scope.

Returns:

true if the resource owner has previously requested that consent should be saved from the specified client and the exact scope.

validateAuthorizationScope

Set<String> validateAuthorizationScope(ClientRegistration clientRegistration,
                                       Set<String> scope,
                                       OAuth2Request request)
                                throws ServerException,
                                       InvalidScopeException

Provided as an extension point to allow the OAuth2 provider to customise the scope requested when authorization is requested.

Parameters:

clientRegistration - The client registration.

scope - The requested scope.

Returns:

The updated scope used in the remaining OAuth2 process.

Throws:

ServerException - If any internal server error occurs.

InvalidScopeException - If the requested scope is invalid, unknown, or malformed.

validateAccessTokenScope

Set<String> validateAccessTokenScope(ClientRegistration clientRegistration,
                                     Set<String> scope,
                                     OAuth2Request request)
                              throws ServerException,
                                     InvalidScopeException

Provided as an extension point to allow the OAuth2 provider to customise the scope requested when an access token is requested.

Parameters:

clientRegistration - The client registration.

scope - The requested scope.

request - The OAuth2 request.

Returns:

The updated scope used in the remaining OAuth2 process.

Throws:

ServerException - If any internal server error occurs.

InvalidScopeException - If the requested scope is invalid, unknown, or malformed.

validateRefreshTokenScope

Set<String> validateRefreshTokenScope(ClientRegistration clientRegistration,
                                      Set<String> requestedScope,
                                      Set<String> tokenScope,
                                      OAuth2Request request)
                               throws ServerException,
                                      InvalidScopeException

Provided as an extension point to allow the OAuth2 provider to customise the scope requested when a refresh token is requested.

Parameters:

clientRegistration - The client registration.

requestedScope - The requested scope.

tokenScope - The scope from the access token.

request - The OAuth2 request.

Returns:

The updated scope used in the remaining OAuth2 process.

Throws:

ServerException - If any internal server error occurs.

InvalidScopeException - If the requested scope is invalid, unknown, or malformed.

getUserInfo

UserInfoClaims getUserInfo(ClientRegistration clientRegistration,
                           AccessToken token,
                           OAuth2Request request)
                    throws ServerException,
                           UnauthorizedClientException,
                           NotFoundException

Gets the resource owners information based on an issued access token or request.

Parameters:

clientRegistration - The client registration.

token - The access token.

request - The OAuth2 request.

Returns:

The claims for the resource owner's information.

Throws:

ServerException - If any internal server error occurs.

UnauthorizedClientException - If the client's authorization fails.

NotFoundException - If the realm does not have an OAuth 2.0 provider service.

evaluateScope

Map<String,Object> evaluateScope(AccessToken accessToken)
                                throws ServerException

Gets the specified access token's information.

Parameters:

accessToken - The access token.

Returns:

A Map<String, Object> of the access token's information.

Throws:

ServerException - If any internal server error occurs.

additionalDataToReturnFromAuthorizeEndpoint

Map<String,String> additionalDataToReturnFromAuthorizeEndpoint(Map<String,Token> tokens,
                                                                     OAuth2Request request)
                                                              throws ServerException

Provided as an extension point to allow the OAuth2 provider to return additional data from an authorization request.

Parameters:

tokens - The tokens that will be returned from the authorization call.

request - The OAuth2 request.

Returns:

A Map<String, String> of the additional data to return.

Throws:

ServerException - If any internal server error occurs.

additionalDataToReturnFromTokenEndpoint

void additionalDataToReturnFromTokenEndpoint(AccessToken accessToken,
                                             OAuth2Request request)
                                      throws ServerException,
                                             InvalidClientException,
                                             NotFoundException

Provided as an extension point to allow the OAuth2 provider to return additional data from an access token request.
Any additional data to be returned should be added to the access token by invoking, AccessToken#addExtraData(String, String).

Parameters:

accessToken - The access token.

request - The OAuth2 request.

Throws:

ServerException - If any internal server error occurs.

InvalidClientException - If either the request does not contain the client's id or the client fails to be authenticated.

NotFoundException - If the realm does not have an OAuth 2.0 provider service.

saveConsent

void saveConsent(ResourceOwner resourceOwner,
                 String clientId,
                 Set<String> scope)

Saves the resource owner's consent for the granting authorization for the specified client with the specified scope.

Parameters:

resourceOwner - The resource owner.

clientId - The client id.

scope - The requested scope.

revokeConsent

void revokeConsent(String userId,
                   String clientId)

Revokes the resource owner's consent for the granting authorization for the specified client.

Parameters:

userId - The user id.

clientId - The client id.

issueRefreshTokens

boolean issueRefreshTokens()
                    throws ServerException

Whether the OAuth2 provider should issue refresh tokens when issuing access tokens.

Returns:

true if refresh tokens should be issued.

Throws:

ServerException - If any internal server error occurs.

issueRefreshTokensOnRefreshingToken

boolean issueRefreshTokensOnRefreshingToken()
                                     throws ServerException

Whether the OAuth2 provider should issue refresh tokens when refreshing access tokens.

Returns:

true if refresh tokens should be issued when access tokens are refreshed.

Throws:

ServerException - If any internal server error occurs.

getAuthorizationCodeLifetime

long getAuthorizationCodeLifetime()
                           throws ServerException

Gets the lifetime an authorization code will have before it expires.

Returns:

The lifetime of an authorization code in seconds.

Throws:

ServerException - If any internal server error occurs.

getAccessTokenLifetime

long getAccessTokenLifetime()
                     throws ServerException

Gets the lifetime an access token will have before it expires.

Returns:

The lifetime of an access token in seconds.

Throws:

ServerException - If any internal server error occurs.

getOpenIdTokenLifetime

long getOpenIdTokenLifetime()
                     throws ServerException

Gets the lifetime an OpenID token will have before it expires.

Returns:

The lifetime of an OpenID token in seconds.

Throws:

ServerException - If any internal server error occurs.

getRefreshTokenLifetime

long getRefreshTokenLifetime()
                      throws ServerException

Gets the lifetime an refresh token will have before it expires.

Returns:

The lifetime of an refresh token in seconds.

Throws:

ServerException - If any internal server error occurs.

getSigningKeyPair

KeyPair getSigningKeyPair(org.forgerock.json.jose.jws.JwsAlgorithm algorithm)
                   throws ServerException

Gets the signing key pair of the OAuth2 provider.

Parameters:

algorithm - The signing algorithm.

Returns:

The KeyPair.

Throws:

ServerException - If any internal server error occurs.

getResourceOwnerAuthenticatedAttributes

Set<String> getResourceOwnerAuthenticatedAttributes()
                                             throws ServerException

Gets the attributes of the resource owner that are used for authenticating resource owners.

Returns:

A Set of resource owner attributes.

Throws:

ServerException - If any internal server error occurs.

getSupportedClaims

Set<String> getSupportedClaims()
                        throws ServerException

Gets the supported claims for this provider.

Returns:

A Set of the supported claims.

Throws:

ServerException - If any internal server error occurs.

getSupportedClaimsWithTranslations

Set<String> getSupportedClaimsWithTranslations()
                                        throws ServerException

Gets the supported claims for this provider as strings with pipe-separated translations.

Returns:

A Set of the supported claims.

Throws:

ServerException - If any internal server error occurs.

getSupportedScopes

Set<String> getSupportedScopes()
                        throws ServerException

Gets the supported scopes for this provider without translations.

Returns:

A Set of the supported scopes.

Throws:

ServerException - If any internal server error occurs.

getSupportedScopesWithTranslations

Set<String> getSupportedScopesWithTranslations()
                                        throws ServerException

Gets the supported scopes for this provider.

Returns:

A Set of the supported scopes.

Throws:

ServerException - If any internal server error occurs.

getDefaultScopes

Set<String> getDefaultScopes()
                      throws ServerException

Gets the default set of scopes to give a client registering with this provider.

Returns:

A Set of the default scopes.

Throws:

ServerException - If any internal server error occurs.

getSupportedIDTokenSigningAlgorithms

Set<String> getSupportedIDTokenSigningAlgorithms()
                                          throws ServerException

Gets the algorithms that the OAuth2 provider supports for signing OpenID tokens.

Returns:

A Set of the supported algorithms.

Throws:

ServerException - If any internal server error occurs.

getSupportedIDTokenEncryptionAlgorithms

Set<String> getSupportedIDTokenEncryptionAlgorithms()
                                             throws ServerException

Gets the algorithms that the OAuth2 provider supports for encryptin OpenID tokens.

Returns:

A Set of the supported algorithms.

Throws:

ServerException - If any internal server error occurs.

getSupportedIDTokenEncryptionMethods

Set<String> getSupportedIDTokenEncryptionMethods()
                                          throws ServerException

Gets the encryption methods that the OAuth2 provider supports for encryptin OpenID tokens.

Returns:

A Set of the supported algorithms.

Throws:

ServerException - If any internal server error occurs.

getOpenIDConnectVersion

String getOpenIDConnectVersion()

Gets the supported version of the OpenID Connect specification.

Returns:

The OpenID Connect version.

getJWKSet

org.forgerock.json.JsonValue getJWKSet()
                                throws ServerException

Gets the JWK Set for this OAuth2 Authorization /OpenID Provider.

Returns:

The JWK Set of signing and encryption keys.

Throws:

ServerException

getCreatedTimestampAttributeName

String getCreatedTimestampAttributeName()
                                 throws ServerException

Gets the created timestamp attribute name.

Returns:

The created attribute timestamp attribute name.

Throws:

ServerException

getModifiedTimestampAttributeName

String getModifiedTimestampAttributeName()
                                  throws ServerException

Gets the modified timestamp attribute name.

Returns:

The modified attribute timestamp attribute name.

Throws:

ServerException

getSupportedSubjectTypes

Set<String> getSupportedSubjectTypes()
                              throws ServerException

Gets the subject types supported by the OAuth2 provider.

Returns:

A Set of supported subject types.

Throws:

ServerException - If any internal server error occurs.

isOpenDynamicClientRegistrationAllowed

boolean isOpenDynamicClientRegistrationAllowed()
                                        throws ServerException

Indicates whether clients may register without providing an access token.

Returns:

true if allowed, otherwise false.

Throws:

ServerException - If any internal server error occurs.

isRegistrationAccessTokenGenerationEnabled

boolean isRegistrationAccessTokenGenerationEnabled()
                                            throws ServerException

Whether to generate access tokens for clients that register without one. Only enabled if isOpenDynamicClientRegistrationAllowed() is true.

Returns:

true if an access token should be generated for clients that register without one.

Throws:

ServerException - If any internal server error occurs.

getAcrMapping

Map<String,AuthenticationMethod> getAcrMapping()
                                              throws ServerException

Returns a mapping from Authentication Context Class Reference (ACR) values (typically a Level of Assurance value) to concrete authentication methods.

Throws:

ServerException

getDefaultAcrValues

String getDefaultAcrValues()
                    throws ServerException

The default Authentication Context Class Reference (ACR) values to use for authentication if none is specified in the request. This is a space-separated list of values in preference order.

Throws:

ServerException

getAMRAuthModuleMappings

Map<String,String> getAMRAuthModuleMappings()
                                           throws ServerException

The mappings between amr values and auth module names.

Returns:

The mappings.

Throws:

ServerException

exists

boolean exists()

Checks whether the config exists.

Returns:

Whether it exists.

getResourceSetStore

ResourceSetStore getResourceSetStore()

Returns the ResourceSetStore instance for the realm.

Returns:

The ResourceSetStore instance.

getClaimsParameterSupported

boolean getClaimsParameterSupported()
                             throws ServerException

Returns whether this provider supports claims requested via 'claims' parameter.

Returns:

true or false.

Throws:

ServerException

validateRequestedClaims

String validateRequestedClaims(String requestedClaims)
                        throws InvalidRequestException,
                               ServerException

Validates that the requested claims are appropriate to be requested by the given client.

Throws:

InvalidRequestException

ServerException

getEndpointAuthMethodsSupported

Set<String> getEndpointAuthMethodsSupported()

Returns the token_endpoint_auth_methods available for clients to register (and subsequently auth) using.

isCodeVerifierRequired

boolean isCodeVerifierRequired()
                        throws ServerException

Whether or not to enforce the Code Verifier Parameter.

Returns:

Whether the Code Verifier option has been configured.

Throws:

ServerException

See Also:

getHashSalt

String getHashSalt()
            throws ServerException

Returns the salt to use for hashing sub values upon pairwise requests.

Throws:

ServerException

isAlwaysAddClaimsToToken

boolean isAlwaysAddClaimsToToken()
                          throws ServerException

Whether to always add claims to id_tokens - non-spec compliant.

Throws:

ServerException

See Also:

OpenID Connect Specification

getUserDisplayNameAttribute

String getUserDisplayNameAttribute()
                            throws ServerException

The attribute that can be used to obtain a UI-displayable name for a user's AMIdentity.

Throws:

ServerException

getJWKSUri

String getJWKSUri()
           throws ServerException

Gets the JSON Web Key Set URI.

Returns:

The JWKS URI.

Throws:

ServerException - If any internal server error occurs.

getCustomLoginUrlTemplate

freemarker.template.Template getCustomLoginUrlTemplate()
                                                throws ServerException

Gets the custom login url template which will create the url to redirect resource owners to for authentication.

Returns:

The custom login url template.

Throws:

ServerException - If the custom login url template setting could not be retrieved.

getVerificationUrl

String getVerificationUrl()
                   throws ServerException

The URL that the user will be instructed to visit to complete their OAuth 2 login and consent when using the device code flow.

Returns:

The verification URL.

Throws:

ServerException - If the setting could not be retrieved.

getCompletionUrl

String getCompletionUrl()
                 throws ServerException

The URL that the user will be sent to on completion of their OAuth 2 login and consent when using the device code flow.

Returns:

The completion URL.

Throws:

ServerException - If the setting could not be retrieved.

getDeviceCodeLifetime

int getDeviceCodeLifetime()
                   throws ServerException

The lifetime of the device code.

Returns:

The lifetime in seconds.

Throws:

ServerException - If the setting could not be retrieved.

getDeviceCodePollInterval

int getDeviceCodePollInterval()
                       throws ServerException

The polling interval for devices waiting for tokens when using the device code flow.

Returns:

The interval in seconds.

Throws:

ServerException - If the setting could not be retrieved.

shouldStoreOpsTokens

boolean shouldStoreOpsTokens()
                      throws ServerException

Whether to generate and store an ops token in CTS for this OIDC provider.

Returns:

true if ops tokens should be generated/stored in CTS.

Throws:

ServerException - If the setting could not be retrieved.

clientsCanSkipConsent

boolean clientsCanSkipConsent()
                       throws ServerException

Whether clients can opt to skip resource owner consent during authorization flows.

Returns:

true if clients are allowed to opt to skip resource owner consent.

Throws:

ServerException - If the setting could not be retrieved.

isOpenIDConnectSSOProviderEnabled

boolean isOpenIDConnectSSOProviderEnabled()
                                   throws ServerException

Whether OpenID Connect ID Tokens are accepted as SSOTokens in this realm or not.

Returns:

true if ID Tokens are accepted as SSOTokens in this realm.

Throws:

ServerException - If the setting could not be retrieved.