org.openid4java.consumer
Class ConsumerManager

java.lang.Object
  extended by org.openid4java.consumer.ConsumerManager

public class ConsumerManager
extends java.lang.Object

Manages OpenID communications with an OpenID Provider (Server).

The Consumer site needs to have the same instance of this class throughout the lifecycle of a OpenID authentication session.

Author:
Marius Scurtescu, Johnny Bufu

Constructor Summary
ConsumerManager()
          Instantiates a ConsumerManager with default settings.
ConsumerManager(RealmVerifierFactory realmFactory, Discovery discovery, HttpFetcherFactory httpFetcherFactory)
           
 
Method Summary
 void allowStateless(boolean allowStateless)
          Deprecated.  
 DiscoveryInformation associate(java.util.List discoveries)
          Tries to establish an association with on of the service endpoints in the list of DiscoveryInformation.
 AuthRequest authenticate(DiscoveryInformation discovered, java.lang.String returnToUrl)
          Builds a authentication request message for the user specified in the discovery information provided as a parameter.
 AuthRequest authenticate(DiscoveryInformation discovered, java.lang.String returnToUrl, java.lang.String realm)
          Builds a authentication request message for the user specified in the discovery information provided as a parameter.
 AuthRequest authenticate(java.util.List discoveries, java.lang.String returnToUrl)
          Builds a authentication request message for the user specified in the discovery information provided as a parameter.
 AuthRequest authenticate(java.util.List discoveries, java.lang.String returnToUrl, java.lang.String realm)
          Builds a authentication request message for the user specified in the discovery information provided as a parameter.
 java.util.List discover(java.lang.String identifier)
          Does discovery on an identifier.
 java.lang.String extractConsumerNonce(java.lang.String returnTo, java.lang.String opUrl)
          Extracts the consumer-side nonce from the return_to parameter in authentication response from a OpenID 1.1 Provider.
 java.util.Map extractQueryParams(java.net.URL url)
          Returns a Map(key, List(values)) with the URL's query params, or null if the URL doesn't have a query string.
 ConsumerAssociationStore getAssociations()
          Gets the association store that holds established associations with OpenID providers.
 javax.crypto.spec.DHParameterSpec getDHParams()
          Gets the Diffie-Hellman base parameters (modulus and generator).
 Discovery getDiscovery()
          Returns discovery process manager.
 int getFailedAssocExpire()
          Gets the timeout (in seconds) configured for keeping track of failed association attempts.
 int getMaxAssocAttempts()
          Gets the value configured for the maximum number of association attempts that will be performed for a given OpenID provider.
 int getMaxNonceAge()
          Gets the max age (in seconds) configured for keeping track of nonces.
 AssociationSessionType getMinAssocSessEnc()
          Gets the minimum level of encryption that will be accepted for association sessions.
 NonceVerifier getNonceVerifier()
          Gets the NonceVerifier implementation used to keep track of the nonces that have been seen in authentication response messages.
 int getPreExpiryAssocLockInterval()
          Gets the interval before the expiration of an association (in seconds) in which the association should not be used, in order to avoid the expiration from occurring in the middle of a authentication transaction.
 AssociationSessionType getPrefAssocSessEnc()
          Gets the preferred encryption type for the association sessions.
 ConsumerAssociationStore getPrivateAssociationStore()
          Gets the private association store used for signing consumer nonces.
 RealmVerifier getRealmVerifier()
          Gets the RealmVerifier used to verify realms against return_to URLs.
 java.lang.String insertConsumerNonce(java.lang.String opUrl, java.lang.String returnTo)
          Inserts a consumer-side nonce as a custom parameter in the return_to parameter of the authentication request.
 boolean isAllowStateless()
          Returns true if the ConsumerManager is configured to fallback to stateless mode when failing to associate with an OpenID Provider.
 boolean isImmediateAuth()
          Returns true if the ConsumerManager is configured to attempt checkid_immediate authentication requests.
 void setAllowStateless(boolean allowStateless)
          Flag used to enable / disable the use of stateless mode.
 void setAssociations(ConsumerAssociationStore associations)
          Configures the ConsumerAssociationStore that will be used to store the associations established with OpenID providers.
 void setConnectTimeout(int connectTimeout)
           
 void setDHParams(javax.crypto.spec.DHParameterSpec dhParams)
          Sets the Diffie-Hellman base parameters that will be used for encoding the MAC key exchange.
 void setDiscovery(Discovery discovery)
          Sets discovery process manager.
 void setFailedAssocExpire(int _failedAssocExpire)
          Sets the expiration timeout (in seconds) for keeping track of failed association attempts.
 void setImmediateAuth(boolean _immediateAuth)
          Configures the authentication request mode: checkid_immediate (true) or checkid_setup (false).
 void setMaxAssocAttempts(int maxAssocAttempts)
          Maximum number of attempts (HTTP calls) the RP is willing to make for trying to establish an association with the OP.
 void setMaxNonceAge(int ageSeconds)
          Sets the max age (in seconds) configured for keeping track of nonces.
 void setMaxRedirects(int maxRedirects)
           
 void setMinAssocSessEnc(AssociationSessionType minAssocSessEnc)
          Configures the minimum level of encryption accepted for association sessions.
 void setNonceVerifier(NonceVerifier nonceVerifier)
          Configures the NonceVerifier that will be used to keep track of the nonces in the authentication response messages.
 void setPreExpiryAssocLockInterval(int preExpiryAssocLockInterval)
          Sets the interval before the expiration of an association (in seconds) in which the association should not be used, in order to avoid the expiration from occurring in the middle of a authentication transaction.
 void setPrefAssocSessEnc(AssociationSessionType prefAssocSessEnc)
          Sets the preferred encryption type for the association sessions.
 void setPrivateAssociationStore(ConsumerAssociationStore associations)
          Configures a private association store for signing consumer nonces.
 void setRealmVerifier(RealmVerifier realmVerifier)
          Sets the RealmVerifier used to verify realms against return_to URLs.
 void setSocketTimeout(int socketTimeout)
           
 boolean statelessAllowed()
          Deprecated.  
 VerificationResult verify(java.lang.String receivingUrl, ParameterList response, DiscoveryInformation discovered)
          Performs verification on the Authentication Response (assertion) received from the OpenID Provider.
 boolean verifyNonce(AuthSuccess authResp, DiscoveryInformation discovered)
          Verifies the nonce in an authentication response.
 boolean verifyReturnTo(java.lang.String receivingUrl, AuthSuccess response)
          Verifies that the URL where the Consumer (Relying Party) received the authentication response matches the value of the "openid.return_to" parameter in the authentication response.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ConsumerManager

