V5.1.6 onwards
The Username & Password and Username & Auth Client methods are considered legacy authentication options. These were designed for older systems and may not meet modern security standards.
For better security and easier management, we recommend using Personal Access Tokens (PAT).
This tutorial demonstrates how to log in to 12d Synergy with an individual Auth Client that has been set up for the user in 12d Synergy Admin.
Similar to logging in with a username and password, a refresh and access token will be sent back in a successful response.
The steps include:
Ensuring the user has been set up correctly in the Admin beforehand
Logging in with a user name and the Auth Client Secret key and receiving the tokens
Troubleshooting error messages
The commands are provided in curl and can be run from the command prompt when the 12d Synergy Server is running (or in a batch script).
The tutorial on how to log in to the API with a username and password and how to use the access and refresh tokens can be found here: Username and Password (and Using Access Tokens)
1.1. Logging in with a password versus logging in with Auth Client
Some of the benefits of using the auth client login versus the password login are mentioned below:
A developer can log in and automate 12d Synergy processes without knowing the user's password
The user's password is not sent out via API requests and responses
If the auth client secret key needs to be changed, the 12d Synergy admin can update this without the user having to learn a new password
(In this case, the developer or the program needs to be updated with the new secret key)
If MFA is being used, the user will still need to enter MFA credentials when they log in, but the API does not require MFA credentials
(This can be useful for systems integration and automating 12d Synergy processes with the API, reducing user input)
Similar to MFA, if users are required to log in via SSO, this login process can bypass having to communicate with the SSO system (identity provider)
Additional API documentation
To get a list of most of the API requests available, with the 12d Synergy server running, browse http://synergy.myserver.com/api-docs/ui/index.
(Replace synergy.myserver.com with the external server address and update the port numbers if necessary.)
1.2. Setting up the User in Admin
A new installation of 12d Synergy will start with 1 Auth Client set up in admin (called angularApp).
In previous versions, there was the ability to add new Auth Clients, but now there is an additional option to set a user to match up to the Auth Client.
This will require the admin to have already created the user and ensured their access to 12d Synergy is correct (not part of this tutorial).
The admin should browse to System Settings | Web Access | Auth Clients..png)
1.2.1. Adding a new Auth Client:
The system admin will need to add a new Auth Client for each user to log in to the API.
The ID can be anything, but can't be left blank and cannot be longer than 20 characters.
The Name field can be anything, but can't be left blank and cannot be longer than 50 characters.
Leave the Application Type as JavaScript and check the Active checkbox for the credentials to work.
The Refresh Token Lifetime Hours will default to 24 hours if set to nothing, 0 or less than 0.
Allowed Origin cannot be left blank. Enter * for the API to accept credentials from any origin.
The User (although marked as Optional) cannot be left blank for this functionality. The admin must select a user from Synergy for this Auth Client to work for them.
Note that this add/edit pane is where the system admin can generate a new Secret key if needed.
1.2.2. Getting the Auth Client Secret Key
Once the Auth Client has been set up for the user, the system admin can grab the encoded Secret key by clicking the Copy API Key String button.
It's this secret key, along with the username, that must be sent up in the request for it to work
1.3. Logging in with the Username and Secret key
The body must have grant_type=client_credentials rather than password
The body must include the username
The header must have the secret key of the individual Auth Client rather than the secret key of the Angular App (after the word BASIC)
The request URL is the external server address concatenated with the external port number (if used), concatenated with /token. (It is not displayed in the API documentation with the rest of the exposed methods)
The access and refresh tokens will be sent back in the response if the request is successful. The refresh token will be valid for 24 hours (unless the system admin chooses a different number of hours for that user). The access token will only be valid for 10 minutes. The refresh token should be used in the Refresh Token Request to get a new access token. (This way, the Secret key will only have to be sent up once for the initial login.) As a matter of best practice, the Refresh Token Request should be done before any other request while the user is logged in.
More information regarding the Refresh Token Request can be found in the following tutorial:
Username and Password (and Using Access Tokens)
Log in with Auth Client Request
curl --location --request POST "http://synergy.myserver.com:8080/token" ^
--header "Content-Type: application/x-www-form-urlencoded" ^
--header "Authorization: BASIC dGVzdC50b2tlbjphN2Q4NDkzNjZkMjI0ZjhlYjUyMWNjZjY5NjkyNTYyNw==" ^
--data-urlencode "grant_type=client_credentials" ^
--data-urlencode "username=bill.posters" ^
--data-urlencode "remember=true" ^
--data-urlencode "mfa_key=" ^
--data-urlencode"machine_key="Log in Response
{
"access_token": <token>,
"token_type": "bearer",
"expires_in": 599,
"refresh_token": "9201459c034b442e884a25a27b4692fe",
"user_name": "bill.posters",
"user_id": "<ID>6</ID><ServerID>1</ServerID><ServerGUID>7341e777-cd38-4bf7-9ea6-7fd912e6b11e</ServerGUID>",
"as:client_id": "bill.posters",
"is_read_only_web_user": "false",
"remember_me": "true",
".issued": "Wed, 19 Jul 2023 06:39:08 GMT",
".refresh": "True",
".expires": "Wed, 19 Jul 2023 06:49:08 GMT"
}1.4. Troubleshooting Error Messages:
If the login request is unsuccessful, some clues may be given by the response errors:
Invalid Client Credentials
{
"error": "invalid_grant",
"error_description": "Invalid Client credentials."
}Check (in admin) that the 12d Synergy user has been added to the custom Auth Client created.
Value cannot be null
{
"error": "invalid_grant",
"error_description": "Value cannot be null.\r\nParameter name: key"
}A fairly generic error message. This may be because the Secret key sent up is incorrect (then the OAuthGrantClientCredentialsContext.ClientId becomes null). Ensure that the Secret key is not the one displayed in the admin, but rather the one copied to the clipboard when 'Copy API Key String' is pressed.
The username or password is not provided
{
"error": "invalid_grant",
"error_description": "The username or password is not provided."
}The API is looking for a password. Make sure that the grant_type in the body of the request is client_credentials rather than password.
1.4.1. Additional Logging
If these error messages are not enough, then a custom setting can be set by the system admin in the admin thick client. The custom setting should be called LogWebLogins with a value of 1. This will add additional logging to the server logs (ask the system admin where these can be obtained).
Try sending the request again and then looking to see what is written in the server logs around that time of day. The logs can be fairly lengthy - try a word search in the logs using the following keywords: Login, logs.