Authentication Service
Authentication Service🔗
Method Authenticate🔗
Method call🔗
authenticate(environment, password, accessRoles, accessOptions, user, userOptions) : accessToken
Description🔗
The authenticate method provides an access token that grants access to the Search web service on the given search environment with the given access roles.
Using the access token a user can directly interface with Search! from within the web browser. The token is a secure alternative to sending passwords to the user's browser.
The customer system is responsible for managing access roles and supplying access tokens to authorized users, as well as securing the search environment password.
Parameters🔗
| Parameter Name | Type | Description |
|---|---|---|
| environment | string | identifier of a search environment |
| password | string | password for the search environment |
| accessRoles | list of strings | the access roles to be granted to the user of the token, access is granted to documents with any of the listed roles, or excluded in case of a negative role (-rolename). |
| accessOptions | AccessOptions object | optional object containing access options (for external searchers) See AccessOptions in chapter Object Structures |
| user | string | the unique identifier of the user in the integrating application, used for saving user-specific data in the Search! database |
| userOptions | UserOptions object | optional object containing additional info on the user See UserOptions in chapter Object Structures |
Returns🔗
| Result Name | Type | Description |
|---|---|---|
| accessToken | string | if password is correct: a randomly generated string that grants access to the Search web service for the given search environment and access roles |
Pre-Condition🔗
The access roles must be defined on the indexed documents in order to be able to retrieve any results with the access token.
Post-Condition🔗
The token grants access to the Search web service for the duration configured for the environment.
Error Handling🔗
| Error Code | Description |
|---|---|
| EMPTY_ARGUMENT | One or more mandatory arguments are empty. |
| INVALID_PASSWORD | The password is incorrect. |
| ENVIRONMENT_NOT_AVAILABLE | The environment is not available (see log-file for possible errors). |
Method Invalidate🔗
Method call🔗
invalidate(accessToken) : void
Description🔗
The invalidate method invalidates the access token associated with a search environment and a set of access roles. In effect, the access token cannot be used anymore on the Search web service. Note that when the clustered session store is used it may take up to 5 minutes until the change is propagated to all nodes.
If the invalidate method is never called, the accessToken expires anyway after a set duration as configured for the search environment.
Parameters🔗
| Parameter Name | Type | Description |
|---|---|---|
| accessToken | string | the token returned by method authenticate |
Returns🔗
| Result Name | Type | Description |
|---|---|---|
| isExpired | boolean | returns true |
Pre-Condition🔗
For the invalidate method to have any effect, the given token must have been issued before by a call to the authenticate method.
Post-Condition🔗
The token is no longer usable.
Error Handling🔗
| Error Code | Description |
|---|---|
| EMPTY_ARGUMENT | The token is not supplied. |
Method Authenticate External🔗
Method call🔗
authenticateExternal(accessToken, searchEngine, credentials, encryptedCredentials, encryptCredentials, language) : ExternalAuthenticationResult
Description🔗
The authenticate external method provides an External Authentication Result object (contains access token and encryptedCredentials) that grants access to the external searcher's services on the given search environment with the given access token.
Upon successful authentication, a new access token is returned containing all parameters and previously authenticated credentials from the supplied access token. This access token can then be used for subsequent search request.
Parameters🔗
| Parameter Name | Type | Description |
|---|---|---|
| accessToken | string | Token that represents user is authenticated to use Search services |
| searchEngine | string | Name of the external searcher to be authenticated |
| credentials | Credentials object | optional object containing credentials for the external searcher. See Credentials in chapter Object Structures |
| encryptedCredentials | EncryptedData object | optional object containing encrypted credentials for the external searchers. The object contains 2 String parameters named as data and iv used when authenticating with previously stored encrypted credentials in the browser. |
| encryptCredentials | boolean | whether encrypted credentials should be returned |
| language | string | the optional language to be encoded in the access token |
Note: Either credentials or encryptedCredentials are required
Returns🔗
Returns ExternalAuthenticationResult object that contains:
| Result Name | Type | Description |
|---|---|---|
| encryptedCredentials | EncryptedData | if encryptCredentials is sent as true encrypted credentials is returned in the response |
| accessToken | String | If authentication is successful, a new access token is generated, containing all credentials from the supplied access token plus the newly authenticated one. |
Pre-Condition🔗
A valid search access token is required before authenticating external searchers.
Post-Condition🔗
The token grants access to the external searcher for the duration configured for the environment.
Error Handling🔗
| Error Code | Description |
|---|---|
| EMPTY_ARGUMENT | One or more mandatory arguments are empty. |
| INVALID_ACCESS_TOKEN | Requested access token is invalid or expired |
| SEARCHER_NOT_FOUND | The requested searcher not found in the environment retrieved from access token. |
| EXTERNAL_LOGIN_ERROR | Exception retrieving authentication token from external searcher. |
| NOT_AUTHENTICATED | Encrypted credentials could not be decrypted for this user/password. |