public ConsumerManager()
Instantiates a ConsumerManager with default settings.


ConsumerManager

@Inject
public ConsumerManager(RealmVerifierFactory realmFactory,
                              Discovery discovery,
                              HttpFetcherFactory httpFetcherFactory)
Method Detail

getDiscovery

public Discovery getDiscovery()
Returns discovery process manager.

Returns:
discovery process manager.

setDiscovery

public void setDiscovery(Discovery discovery)
Sets discovery process manager.

Parameters:
discovery - discovery process manager.

getAssociations

public ConsumerAssociationStore getAssociations()
Gets the association store that holds established associations with OpenID providers.

See Also:
ConsumerAssociationStore

setAssociations

@Inject
public void setAssociations(ConsumerAssociationStore associations)
Configures the ConsumerAssociationStore that will be used to store the associations established with OpenID providers.

Parameters:
associations - ConsumerAssociationStore implementation
See Also:
ConsumerAssociationStore

getNonceVerifier

public NonceVerifier getNonceVerifier()
Gets the NonceVerifier implementation used to keep track of the nonces that have been seen in authentication response messages.

See Also:
NonceVerifier

setNonceVerifier

@Inject
public void setNonceVerifier(NonceVerifier nonceVerifier)
Configures the NonceVerifier that will be used to keep track of the nonces in the authentication response messages.

Parameters:
nonceVerifier - NonceVerifier implementation
See Also:
NonceVerifier

setDHParams

public void setDHParams(javax.crypto.spec.DHParameterSpec dhParams)
Sets the Diffie-Hellman base parameters that will be used for encoding the MAC key exchange.

If not provided the default set specified by the Diffie-Hellman algorithm will be used.

Parameters:
dhParams - Object encapsulating modulus and generator numbers
See Also:
DiffieHellmanSession

getDHParams

public javax.crypto.spec.DHParameterSpec getDHParams()
Gets the Diffie-Hellman base parameters (modulus and generator).

See Also:
DiffieHellmanSession

