This is the translated version of Single-Sign-On Schnittstelle v2.0
This is the translated version of Single-Sign-On Schnittstelle v2.0
Single sign-on (SSO) simplifies access to the PRINT LOUNGE from external systems. The user simply clicks on a link in the software (e.g. CMS or CRM system, intranet or procurement platform) and is automatically and securely registered and logged in to the PRINT LOUNGE. The relevant user data is transmitted via this SSO link in encrypted form.
There is no need to register or log in to the PRINT LOUNGE again, making it easier to integrate and use the software with external systems and existing software environments.
This can result in faster integration and easier sign-up, increased productivity, efficiency and security, and centralized processes.
Contents of this Documentation
16falsediscContents of this DocumentationlistfalseRequirements
The "Single Sign-On (SSO)" add-on must be enabled for the client
The SSO interface must be configured in the store.
A technical adjustment in the external system may be required to create and integrate the SSO interface.
How to use the SSO Link
The link to access the PRINT LOUNGE contains all relevant data in encrypted form; the validity of the link can also be limited to a specific duration, IP address or referrer.
The structure of the SSO link is always the same:
https://SHOP_DOMAIN/sso.php?h=ENCODED_KEY_VALUE_PAIRS
Depending on your shop configuration, the SHOP_DOMAIN is either the stored name of the shop followed by the SASS domain (e.g. shop.print-server.net, where "shop" is the name of the shop) or the individual shop domain (e.g. example-shop-domain.dev).
noteThese settings can be found in the Administration under "Administration » Shops » edit" in the "Basic Settings" tab.
These settings can be found in the Administration under "Administration » Shops » edit" in the "Basic Settings" tab.
Configuring the Interface
Before the SSO interface can be used, it must first be configured and activated in the Administration under “Administration » Shops » Edit” in the "SSO Interface" tab.
The following configuration options are available:
Setting | Possible values | Description |
|---|---|---|
Enable SSO interface | yes / no | Enables or disables general use of the SSO interface. |
Disable regular login | yes / no | Disables regular login via the login form when the SSO interface is enabled. This means that it can only be used via SSO. |
Allow user to log out | yes / no | Disables the user's independent logout from the shop. |
Show “back” button with HOOK_URL | yes / no | Displays a "back" button with the passed HOOK_URL. |
Register unknown users | yes / no | Allows unknown users to register. Enabling this setting is not recommended, but may be necessary and useful in some software environments. It should be ensured that all users with access to the SSO link are allowed to use the PRINT LOUNGE. If this option is disabled, only users already created in the PRINT LOUNGE will be able to log in using SSO. |
Automatically create user groups | yes / no | User groups that have been passed but not yet created in the PRINT LOUNGE are automatically recreated during SSO login. If this is disabled, the passed and existing group or the default user group is used. |
Determine user groups based on customer number | yes / no | The appropriate user group is determined based on the customer number provided. If no user group is found, the default user group is used. |
Internally assign users to the following default budget group | Selection of user group | User group to which SSO users are automatically assigned. |
User fields that cannot be overwritten | Selection of user fields | Selected user fields are protected and cannot be set via SSO. Passed parameters for these custom fields are ignored during processing. |
Passphrase | – | System-generated passphrase; cannot be set individually. |
Encryption method | Selection of the encryption method | Select the method to use for encrypting and decrypting transmitted data. |
IP-Filter (optional) | Semicolon-separated IP addresses | Semicolon-separated IP addresses for which SSO usage should be enabled. |
Referrer verification (optional) | Regular expression | Regular expression to check the passed referrer. If the referrer does not match this schema, the SSO login will fail. |
Logging in users without a username with a temporary username | yes / no | Enables or disables the use of the SSO interface without a username. |
Request Timeout | Timeout in milliseconds | Link validity period. The If the value is 0, the link is valid for a maximum of 3 days. |
Error/Note Texts | Text | This text is displayed in the event of an error. The following error texts can be saved:
|
Information about referrer verification
A regular expression (RegExp) can be stored in the referrer check configuration. This expression can be used to check one or more domains when a user registers and logs in via the SSO interface, so that only certain domains are allowed.
Example to allow only www.example.org:
/www\.example\.org/
Example, to allow www.example.org and www.printlounge.dev:
/www\.(example\.org|printlounge\.dev)/
Example, to allow *.example.org:
/(.*)\.example|\.org/
Logging in users with temporary usernames
If the "Logging in users without a username with a temporary username" option is enabled, the "Register unknown users" option must also be enabled. If both settings are set and no ENCODED_KEY_VALUE_PAIRS is passed, a temporary user with a dummy username is created.
(Technical) Data transfer & SSO link creation
The relevant data for the user registration or login (ENCODED_KEY_VALUE_PAIRS) must be transferred with the stored PASSPHRASE and encryption type. If successful, the user is logged into the PRINT LOUNGE and can use it regularly.
Code example for generating the SSO link in PHP:
php (new DateTimeImmutable)->format(DateTime::ISO8601), 'customer_user_name' => 'example_user', 'customer_firstname' => 'printy', 'customer_lastname' => 'tester', ]; passphrase = 'SECRET_RANDOM_PASSPHRASE'; $cipher = 'aes-128-gcm'; $initializationVectorLength = openssl_cipher_iv_length($cipher); $initializationVecotr = openssl_random_pseudo_bytes($initializationVectorLength); $encryptedShopUserData = openssl_encrypt(http_build_query($shopUserData), $cipher, $passphrase, 0, $iv); $ssoLoginLink = 'https://shop.print-server.net/sso.php?h=' . urlencode($encryptedShopUserData);]]>Available SSO Parameters
Parameter Name | Type / Value | Description |
|---|---|---|
continue_shopping | integer Available values 0: Disabled | Displays the "Continue Shopping" button in the shopping cart. noteWhen enabled, the When enabled, the |
customer_firstname | string max 50 characters (UTF-8) | Shop User » First Name |
customer_funktion | string max 200 characters (UTF-8) | Shop User » Function |
customer_lastname | string max 50 characters (UTF-8) | Shop User » Last Name |
customer_longname | string max 50 characters (UTF-8) | Shop User » Name / Contact |
customer_user_aussendienst | string max 200 characters (UTF-8) | Shop User » External Sales |
customer_user_budgetgruppe__id | integer | Shop User » User Group (ID) noteIf no user group is passed, the user is created in a defined default user group. The same applies if no valid user group can be determined based on the ID. If no user group is passed, the user is created in a defined default user group. The same applies if no valid user group can be determined based on the ID. |
customer_user_businessunit | string max 50 characters (UTF-8) | Shop User » Department |
customer_user_company1 | string max 200 characters (UTF-8) | Shop User » Company 1 |
customer_user_company2 | string max 200 characters (UTF-8) | Shop User » Company 2 |
customer_user_company3 | string max 200 characters (UTF-8) | Shop User » Company 3 |
customer_user_costcenter | string max 200 characters (UTF-8) | Shop User » Cost Center |
| string max 200 characters (UTF-8) |
deprecated, please use |
customer_user_countrycode | string | Shop User » Country Code noteISO-3166 country code ISO-3166 country code |
customer_user_email | string max 100 characters (UTF-8) | Shop User » Email Address |
customer_user_internet | string max 100 characters (UTF-8) | Shop User » Internet Address |
customer_user_kundennummer | string max 100 characters (UTF-8) | Shop User » Customer Number |
customer_user_level | integer Available Values: 57: A – User (default) | Shop User » User Role |
customer_user_mobil | string max 50 characters (UTF-8) | Shop User » Mobile Number |
customer_user_name * | string max 50 characters (A-Z0-9_-.@) | Shop User » Username Unique assignments such as user IDs, email addresses, or usernames must be used. |
customer_user_purchaser | string max 50 characters (UTF-8) | Shop User » Purchaser |
customer_user_street | string max 200 characters (UTF-8) | Shop User » Street |
customer_user_telefax | string max 200 characters (UTF-8) | Shop User » Fax Number |
customer_user_telefon | string max 200 characters (UTF-8) | Shop User » Phone Number |
customer_user_town | string max 200 characters (UTF-8) | Shop User » City |
customer_user_zip | string max 10 characters (UTF-8) | Shop User » Postal Code |
customfield1 | string max 200 characters (UTF-8) | Shop User » Custom Field 1 |
customfield2 | string max 200 characters (UTF-8) | Shop User » Custom Field 2 |
customfield3 | string max 200 characters (UTF-8) | Shop User » Custom Field 3 |
customfield4 | string max 200 characters (UTF-8) | Shop User » Custom Field 4 |
customfield5 | string max 200 characters (UTF-8) | Shop User » Custom Field 5 |
delivery_address_editable | integer Available Values: 0: Yes | Determines whether the shipping address can be edited in the shopping cart. |
dest_id | integer | The ID of the record (product group or product) |
dest_page | string Available Values: wg: Product Group Page | Landing page after SSO login |
dynamic_lists | Pass list items as a JSON string via the SSO interface (see "Dynamic List Entries" for more information). | |
email_address_for_cost_release | string | Email address for cost approval Available since version 6.0.0 |
external_order_number | string | External Job Number This parameter can be used to transfer a job number from an external system, which will be stored in the new job as an "external job number" when the job is placed in the PRINT LOUNGE. |
freigabeportal_zeigen | integer Available Values: 53: Yes | Shop User » Show Release Portal |
group_customer_number | string | User group » Customer number noteIf the name of the user group is passed, it is checked if the customer number with exactly this value exists in the group. If not, the user is assigned to the default group. If there is a match, the user is assigned to that group. If the name of the user group is passed, it is checked if the customer number with exactly this value exists in the group. If not, the user is assigned to the default group. If there is a match, the user is assigned to that group. Works only if the "Determine user groups based on customer number" option is enabled. This data is used only to determine the user group. |
group_name | string max 50 characters (UTF-8) | Benutzergruppe » Description noteIf the name of the user group is passed, it will be checked if the group with the exact name exists. If not, the group is created. The user will be assigned to this group. If the name of the user group is passed, it will be checked if the group with the exact name exists. If not, the group is created. The user will be assigned to this group. Works only if the "Automatically create user groups" option has been enabled. |
lang |
| Language |
pers_data | Used to transmit personalization data (see below) | |
quantity | integer | Price scale quantity noteIf no quantity is specified, the system determines the lowest price scale for the item If no quantity is specified, the system determines the lowest price scale for the item |
request_time * | Date and time (ISO 8601) | Request time Default validity of the request 500s - 8 min |
return_url | 200 characters | URL for return link If a URL is specified here, a button leading to this URL will be displayed on the order confirmation (finish) page. |
settings | Array | User Settings This array can contain any user settings that should be set as a key-value pair. |
skip_cart | 53: Yes | Shop User » Skip Cart |
| string de: German (default) |
deprecated, please use |
test | Enable Test Mode noteTo enable test mode, the parameter "test=true" can be passed. Instead of passing the data, it will be displayed on the screen. To enable test mode, the parameter "test=true" can be passed. Instead of passing the data, it will be displayed on the screen. | |
user_groups_binary_description | 50 characters (Utf8) | Description for the logo (image) of a user group |
user_groups_binary_url | 200 characters (Utf8) | URL for the logo (image) of a user group |
view_settings | Array The following keys are available:
Possible values for all keys: 1: enable / show | note OCI must be enabled and “Use in iFrame” setting must be disabled. Compatible with the premium template only. OCI must be enabled and “Use in iFrame” setting must be disabled. Compatible with the premium template only. |
* Required Parameter
After successful login via the SSO interface, all functions are available as with the regular login via the login form. In addition, the regular login with username and password can optionally be disabled so that users can only log in to the PRINT LOUNGE via the SSO interface.
Transfer of dynamic list items
Dynamic list entries can be passed to the interface using the dynamic_lists SSO parameter. These can then be used by the user during personalization.
The dynamic list items are passed in JSON format.
The use of dynamic list entries transferred via SSO must first be activated in the special option (FSO) "List" of the respective text fields in the print templates.
Example of passing dynamic lists for the “Company” and “Department” text fields:
jsonSample Applications
Cancellation of an order
To cancel an order using the SSO interface, the following values are required during delivery:
Parameter Name | Required value |
|---|---|
request_time | Date and time of request in ISO-8501 format |
dest_page | cancel_order |
dest_id | Unique order code |
Transfer of Personalization Data
The SSO interface can be used to start the personalization of a specific item immediately after a successful login. To do this, the pers parameter must be passed with the value "true" and the dest_page parameter must be passed with the value "pers" via the SSO link.
In addition, the pers_data parameter can be used to pass the desired personalization data. There are two ways to pass data:
Personalization data as an array (the key corresponds to the personalization variable of the template and the corresponding value contains the desired personalization data).
ID of a stored record from the PRINT LOUNGE
Code example for generating the SSO link with personalization data in PHP:
php (new DateTimeImmutable)->format(DateTime::ISO8601), 'customer_user_name' => 'example_user', 'customer_firstname' => 'printy', 'customer_lastname' => 'tester', 'pers' => true, 'pers_data' => [ 'Company' => 'Example Company', 'Department' => 'Department 1' ] ]; passphrase = 'SECRET_RANDOM_PASSPHRASE'; $cipher = 'aes-128-gcm'; $initializationVectorLength = openssl_cipher_iv_length($cipher); $initializationVecotr = openssl_random_pseudo_bytes($initializationVectorLength); $encryptedShopUserData = openssl_encrypt(http_build_query($shopUserData), $cipher, $passphrase, 0, $iv); $ssoLoginLink = 'https://shop.print-server.net/sso.php?h=' . urlencode($encryptedShopUserData);]]>