com.sap.security.um.user

## Interface UserProvider

-     public interface UserProvider

  This interface represents the service interface which provides read access to a user implementation. If the service interface is implemented in an OSGi framework, the implementation has to be registered via the interface BundleContext in the activator of the bundle that provides the implementation. Example:

       public class MyUserProviderActivator implements BundleActivator {
       ...
           public void start(final BundleContext context) {
               context.registerService(UserProvider.class.getName(),
                                       new MyUserProviderImplementation(),
                                       null);
           }
       ...
       }

  Consumers of the service interface have to track the availability of an implementation. Example:

       public class MyPasswordPolicyConsumerActivator implements BundleActivator {

           private ServiceTracker userProviderTracker;

           public void start(final BundleContext context) {
               userProviderTracker =
                   new ServiceTracker(context,
                                      UserProvider.class.getName(),
                                      new ServiceTrackerCustomizer() {

                                          public Object addingService(final ServiceReference reference) {
                                              final UserProvider UserProvider = (UserProvider)context.getService(reference);
                                              //store instance of UserProvider
                                              return UserProvider;
                                          }

                                          public void modifiedService(final ServiceReference reference, final Object service) {
                                              //nothing to be done
                                          }

                                          public void removedService(final ServiceReference reference, final Object service) {
                                              //remove stored instance of UserProvider
                                          }
                                      });

               userProviderTracker.open();

           }

           public void stop(final BundleContext context) {
               if (userProviderTracker != null) userProviderTracker.close();
           }
       ...
       }

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `UserProvider.CaseSensitive` Two possible ways to search for user attribute values if supported by the the user provider implementation for the concrete user attribute.
    `static class` | `UserProvider.SearchOperator` Searching for exact match of the search criteria.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `USER_PROVIDER_NAME_PROPERTY` Could be used to specify a name of the UserProvider implementation when it is registered in an OSGi framework.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `PasswordCheckResult` | `checkUserPassword(String user, char[] password)` Checks the provided password against the user's stored password.
    `User` | `getCurrentUser()` Returns the current authenticated user, or `null` if no there is no such user.
    `User` | `getUser(String name)` Returns the user which has the provided name, or `null` if no user with the provided name exists.
    `User` | `getUser(X509Certificate certificate)` Returns the user which has the provided X.509 client certificate assigned, or `null` if the provided certificate is not assigned to any user.
    `Set<String>` | `searchUser(String attribute, String criteria, UserProvider.SearchOperator operator, UserProvider.CaseSensitive preferredCaseSensitivity)` Searches users and returns the user names of the users that match the provided search criteria.

- - ### Field Detail

    - #### USER_PROVIDER_NAME_PROPERTY

          static final String USER_PROVIDER_NAME_PROPERTY

      Could be used to specify a name of the UserProvider implementation when it is registered in an OSGi framework.
      Example:

           public class MyUserProviderActivator implements BundleActivator {
           ...
               public void start(final BundleContext context) {
                   Dictionary properties = new Hashtable();
                   properties.put(UserProvider.USER_PROVIDER_NAME_PROPERTY, "MyName");
                   context.registerService(UserProvider.class.getName(),
                                           new MyUserProviderImplementation(),
                                           properties);
               }
           ...
           }

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getUser

          User getUser(String name)
                       throws PersistenceException

      Returns the user which has the provided name, or `null` if no user with the provided name exists. Whether the lookup is done case sensitive or not depends on the user provider implementation. Usually the lookup of users by name is done case in-sensitive.
      Parameters:
        `name` - The user name
      Returns:
        The user which has the provided name or `null` if no such user exists.
      Throws:
        `PersistenceException` - If an unexpected error occurs during the read operation (e.g. connection to user store broken).

    - #### getCurrentUser

          User getCurrentUser()
                              throws PersistenceException

      Returns the current authenticated user, or `null` if no there is no such user.
      Returns:
        The current authenticated user or `null` if no such user exists.
      Throws:
        `PersistenceException` - If an unexpected error occurs during the read operation (e.g. connection to user store broken).

    - #### getUser

          User getUser(X509Certificate certificate)
                       throws PersistenceException

      Returns the user which has the provided X.509 client certificate assigned, or `null` if the provided certificate is not assigned to any user. The implementation of this lookup is user provider specific. So one user provider can implement the lookup using the binary representation of the certificate while another provider can implement the lookup by extracting data like the subject name from the certificate and use this data for the lookup.
      Parameters:
        `certificate` - The X.509 client certificate of the user.
      Returns:
        The user which has the provided certificate or `null` if no such user exists.
      Throws:
        `PersistenceException` - If an unexpected error occurs during the read operation (e.g. connection to user store broken).

    - #### searchUser

          Set<String> searchUser(String attribute,
                               String criteria,
                               UserProvider.SearchOperator operator,
                               UserProvider.CaseSensitive preferredCaseSensitivity)

      Searches users and returns the user names of the users that match the provided search criteria. Currently there's only one search operator available for exact match searches without wild cards, but this may change in the future. The search argument preferred case sensitivity allows specifying whether the caller wants the criteria to be match case sensitive or not. Depending on the user provider both options or only one option might be supported.
      Parameters:
        `attribute` - The user attribute.
        `criteria` - The search criteria.
        `operator` - The search operator.
        `preferredCaseSensitivity` - The preferred case sensitivity.
      Returns:
        The names of users where the value of the provided attribute matches the search criteria or `null` if no user matches the search criteria.

    - #### checkUserPassword

          PasswordCheckResult checkUserPassword(String user,
                                              char[] password)
                                                throws PersistenceException

      Checks the provided password against the user's stored password. If the provided password matches the stored one, `null` is returned. If the password does not match, or cannot be checked, a password check result code is returned which provides the details about the failing check.
      Parameters:
        `user` - The username which the end user inputs.
        `password` - The password for that username.
      Returns:
        `null` in case of a successful password check, otherwise a `PasswordCheckResult`.
      Throws:
        `PersistenceException` - If an unexpected error occurs during the check operation.

Copyright © 2016 SAP. All Rights Reserved.