setMaxAssocAttempts

public void setMaxAssocAttempts(int maxAssocAttempts)
Maximum number of attempts (HTTP calls) the RP is willing to make for trying to establish an association with the OP. Default: 4; 0 = don't use associations Associations and stateless mode cannot be both disabled at the same time.


getMaxAssocAttempts

public int getMaxAssocAttempts()
Gets the value configured for the maximum number of association attempts that will be performed for a given OpenID provider.

If an association cannot be established after this number of attempts the ConsumerManager will fallback to stateless mode, provided the #allowStateless preference is enabled.

See also: allowStateless(boolean) statelessAllowed()


allowStateless

public void allowStateless(boolean allowStateless)
Deprecated. 

Flag used to enable / disable the use of stateless mode.

Default: enabled.

Associations and stateless mode cannot be both disabled at the same time.

See Also:
setAllowStateless(boolean)

setAllowStateless

public void setAllowStateless(boolean allowStateless)
Flag used to enable / disable the use of stateless mode.

Default: enabled.

Associations and stateless mode cannot be both disabled at the same time.


statelessAllowed

public boolean statelessAllowed()
Deprecated. 

Returns true if the ConsumerManager is configured to fallback to stateless mode when failing to associate with an OpenID Provider.

See Also:
isAllowStateless()

isAllowStateless

public boolean isAllowStateless()
Returns true if the ConsumerManager is configured to fallback to stateless mode when failing to associate with an OpenID Provider.


setMinAssocSessEnc

public void setMinAssocSessEnc(AssociationSessionType minAssocSessEnc)
Configures the minimum level of encryption accepted for association sessions.

Default: no-encryption session, SHA1 MAC association.

See also: allowStateless(boolean)


getMinAssocSessEnc

public AssociationSessionType getMinAssocSessEnc()
Gets the minimum level of encryption that will be accepted for association sessions.

Default: no-encryption session, SHA1 MAC association


setPrefAssocSessEnc

public void setPrefAssocSessEnc(AssociationSessionType prefAssocSessEnc)
Sets the preferred encryption type for the association sessions.

Default: DH-SHA256


getPrefAssocSessEnc

public AssociationSessionType getPrefAssocSessEnc()
Gets the preferred encryption type for the association sessions.


setFailedAssocExpire

public void setFailedAssocExpire(int _failedAssocExpire)
Sets the expiration timeout (in seconds) for keeping track of failed association attempts.

If an association cannot be establish with an OP, subsequesnt authentication request to that OP will not try to establish an association within the timeout period configured here.

Default: 300s 0 = disabled (attempt to establish an association with every authentication request)

Parameters:
_failedAssocExpire - time in seconds to remember failed association attempts

getFailedAssocExpire

public int getFailedAssocExpire()
Gets the timeout (in seconds) configured for keeping track of failed association attempts.

See also: setFailedAssocExpire(int)


getPreExpiryAssocLockInterval

public int getPreExpiryAssocLockInterval()
Gets the interval before the expiration of an association (in seconds) in which the association should not be used, in order to avoid the expiration from occurring in the middle of a authentication transaction. Default: 300s.


setPreExpiryAssocLockInterval

public void setPreExpiryAssocLockInterval(int preExpiryAssocLockInterval)
Sets the interval before the expiration of an association (in seconds) in which the association should not be used, in order to avoid the expiration from occurring in the middle of a authentication transaction. Default: 300s.

Parameters:
preExpiryAssocLockInterval - The number of seconds for the pre-expiry lock inteval.

setImmediateAuth

public void setImmediateAuth(boolean _immediateAuth)
Configures the authentication request mode: checkid_immediate (true) or checkid_setup (false).

Default: false / checkid_setup


isImmediateAuth

public boolean isImmediateAuth()
Returns true if the ConsumerManager is configured to attempt checkid_immediate authentication requests.

Default: false


getRealmVerifier

public RealmVerifier getRealmVerifier()
Gets the RealmVerifier used to verify realms against return_to URLs.


setRealmVerifier

public void setRealmVerifier(RealmVerifier realmVerifier)
Sets the RealmVerifier used to verify realms against return_to URLs.


getMaxNonceAge

public int getMaxNonceAge()
Gets the max age (in seconds) configured for keeping track of nonces.

Nonces older than the max age will be removed from the store and authentication responses will be considered failures.


