User lookup

Configuration

Note

Authenticator type: UserLookup

Common Authenticator configuration can be found here.

Properties

Name	Description	Default value	Mandatory
pipe_id	Name of pipe used for validation	N/A	true
allowed_retries	Allowed number of times a user is allowed to enter username before process is aborted.	2	false
webroot_dir	See common authenticator configuration	web/authenticator/user_lookup	false
custom_identifier	Tag used for event separation	N/A	false

Example

{
    "id": "uidlookup",
    "type": "UserLookup",
    "config": {
        "base_path": "/saml/authn",
        "pipe_id": "finduser",
        "webroot_dir": "web/authenticator/user_lookup"
    }
}

Caution

Property base_path should not contain the full path when used in conjunction with the Selector, instead, the full URI will be handled by the selector. The full path will be base_path + / + id.

Logging

Apart from system logging, event logging is done when completing and failing a transaction.

Event ids are:

• WEB_100024("Performed user lookup")

  • IDENTIFIER (user trace id)
  • CUSTOMER_IDENTIFIER (if configured)
  • SOURCE_USER_NAME (username entered by the user)
  • SOURCE_ADDRESS (ip of the remote session)

• WEB_100025("User lookup failed")

  • IDENTIFIER (user trace id)
  • CUSTOMER_IDENTIFIER (if configured)
  • SOURCE_ADDRESS (ip of the remote session)
  • SOURCE_USER_NAME (username entered by the user)

Data sent to validation pipe

On validation, data sent to the pipe is:

• identifier - the username provided by the user

Data exposed to global state

After a user completes a transaction, the authenticator is marked as done. Data from the authentication response is then put into the global state replacing existing values:

• username

API

API follows the general conventions of the Fortified Web Authenticator API.

General requirements

All requests use the HTTP PUT method with Content-Type: application/json, sent to the directory URL the view was loaded from. The session cookie must be sent with every request.

Messages

Message	Purpose
state	Fetch the current state. Send it when the view loads.
start	Submit the identifier to look up.
cancel	Cancel the authentication.

Getting state

Send this when the view loads, and after a browser reload. It moves a pending authenticator into progress and reports that the view may collect input.

Request

{
    "type": "state"
}

Response

{
    "status": "ABOUT_TO_START"
}

Starting an authentication

Send the identifier entered by the user. It is passed to the configured pipe together with any whitelisted request headers.

Request

{
    "type": "start",
    "data": {
        "identifier": "<identifier>"
    }
}

Response

{
    "type": "complete",
    "success": true,
    "data": {
        "location": "<next-location>"
    }
}

Errors

{
    "status": "ERROR"
}

Returned when the identifier is missing from the request, or when the lookup pipe fails or reports no success. The view should show an error and let the user try again.

Caution

The number of attempts is limited by allowed_retries. When it is exceeded the authenticator fails instead of answering ERROR, and the response is a failure message with the reason Failed userlookup. The view must not offer another attempt after that.

Cancel a request

A request can be canceled at any time. This is done by sending a cancel request.

{
    "type": "cancel"
}

Response from server

Expect HTTP status code 200. Anything else is to be considered an error.

The body is a JSON object. A step that is still in progress answers with a status property; a step that ends the authenticator answers with a complete, cancel, or failure message as described in Web Authenticator API.

Possible status messages

Status	Meaning
ABOUT_TO_START	The authenticator is ready and the view should collect the identifier.
ERROR	The identifier was missing, or the lookup failed. Attempts remain.

Translation keys

{
  "user_lookup.identifier": "Username",
  "user_lookup.start_authentication": "Sign in",
  "user_lookup.authentication_verified": "Identity verified",
  "user_lookup.redirecting": "Redirecting...",
  "user_lookup.cancel": "Cancel",
  "user_lookup.ERROR": "Wrong username or password.",
  "allow-cookies-body": "To save your language settings on this device you need to approve a language cookie.",
  "allow-cookies-button": "Approve language cookie",
  "authentication.help_text": "",
  "change_language": ""
}

{
  "user_lookup.identifier": "Användarnamn",
  "user_lookup.start_authentication": "Logga in",
  "user_lookup.authentication_verified": "Identitet verifierad",
  "user_lookup.redirecting": "Omdirigerar...",
  "user_lookup.cancel": "Avbryt",
  "user_lookup.ERROR": "Felaktigt användarnamn eller lösenord",
  "allow-cookies-body": "Vill du spara dina språkinställningar på denna enhet behövs ett godkännande av  språk-cookie.",
  "allow-cookies-button": "Godkänn språk-cookie",
  "authentication.help_text": "",
  "change_language": ""
}