External Authentication
Administrators can benefit from using external authentication servers for authenticating users into MyQ. This is helpful mainly in environments where an authentication service not natively supported by MyQ is used.
External Authentication is used for login on the MyQ Embedded Terminal and MyQ Desktop Client. The MyQ Web User Interface and MyQ X Mobile Client require credentials set in MyQ.
How it works
An API connector between MyQ and the authentication service is set up. MyQ requests authentication through this connector, and on the other side is the authentication service itself where users and their credentials are stored.
User attempts to sign in on the MyQ Embedded Terminal
By swiping an ID card
By entering a PIN
The request is sent to the API connector, containing the login method type and the value
The connector handles communication with the authentication service and returns the user who matches back to MyQ
There are two modes of operation for External Authentication. Either it can be the primary way of authenticating users, or it can be configured as a backup authentication in case the authentication towards MyQ fails. For this, the option “Use only if authentication against MyQ DB fails” can be selected.
Authentication request
Supported login methods
This setting defines the login method for which External Authentication is used. The other, unselected, login method authenticates the user against the credentials in MyQ.
ID Card
PIN
MyQ sends the type of login method together with the actual PIN/ID card value so that the API connector can recognize which user property should be used to find the correct user.
For example, if an ID Card is selected, and the user authenticates on the Embedded Terminal with an ID card, MyQ sends out loginType=1&loginValue=1234
. This can be interpreted as the ID card number 1234
.
If a card reader that emulates keystrokes is connected to the device and a user swipes their card, MyQ cannot recognize if the value received is a PIN or ID card number. MyQ indicates this to the API connector (loginType=7
). The connector should be configured to handle these requests, e.g. by attempting to authenticate towards both user properties.
Authentication response
Supported user identifiers
The API connector has to respond in a JSON format with one of the values back to MyQ to pair the correct user and log them into the client.
Personal number of an existing user in MyQ
Username of an existing user in MyQ
Example responses:
{"result":0,"personalNumber":"123456"}
means that the user was successfully identified by the authentication service and its personal number is123456
. The user with this personal number in MyQ is authenticated.{"result":0,"username":"JohnDoe"}
means that the user was identified and its username isJohnDoe
. The user with this username in MyQ is authenticated.
Error states
Invalid user (
{"result":1}
)-- the user was found, but their account is invalid (e.g. deactivated)No user found (
{"result":2}
)-- there is no user associated with the credentials
API Documentation
For implementation details, containing information about the API endpoints and valid responses, read the MyQ API documentation – External Authentication.
Common use cases
The External API connector can be used in its most simple way to “translate” requests. But it also allows more advanced authentication workflows as the connector itself can perform a set of operations before it returns the matching user back to MyQ.
Example 1: Authentication service not supported by MyQ is required
A connector that translates the API calls between MyQ and the remote authentication service.
Example 2: Advanced authentication workflow – multiple identities
External Authentication can be used in cases where some operation is required to happen between MyQ and the authentication server. This can be transformation, advanced user recognition in multi-domain environments, and more.
Setup External Authentication
External Authentication destination can be enabled and configured in MyQ, Settings, User Authentication.
![External authentication settings](../../../__attachments/1262780700/UserAuthExternal.png?inst-v=f576f6b0-eb9f-4035-8724-3dad44b7106e)
URL: type the URL where the API connector is running
User name: type the user name required for the connection to the external server via API
Password: type the password required for the connection to the external server via API
Login method: choose the users login method - ID Card or PIN
Use only if authentication against MyQ DB fails: this option defines whether the External Authentication will be the primary or secondary method for authentication
If enabled, the user is first authenticated towards the MyQ Print Server, and only after it fails, the next attempt goes through the remote authentication service
If disabled, no authentication towards the MyQ Print Server is performed, External Authentication service is always used