ConsumerManager (OpenID4Java no dependencies 0.9.6-wso2v5 API)

java.lang.Object
- org.openid4java.consumer.ConsumerManager

```
public class ConsumerManager
extends 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

Constructors
Constructor and Description
`ConsumerManager()` Instantiates a ConsumerManager with default settings.
`ConsumerManager(RealmVerifierFactory realmFactory, Discovery discovery, HttpFetcherFactory httpFetcherFactory)`

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`allowStateless(boolean allowStateless)` Deprecated.
`DiscoveryInformation`	`associate(List discoveries)` Tries to establish an association with on of the service endpoints in the list of DiscoveryInformation.
`AuthRequest`	`authenticate(DiscoveryInformation discovered, String returnToUrl)` Builds a authentication request message for the user specified in the discovery information provided as a parameter.
`AuthRequest`	`authenticate(DiscoveryInformation discovered, String returnToUrl, String realm)` Builds a authentication request message for the user specified in the discovery information provided as a parameter.
`AuthRequest`	`authenticate(List discoveries, String returnToUrl)` Builds a authentication request message for the user specified in the discovery information provided as a parameter.
`AuthRequest`	`authenticate(List discoveries, String returnToUrl, String realm)` Builds a authentication request message for the user specified in the discovery information provided as a parameter.
`List`	`discover(String identifier)` Does discovery on an identifier.
`String`	`extractConsumerNonce(String returnTo, String opUrl)` Extracts the consumer-side nonce from the return_to parameter in authentication response from a OpenID 1.1 Provider.
`Map`	`extractQueryParams(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.
`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.
`String`	`insertConsumerNonce(String opUrl, 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(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(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(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
  - getDHParams
```
public DHParameterSpec getDHParams()
```
    Gets the Diffie-Hellman base parameters (modulus and generator).
    
    See Also:
    DiffieHellmanSession
  - setDHParams
```
public void setDHParams(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
  - 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()
  - 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.
  - 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)
  - 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.
  - 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.
  - getMinAssocSessEnc
```
public AssociationSessionType getMinAssocSessEnc()
```
    Gets the minimum level of encryption that will be accepted for association sessions.
    Default: no-encryption session, SHA1 MAC association
  - 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)
  - getPrefAssocSessEnc
```
public AssociationSessionType getPrefAssocSessEnc()
```
    Gets the preferred encryption type for the association sessions.
  - setPrefAssocSessEnc
```
public void setPrefAssocSessEnc(AssociationSessionType prefAssocSessEnc)
```
    Sets the preferred encryption type for the association sessions.
    Default: DH-SHA256
  - getFailedAssocExpire
```
public int getFailedAssocExpire()
```
    Gets the timeout (in seconds) configured for keeping track of failed association attempts.
    See also: setFailedAssocExpire(int)
  - 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
  - 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.
  - isImmediateAuth
```
public boolean isImmediateAuth()
```
    Returns true if the ConsumerManager is configured to attempt checkid_immediate authentication requests.
    Default: false
  - setImmediateAuth
```
public void setImmediateAuth(boolean _immediateAuth)
```
    Configures the authentication request mode: checkid_immediate (true) or checkid_setup (false).
    Default: false / checkid_setup
  - 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 List discover(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.
  - getPrivateAssociationStore
```
public ConsumerAssociationStore getPrivateAssociationStore()
```
    Gets the private association store used for signing consumer nonces.
    
    See Also:
    setPrivateAssociationStore(ConsumerAssociationStore)
  - 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
  - setConnectTimeout
```
public void setConnectTimeout(int connectTimeout)
```
  - setSocketTimeout
```
public void setSocketTimeout(int socketTimeout)
```
  - setMaxRedirects
```
public void setMaxRedirects(int maxRedirects)
```
  - associate
```
public DiscoveryInformation associate(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(List discoveries,
                       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(List discoveries,
                       String returnToUrl,
                       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,
                       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,
                       String returnToUrl,
                       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(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:
    - nonce: the same assertion will not be accepted more than once
    - signatures: verifies that the message was indeed sent by the OpenID Provider that was contacted earlier after discovery
    - discovered information: the information contained in the assertion matches the one obtained during the discovery (the OpenID Provider is authoritative for the claimed identifier; the received assertion is not meaningful otherwise
    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(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 Map extractQueryParams(URL url)
                       throws 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:
    
    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 String insertConsumerNonce(String opUrl,
                         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 String extractConsumerNonce(String returnTo,
                          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.

Class ConsumerManager

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ConsumerManager

ConsumerManager

Method Detail

getDiscovery

setDiscovery

getAssociations

setAssociations

getNonceVerifier

setNonceVerifier

getDHParams

setDHParams

getMaxAssocAttempts

setMaxAssocAttempts

allowStateless

statelessAllowed

isAllowStateless

setAllowStateless

getMinAssocSessEnc

setMinAssocSessEnc

getPrefAssocSessEnc

setPrefAssocSessEnc

getFailedAssocExpire

setFailedAssocExpire

getPreExpiryAssocLockInterval

setPreExpiryAssocLockInterval

isImmediateAuth

setImmediateAuth

getRealmVerifier

setRealmVerifier

getMaxNonceAge

setMaxNonceAge

discover

getPrivateAssociationStore

setPrivateAssociationStore

setConnectTimeout

setSocketTimeout

setMaxRedirects

associate

authenticate

authenticate

authenticate

authenticate

verify

verifyReturnTo

extractQueryParams

verifyNonce

insertConsumerNonce

extractConsumerNonce