setMaxNonceAge

public void setMaxNonceAge(int ageSeconds)
Sets the max age (in seconds) configured for keeping track of nonces.

Nonces older than the max age will be removed from the store and authentication responses will be considered failures.


discover

public java.util.List discover(java.lang.String identifier)
                        throws DiscoveryException
Does discovery on an identifier. It delegates the call to its discovery manager.

Returns:
A List of DiscoveryInformation objects. The list could be empty if no discovery information can be retrieved.
Throws:
DiscoveryException - if the discovery process runs into errors.

setPrivateAssociationStore

public void setPrivateAssociationStore(ConsumerAssociationStore associations)
                                throws ConsumerException
Configures a private association store for signing consumer nonces.

Consumer nonces are needed to prevent replay attacks in compatibility mode, because OpenID 1.x Providers to not attach nonces to authentication responses.

One way for the Consumer to know that a consumer nonce in an authentication response was indeed issued by itself (and thus prevent denial of service attacks), is by signing them.

Parameters:
associations - The association store to be used for signing consumer nonces; signing can be deactivated by setting this to null. Signing is enabled by default.
Throws:
ConsumerException

getPrivateAssociationStore

public ConsumerAssociationStore getPrivateAssociationStore()
Gets the private association store used for signing consumer nonces.

See Also:
setPrivateAssociationStore(ConsumerAssociationStore)

setConnectTimeout

public void setConnectTimeout(int connectTimeout)

setSocketTimeout

public void setSocketTimeout(int socketTimeout)

setMaxRedirects

public void setMaxRedirects(int maxRedirects)

associate

public DiscoveryInformation associate(java.util.List discoveries)
Tries to establish an association with on of the service endpoints in the list of DiscoveryInformation.

Iterates over the items in the discoveries parameter a maximum of #_maxAssocAttempts times trying to esablish an association.

Parameters:
discoveries - The DiscoveryInformation list obtained by performing dicovery on the User-supplied OpenID identifier. Should be ordered by the priority of the service endpoints.
Returns:
The DiscoveryInformation instance with which an association was established, or the one with the highest priority if association failed.
See Also:
Discovery.discover(org.openid4java.discovery.Identifier)

authenticate

public AuthRequest authenticate(java.util.List discoveries,
                                java.lang.String returnToUrl)
                         throws ConsumerException,
                                MessageException
Builds a authentication request message for the user specified in the discovery information provided as a parameter.

If the discoveries parameter contains more than one entry, it will iterate over them trying to establish an association. If an association cannot be established, the first entry is used with stateless mode.

Parameters:
discoveries - The DiscoveryInformation list obtained by performing dicovery on the User-supplied OpenID identifier. Should be ordered by the priority of the service endpoints.
returnToUrl - The URL on the Consumer site where the OpenID Provider will return the user after generating the authentication response.
Null if the Consumer does not with to for the End User to be returned to it (something else useful will have been performed via an extension).
Must not be null in OpenID 1.x compatibility mode.
Returns:
Authentication request message to be sent to the OpenID Provider.
Throws:
ConsumerException
MessageException
See Also:
associate(java.util.List)

authenticate

public AuthRequest authenticate(java.util.List discoveries,
                                java.lang.String returnToUrl,
                                java.lang.String realm)
                         throws ConsumerException,
                                MessageException
Builds a authentication request message for the user specified in the discovery information provided as a parameter.

If the discoveries parameter contains more than one entry, it will iterate over them trying to establish an association. If an association cannot be established, the first entry is used with stateless mode.

Parameters:
discoveries - The DiscoveryInformation list obtained by performing dicovery on the User-supplied OpenID identifier. Should be ordered by the priority of the service endpoints.
returnToUrl - The URL on the Consumer site where the OpenID Provider will return the user after generating the authentication response.
Null if the Consumer does not with to for the End User to be returned to it (something else useful will have been performed via an extension).
Must not be null in OpenID 1.x compatibility mode.
realm - The URL pattern that will be presented to the user when he/she will be asked to authorize the authentication transaction. Must be a super-set of the @returnToUrl.
Returns:
Authentication request message to be sent to the OpenID Provider.
Throws:
ConsumerException
MessageException
See Also:
associate(java.util.List)

authenticate

public AuthRequest authenticate(DiscoveryInformation discovered,
                                java.lang.String returnToUrl)
                         throws MessageException,
                                ConsumerException
