io.continual.iam.identity

Interface IdentityManager<I extends Identity>

All Superinterfaces:

IdentityDb<I>

All Known Subinterfaces:

IamDb<I,G>

All Known Implementing Classes:

CommonJsonDb, JsonDocDb, MultiSourceDb

public interface IdentityManager<I extends Identity>
extends IdentityDb<I>

This interface to the database allows the caller to make changes to identity information, like creating users, enabling/disabling users, etc.

A userId string can be any value suitable to the application, such as email address or UUID. Note that userIds are fixed, so using an email address comes with some risk of identity migration work if the email address changes.

Method Summary

Modifier and Type	Method and Description
void	addAlias(String userId, String alias) Add a username/alias for this user.
void	addJwtValidator(JwtValidator v) Add a JWT validator to the identity manager.
boolean	completePasswordReset(String tag, String newPassword) Complete a password reset by providing a tag and a new password.
I	createAnonymousUser() Create a new anonymous user in the identity manager.
I	createUser(String userId) Create a new user in the identity manager.
void	deleteUser(String userId) Delete a user from the identity manager.
List<String>	findUsers(String startingWith) Find users with a user ID that starts with the given string
Collection<String>	getAliasesFor(String userId) Get the aliases for a userId.
Collection<String>	getAllUsers() Get all user IDs in this db.
Map<String,I>	loadAllUsers() Load all users in this identity manager.
ApiKey	loadApiKeyRecord(String apiKey) Load an API key record based on the API key ID.
I	loadUser(String userId) Load a user from the identity manager.
I	loadUserOrAlias(String userIdOrAlias) Load a user from the identity manager.
void	removeAlias(String alias) Remove a username/alias from the database.
void	restoreApiKey(ApiKey key) Restore an API key into the API key store
boolean	userExists(String userId) Find out if a given user exists.
boolean	userOrAliasExists(String userIdOrAlias) Find out if a given user or alias exists.

Methods inherited from interface io.continual.iam.identity.IdentityDb

authenticate, authenticate, authenticate, createJwtToken, invalidateJwtToken

Method Detail

userExists

boolean userExists(String userId)
            throws IamSvcException

Find out if a given user exists.

Parameters:

userId - a user ID

Returns:

true if the user exists in the identity manager.

Throws:

IamSvcException - when the call cannot be completed due to a service error

userOrAliasExists

boolean userOrAliasExists(String userIdOrAlias)
                   throws IamSvcException

Find out if a given user or alias exists.

Parameters:

userIdOrAlias - the user ID or an alias

Returns:

true if the user exists by userId or alias in the identity manager.

Throws:

IamSvcException - when the call cannot be completed due to a service error

loadUser

I loadUser(String userId)
    throws IamSvcException

Load a user from the identity manager.

Parameters:

userId - a user ID

Returns:

a user or null if the user doesn't exist

Throws:

IamSvcException - when the call cannot be completed due to a service error

loadUserOrAlias

I loadUserOrAlias(String userIdOrAlias)
           throws IamSvcException

Load a user from the identity manager.

Parameters:

userIdOrAlias - the actual userId or an alias

Returns:

a user or null if the user doesn't exist

Throws:

IamSvcException - when the call cannot be completed due to a service error

findUsers

List<String> findUsers(String startingWith)
                throws IamSvcException

Find users with a user ID that starts with the given string

Parameters:

startingWith - a prefix for users

Returns:

a list of 0 or more matching user IDs

Throws:

IamSvcException - when the call cannot be completed due to a service error

createUser

I createUser(String userId)
      throws IamIdentityExists,
             IamSvcException

Create a new user in the identity manager. The username for this user defaults to the userId value provided here.

Parameters:

userId - a user ID

Returns:

the new user

Throws:

IamIdentityExists - if the user exists

IamSvcException - when the call cannot be completed due to a service error

createAnonymousUser

I createAnonymousUser()
               throws IamSvcException

Create a new anonymous user in the identity manager.

Returns:

a new anonymous user

Throws:

IamSvcException - when the call cannot be completed due to a service error

deleteUser

void deleteUser(String userId)
         throws IamSvcException

Delete a user from the identity manager.

Parameters:

userId - a user ID

Throws:

IamSvcException - when the call cannot be completed due to a service error

addAlias

void addAlias(String userId,
              String alias)
       throws IamSvcException,
              IamBadRequestException

Add a username/alias for this user. Identity DBs should normally support multiple aliases (username, email, mobile phone, etc.). Tracking them beyond being references to an identity record is done at the application level.

Parameters:

userId - a user ID

alias - an alias

Throws:

IamSvcException - when the call cannot be completed due to a service error

IamBadRequestException - if the request is illegal

removeAlias

void removeAlias(String alias)
          throws IamBadRequestException,
                 IamSvcException

Remove a username/alias from the database. A userId may not be removed (disable the user instead).

Parameters:

alias - an alias

Throws:

IamBadRequestException - If a userId is provided.

IamSvcException - when the call cannot be completed due to a service error

getAliasesFor

Collection<String> getAliasesFor(String userId)
                          throws IamSvcException,
                                 IamIdentityDoesNotExist

Get the aliases for a userId. The result must be non-null but may be empty. The userId is not included in the list.

Parameters:

userId - a user ID

Returns:

a collection of 0 or more aliases for a userId

Throws:

IamSvcException - when the call cannot be completed due to a service error

IamIdentityDoesNotExist - if the identity does not exist

completePasswordReset

boolean completePasswordReset(String tag,
                              String newPassword)
                       throws IamSvcException

Complete a password reset by providing a tag and a new password. The update will fail if the tag is unknown or has expired. See requestPasswordReset for details on creating a password reset tag.

Parameters:

tag - a tag

newPassword - a new password

Returns:

true if the password was updated successfully.

Throws:

IamSvcException - when the call cannot be completed due to a service error

loadApiKeyRecord

ApiKey loadApiKeyRecord(String apiKey)
                 throws IamSvcException

Load an API key record based on the API key ID.

Parameters:

apiKey - an API key

Returns:

an API key or null if it doesn't exist

Throws:

IamSvcException - when the call cannot be completed due to a service error

restoreApiKey

void restoreApiKey(ApiKey key)
            throws IamIdentityDoesNotExist,
                   IamBadRequestException,
                   IamSvcException

Restore an API key into the API key store

Parameters:

key -

Throws:

IamBadRequestException

IamIdentityDoesNotExist

IamSvcException

addJwtValidator

void addJwtValidator(JwtValidator v)

Add a JWT validator to the identity manager.

Parameters:

v - a validator

getAllUsers

Collection<String> getAllUsers()
                        throws IamSvcException

Get all user IDs in this db. Clearly not suitable for systems beyond a few thousand users. For larger scale, this call may throw an IamSvcException signaling that the underlying database won't return a user list.

Returns:

a collection of user Ids

Throws:

IamSvcException - when the call cannot be completed due to a service error

loadAllUsers

Map<String,I> loadAllUsers()
                    throws IamSvcException

Load all users in this identity manager. Clearly not suitable for systems beyond a few thousand users. For larger scale, this call may throw an IamSvcException signaling that the underlying database won't return a user list.

Returns:

a map of user ID to identity

Throws:

IamSvcException - when the call cannot be completed due to a service error