Basic Auth refers to the classic authentication method, where in order to authenticate with your API users simply provide the Anypoint™ Connector their username and password. This is also the scheme you want to use if your API relies on Basic Auth, using atypical values for the username and password. For instance, an API that uses a security token on top of the username and password would still use Basic Auth for its connecting applications.
The Anypoint DevKit Basic Auth framework provides multi-tenancy capabilities for a connector (managing multiple simultaneous connections with different credentials for a given connector within your application), as well as connection pooling and instance pooling. These benefits are available for most authentication schemes other than OAuth, and for APIs that do not require authentication.
This document describes the benefits of using the Basic Auth framework, the Java annotations through which it is exposed, and how to implement Basic Auth support in your own connector to authenticate with your API. Examples in this discussion show the use of Basic Authentication with basic username/password authentication, but they can easily be generalized to other non-OAuth protocols.
This document assumes you are familiar with the Anypoint Connector DevKit, have already created a connector project, and are ready to implement authentication on your connector. Further, it assumes you are familiar with the various authentication methods, have compared the different authentication support options in Devkit, and chosen Basic Authentication to connect to your API.
Anypoint DevKit’s Basic Auth framework provides the following benefits with minimal effort on the part of the connector developer:
Transparent multitenancy – a Mule application can open many connections to a single target, using different credentials to connect on behalf of many users simultaneously
Connection pooling – automated management of a pool of instances of the connector class, to manage connection resources effectively
The ability to automatically invalidate connections on exceptions, and to reconnect as needed
Anypoint DevKit makes it easy to add Basic Authentication functionality to connectors by applying annotations at the @Connector class level.
Connection Management Framework and Authentication Protocols
The Basic Auth framework can be used in conjunction with most authentication protocols, such as basic username/password authentication (most common), SAML, Kerberos, LDAP and NTLM.
However, you cannot use the Basic Authentication framework with connectors that use OAuth authentication; the framework does not support the "OAuth dance" or the management of OAuth tokens.
To use Basic Authentication in a connector, define and annotate the following methods in the @Connector class:
@Connect method- Creates a connection
@Disconnect method- Explicitly closes a connection
@ValidateConnection method- Returns true if a connection is still valid,
@ConnectionIdentifier method- Returns a prefix used in generating unique identifies for connector instances in the connection pool
Also available is an
@InvalidateConnectionOn method for when an API operation encounters an exception due to a lost connection.
The specific implementation of these methods depends on the target.
Because Basic Authentication is such a useful and fundamental feature, the generated code skeleton includes placeholder methods with the Basic Authentication annotations already applied:
|Skeleton Connector with Connection Management Annotated Methods|
|When developing your connector, make sure to incorporate connection logic that pertains to your connector.|
The methods are called automatically as needed by the Anypoint DevKit framework; you never call them directly from your code.
This method designates which method inside an
@Connector class is responsible for creating a connection to the target. The
@Connect method is called automatically by Mule when the connector starts up, or if the connection to the API has been lost and must be reestablished. When this method finishes, if authentication is successful, the connector instance is ready to make requests to the API.
A method annotated with
org.mule.api.ConnectionException(and no other exceptions)
If automatic Basic Authentication is used, have exactly one method annotated
@Connect; otherwise compilation fails
The specific code that implements the actual connection depends on the API. Here is an example implementation of a
|Connect method for salesforce connector|
The parameters required by this method are the credentials needed for authentication, in this case username and password. Since this method is annotated with
@Connect, Anypoint DevKit makes these parameters available both in the configuration element for this connector (as occurs with
@Configurable fields), as well as in the message processor whenever it is dragged into a flow. Specified credentials override those that are set in the configuration element.
The username parameter is annotated with
@ConnectionKey. If pools are enabled (see Connection Pooling below), Mule keeps a pool of simultaneous connections which are used as needed to make calls. The
@ConnectionKey annotation marks that this field is used as the key for this particular connection within the connection pool, so once a connection for this username has been created and added to the pool, it will be reused rather than recreated for each request.
Choosing a Connection Key
For username and password authentication, the username is the obvious choice for
In the example above, the
== @Disconnect Method
This annotation indicates the method inside a
A method annotated with
If Basic Authentication is used, the
If the connector currently has a connection open, this code calls
== @ValidateConnection Method
This method is called by Mule to check whether the connection is actually open or not.
A method annotated with
Only one method on a
In this example, in order to determine whether the connection is active the code simply checks if the connection parameter is null. A different implementation may be required for other connectors, depending on the protocol.
== @ConnectionIdentifier Method
This annotation identifies a method inside a
A method annotated with
A @Connector class that uses Basic Authentication must have exactly one method annotated
This code returns the connection SessionId as an identifier (if available). The SessionHeader object in this case contains header information about the current connection to the API, including the session ID.
== @ReconnectOn Annotation
This annotation is used for exception handling related to connections. It can be used at a class level (annotated with the
== Connection Pooling
You can allow users of your connector to use a pool of simultaneous connections instead of sharing a single instance to process messages.
Connectors that implement pools are each assigned a pool component, which contains multiple instances of the connector to handle simultaneous requests. A connector’s configuration pooling profile configures its component pool.
If you set the
In the corresponding XML, the
The following table lists
== See Also