IDM 7.2.2

Authenticate operation

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

The authenticate operation authenticates an object on the target system, based on two parameters, usually a unique identifier (username) and a password. If possible, your connector should try to authenticate these credentials natively.

If authentication fails, the connector should throw a runtime exception. The exception must be an IllegalArgumentException or, if a native exception is available and is of type RuntimeException, that native runtime exception. If the native exception is not a RuntimeException, it should be wrapped in a RuntimeException, and then thrown.

The exception should provide as much detail as possible for logging problems and failed authentication attempts. Several exceptions are provided in the exceptions package, for this purpose. For example, one of the most common authentication exceptions is the InvalidPasswordException.

For more information about the common exceptions provided in the OpenICF framework, refer to Common exceptions.

Use the ICF authenticate operation

This section shows how your application can use the framework’s authentication operation, and how to write a unit test for this operation, when you are developing your connector.

The authentication operation throws a RuntimeException if the credentials do not pass authentication, otherwise returns the UID.

Sample Unit Test for the Authentication Operation (Java)
@Test
public void authenticateTest() {
    logger.info("Running Authentication Test");
    final ConnectorFacade facade = createConnectorFacade(BasicConnector.class, null);
    final OperationOptionsBuilder builder = new OperationOptionsBuilder();
    Uid uid =
        facade.authenticate(ObjectClass.ACCOUNT, "username", new GuardedString("Passw0rd"
        .toCharArray()), builder.build());
    Assert.assertEquals(uid.getUidValue(), "username");
}

Implement the authenticate operation

To implement the authenticate operation in your connector, add the AuthenticateOp interface to your connector class, for example:

@ConnectorClass(
    displayNameKey = "Sample.connector.display",
    configurationClass = SampleConfiguration.class)
public class SampleConnector implements Connector, AuthenticateOp...

For more information, refer to the AuthenticateOp JavaDoc.

The SPI provides the following detailed exceptions:

  • UnknownUidException - the UID does not exist on the resource.

    (org.identityconnectors.framework.common.exceptions.UnknownUidException)

  • ConnectorSecurityException - base exception for all security-related exceptions.

    (org.identityconnectors.framework.common.exceptions.ConnectorSecurityException)

  • InvalidCredentialException - generic invalid credential exception that should be used if the specific error cannot be obtained.

    (org.identityconnectors.framework.common.exceptions.UnknownUidException)

  • InvalidPasswordException - the password provided is incorrect.

    (org.identityconnectors.framework.common.exceptions.InvalidPasswordException)

  • PasswordExpiredException - the password is correct, but has expired.

    (org.identityconnectors.framework.common.exceptions.PasswordExpiredException)

  • PermissionDeniedException - the user can be identified but does not have permission to authenticate.

    (org.identityconnectors.framework.common.exceptions.PermissionDeniedException)

Implementation of the Authentication Operation, at the SPI Level
public Uid authenticate(final ObjectClass objectClass, final String userName,
        final GuardedString password, final OperationOptions options) {
    if (ObjectClass.ACCOUNT.equals(objectClass)) {
        return new Uid(userName);
    } else {
        logger.warn("Authenticate of type {0} is not supported", configuration
                .getConnectorMessages().format(objectClass.getDisplayNameKey(),
                        objectClass.getObjectClassValue()));
        throw new UnsupportedOperationException("Authenticate of type"
                + objectClass.getObjectClassValue() + " is not supported");
    }
}