Builds a authentication request message for the user specified in the discovery information provided as a parameter.

Parameters:
discovered - A DiscoveryInformation endpoint from the list obtained by performing dicovery on the User-supplied OpenID identifier.
returnToUrl - The URL on the Consumer site where the OpenID Provider will return the user after generating the authentication response.
Null if the Consumer does not with to for the End User to be returned to it (something else useful will have been performed via an extension).
Must not be null in OpenID 1.x compatibility mode.
Returns:
Authentication request message to be sent to the OpenID Provider.
Throws:
MessageException
ConsumerException

authenticate

public AuthRequest authenticate(DiscoveryInformation discovered,
                                java.lang.String returnToUrl,
                                java.lang.String realm)
                         throws MessageException,
                                ConsumerException
Builds a authentication request message for the user specified in the discovery information provided as a parameter.

Parameters:
discovered - A DiscoveryInformation endpoint from the list obtained by performing dicovery on the User-supplied OpenID identifier.
returnToUrl - The URL on the Consumer site where the OpenID Provider will return the user after generating the authentication response.
Null if the Consumer does not with to for the End User to be returned to it (something else useful will have been performed via an extension).
Must not be null in OpenID 1.x compatibility mode.
realm - The URL pattern that will be presented to the user when he/she will be asked to authorize the authentication transaction. Must be a super-set of the @returnToUrl.
Returns:
Authentication request message to be sent to the OpenID Provider.
Throws:
MessageException
ConsumerException

verify

public VerificationResult verify(java.lang.String receivingUrl,
                                 ParameterList response,
                                 DiscoveryInformation discovered)
                          throws MessageException,
                                 DiscoveryException,
                                 AssociationException
Performs verification on the Authentication Response (assertion) received from the OpenID Provider.

Three verification steps are performed:

Parameters:
receivingUrl - The URL where the Consumer (Relying Party) has accepted the incoming message.
response - ParameterList of the authentication response being verified.
discovered - Previously discovered information (which can therefore be trusted) obtained during the discovery phase; this should be stored and retrieved by the RP in the user's session.
Returns:
A VerificationResult, containing a verified identifier; the verified identifier is null if the verification failed).
Throws:
MessageException
DiscoveryException
AssociationException

verifyReturnTo

public boolean verifyReturnTo(java.lang.String receivingUrl,
                              AuthSuccess response)
Verifies that the URL where the Consumer (Relying Party) received the authentication response matches the value of the "openid.return_to" parameter in the authentication response.

Parameters:
receivingUrl - The URL where the Consumer received the authentication response.
response - The authentication response.
Returns:
True if the two URLs match, false otherwise.

extractQueryParams

public java.util.Map extractQueryParams(java.net.URL url)
                                 throws java.io.UnsupportedEncodingException
Returns a Map(key, List(values)) with the URL's query params, or null if the URL doesn't have a query string.

Throws:
java.io.UnsupportedEncodingException

verifyNonce

public boolean verifyNonce(AuthSuccess authResp,
                           DiscoveryInformation discovered)
Verifies the nonce in an authentication response.

Parameters:
authResp - The authentication response containing the nonce to be verified.
discovered - The discovery information associated with the authentication transaction.
Returns:
True if the nonce is valid, false otherwise.

insertConsumerNonce

public java.lang.String insertConsumerNonce(java.lang.String opUrl,
                                            java.lang.String returnTo)
Inserts a consumer-side nonce as a custom parameter in the return_to parameter of the authentication request.

Needed for preventing replay attack when running compatibility mode. OpenID 1.1 OpenID Providers do not generate nonces in authentication responses.

Parameters:
opUrl - The endpoint to be used for private association.
returnTo - The return_to URL to which a custom nonce parameter will be added.
Returns:
The return_to URL containing the nonce.

extractConsumerNonce

public java.lang.String extractConsumerNonce(java.lang.String returnTo,
                                             java.lang.String opUrl)
Extracts the consumer-side nonce from the return_to parameter in authentication response from a OpenID 1.1 Provider.

Parameters:
returnTo - return_to URL from the authentication response
opUrl - URL for the appropriate OP endpoint
Returns:
The nonce found in the return_to URL, or null if it wasn't found.


Copyright © 2011 Sxip. All Rights Reserved.