---
title: Authenticate operation
description: 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.
component: openicf
page_id: openicf:connector-dev-guide:operations/operation-authenticate
canonical_url: https://docs.pingidentity.com/openicf/connector-dev-guide/operations/operation-authenticate.html
section_ids:
  AuthenticationApiOp-api-level-rules: Use the ICF authenticate operation
  AuthenticateOp-spi-level-rules: Implement the authenticate operation
---

# Authenticate operation

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](../common-exceptions.html).

## 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)

```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:

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

For more information, refer to the [AuthenticateOp JavaDoc](../../_attachments/apidocs/org/identityconnectors/framework/spi/operations/AuthenticateOp.html).

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

```java
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");
    }
}
```