Authentication Providers (Conf)

LDAP Providers

To add a new LDAP or AD provider, press the New LDAP Provider button, enter the name and press Save changes.

Hint

Important note: If an OU with a symbol is used, (e.g., OU=+1) it needs to be encoded to work in LDAP providers. Authentication providers offer two possibilities to do this. In both cases, the symbol in the OU needs to be encoded, so in our example +1 translates to 2B1 or "+1" (with quotationmarks).

• Option 1 to encode the OU would be the same as with addressbook providers: Leave the base path field empty. Instead configure the base path in the ldap URL field and encode the OU. In our example the "+1" would translate to 2B1. The URL should look like this: ldap://hostname.local:389/OU=\2B1,DC=GeniusBytes,DC=local.

• Option 2 would be to encode the OU in the baseUserPath. The possibilities (for our example OU=+1) are:

  • OU=+1,DC=GeniusBytes,DC=local

  • OU=2B1,DC=GeniusBytes,DC=local

  • OU="+1",DC=GeniusBytes,DC=local

• An alternative to option 2 is to write only the OU in the base path (so OU=+1, OU=2B1 or OU="+1") and add the other information into the basePath (in our example DC=GeniusBytes, DC=local).

Connection Info

• URL: the address of the external authentication system.

• UserDN: the user who performs queries on the provider.

• Password: the password of the user specified in userDN.

• Confirm password: the password entered in the upper field.

• Authentication Type [Advanced]: authentication mechanism used by the LDAP protocol. Possible values are SIMPLE or GSSAPI.

• Realm (only GSSAPI) [Advanced]: the GSSAPI/Kerberos authentication realm.

• Kerberos KDC (only GSSAPI) [Advanced]: the KDC (Key Distribution Center) for GSSAPI/Kerberos. Usually the Domain Controller.

• Base path: the starting path used to build the search path for queries.

• Dereference aliases: dereferenced aliases. For further details, refer to the Aliases and Dereferencing Aliases appendix.

Base

• Read groups: if checked, the provider can read groups.

• Alias management enabled: if checked, it enables the alias for users (alias management is helpful for managing users with more than one username).

Note

It can be enabled only in some specific environments. Do not use it in standard installation.

• Read user details: it is enabled by default. This setting let the server search for additional information from other authentication providers, when a mapping has been found.

• Username/password login lookup: if checked, the provider can authenticate using username and password.

• Card login lookup: the provider can authenticate using the card ID.

• Enabled Card Registration: Allow card registration in this provider. If enabled, card login should be activated as well. Please make sure the card registration attribute is configured.

• Delete existing on new card: if this is checked, any existing cards are deleted.

• PIN login lookup: the provider can authenticate using the PIN ID.

• Remove card/username domain: if checked, it enables to save users in the system through the username and without the user domain.

User mapping

Settings for searching filter:

• Base user path: the base path for the user search. The starting path is defined in the base path field inside the "Connection Info".

• Test connection username: it is a test user in the authentication provider (enter the username).

• Detail search filter: the filter for detailed information of the user.

• User's filter: the filter for the users. Use the username placeholder for the user matching.

• Email filter: the filter for emails. Use the mail placeholder for the email matching.

• User's card filter: the filter for the card ID. Use the card placeholder for the card matching.

• User's PIN card filter: the filter for the user's PIN card.

• User's PIN filter: the filter for the user's PIN.

Hint

In case of test connection username for MS AD, a sAMAccountName has to be configured, which has to be in the resulting user search path. If the search path is CN=Users,DC=GeniusBytes,DC=local and the test connection username is 'test_gb_user', a user with sAMAccountName 'test_gb_user' has to be found in test connection username.

Hint

There is no default attribute in AD for the card ID. Any field you select, replace the placeholder card in Card user filter.

• Username attribute: the attribute for the username, cn is the identifier used by the external provider.

• Card registration attribute: the name of the attribute used to store the card on card registration (write access required).

• Card PIN attribute: the attribute for the PIN card.

• Email attribute: the attribute for the email, the placeholder: mail is an identifier for an external provider.

• Home folder attribute: the attribute for the home folder of the user (in AD, the default attribute is homeDirectory even if it is not always used).

• Cost center attribute: the attribute for the cost center.

• Company attribute: the attribute for the company.

• Display name attribute: the attribute for the user display name.

• Extra# attribute (#=1..2): the attribute value for extra attributes.

These attributes are used to specify additional search filters. For example, in the active directory you can use "distinguishedName" to search the users.

• Custom field # attribute (#=0..9): searching keys for fields defined by the user.

• Delegation attribute: pull printing delegation field (more than one value is possible). Genius server attempts to fetch the LDAP attribute and setup a pull-printing delegation relationship between the logged in user (delegated user) and the usernames in the attribute (delegating users).

Group Mapping

Settings for group mapping:

• Base group path: the base group path is concatenated to the value, which has been entered in the base path (refer to the Connection Info section) to search for groups.

• Group filter: the filter useful for the group. Specify the name of a group.

• Group member filter: the filter useful to search for a member of the group.

• Group name attribute: the attribute of the name of the group.

• Group search scope: the scope for a group search. Possible values are SUBTREE and ONELEVEL.

• Group time limit: the group time limit in ms.

[Advanced] Avanced Features

• Connection timeout: the connection timeout in milliseconds.

• Read timeout: the read timeout.

• Context pooled: if checked, it enables connection pooling.

LDAP caches the password for a specific user and password combination with pooled connections.

1. Authenticate with user "cn=joe, dc=de" and password "test" -> Result: true.

2. Change the userPassword Attribute to "newtest".

3. Authenticate with user "cn=joe, dc=de" and password "test" -> Result: true!!.

4. Restart the LDAP provider.

5. Authenticate for user "cn=joe, dc=de" and password "test" -> Result: false.

Uncheck the connection pooling, to solve this issue.

• Additional group names: additional group names separated by a comma.

• Card validation pattern: the card number validation pattern.

• Card pre processing script: Python scripts to pre process the card token. For example to read the integer value from the card: int(card); or to remove a prefix: card.replace('GENIUS', ''); or to take the last 6 characters card[-6:]; or the first 5 card[:5], or to invert the read characters card[::-1].

To check the connection info, press Check connection button.

To test the manual login, press the Manual login button, enter the user, and click on the Test button.

To test the card login, press the Card login button, enter the card token, and click on the Test button.

To test the PIN login, press the PIN login button, enter the PIN code, and click on the Test button.

To query a user, press the Query user button, enter the user, and click on the Test button.

To query a group of users, press the Query user groups button, enter the user, and click on the Test button.

To save the new configuration, press the Save changes button.

Deploy Target

• Target Nodes: Target nodes: if any node is selected, the feature is automatically enabled on all of them.

Tests

To check the connection info, press Check connection button.

To test the manual login, press the Manual login button, enter the user and click on the Test button.

To test the card login, press the Card login button, enter the card token and click on the Test button.

To test the PIN login, press the PIN login button, enter the PIN code and click on the Test button.

To query a user, press the Query users button, enter the user and click on the Test button.

To query a user by email, press the Query user by email button, enter the email and click on the Test button.

To query a group, press the Query groups button, enter the group and click on the Test button.

To query a group of users, press the Query user groups button, enter the user, and click on the Test button.

To save the new configuration, press the Save changes button and then Back.

Commonly Used Attributes

In the table below, some attributes which are used in LDAP/AD context with their description are shown. Further details are available on RFC-4519.

Name	Alias	Description
cn	commonName	Typically the person's full name (e.g. John Doe)
dc	domainComponent	The component of a DNS domain name. (e.g. Host or component name: mycompany.com -> dc=mycompany,dc=com)
o	organizationName	Name of an organization (e.g. Geniusbytes)
ou	organisationalUnitName	Usually department names or name office (e.g. Marketing, Resources)
postalAddress	postalAddress	Addresses used by Postal Service (e.g. 12 E 1st Street New York)
sn	surname	Surname or family name (e.g. Smith)
st	stateOrProvinceName	Full names of states or provinces (e.g. Germany, Italy)
street	streetAddress	Site information from Postal Service (e.g. 12 E 1st Street)
uid	userid	Username or other unique values (e.g. admin)
mail	mail	The user's mail address

Placeholder

Placeholders are special words that are intended to be substituted by some values pertaining to the context in which they are used. These special words can be used when a mapping or a search are required.

To use a placeholder, put a key word in the braces.

Key words are:

• username: the name to be displayed.

• email: the email of the user.

• authenticationid: the authentication ID of the user.

• card: the card ID of the user.

• pin: the PIN code of the user.

• groupname: the name of a group.

• extra1..2: extra attributes.

• custom0..9: custom field attributes.

LDAP/AD Errors Troubleshooting

If LDAP or AD do not behave as desired and you receive an error message, check the Error Code Table table below to find out what problem has occurred and how to solve it.

Users are unable to log in

While testing LDAP/AD, an error as the following ones can occur (the account is expired):

javax.naming.AuthenticationException: [LDAP: error code 49 - 80090308:
LdapErr: DSID-0C0903A9, comment: AcceptSecurityContext error, data 701, v1db0]

It can happen for many reasons. Check the error code (in the example above, the code is 701) and find its description in the Error Code Table below.

Error Code Table

Error code	Description
52e	invalid credentials
525	user not found
530	not permitted to logon at this time
531	not permitted to logon at this workstation
532	password expired (remember to check the user set in osuser.xml also)
533	account disabled
701	account expired
773	user must reset password
775	user account locked

Special Characters

Make sure that special characters in LDAP/AD query strings are protected. A special character should be preceded by a \ symbol.

A node in the external provider can contain special literals, for example test/test. This kind of query can fail if the special characters are not protected. If the node ou=test/test is replaced by ou=test\/test or ou=test\2ftest, the query executor finds the node.

The table below shows a list of ASCII symbols with the corresponding substitutes: the escape characters.

ASCII character	Escape sequence substitute
*	\2a
(	\28
)	\29
\	\5c
NUL	\00
/	\2f

Database Provider

To add a new database provider, press the New database provider button, enter the name and press the Save button.

Connection Info

Users can use default connection settings for different database types: PostgreSQL, MySQL, H2, Oracle and MS SQL Server.

Select a configuration pressing the < Preset > menu button and select the database type.

A description of the connection settings follows:

• JDBC Driver: the JDBC Driver class to connect to the database.

• JDBC URL: the complete JDBC Connection URL.

• Username: the database username.

• Password: the database password.

• Confirm password: the password entered in the upper field.

Base

• Enable Group Management: if checked, database queries for group information are enabled. When enabled, fill in the settings found in the Group Mapping section.

• Enable Alias Management: if checked, it enables alias for users (using alias management you can manage users with more than one username). When enabled, fill in the settings found in the Alias Mapping section.

• Enable Delegation Management: if checked, the database can be queried for delegation information. When enabled, fill in the settings found in the Delegation Mapping section.

• Enable User Detail Management: if checked, the database can be queried for user detail information. When enabled, fill in the settings found in the User Details Mapping section.

• Enable Username/Password Login: if checked, it enables users to authenticate using username and password. When enabled, fill in the settings found in the User Mapping section.

• Enable Card Login: if checked, it enables users to authenticate using the card ID. When enabled, fill in the settings found in the Card Mapping section.

• Enabled Card Registration: allows card registration in this provider. If enabled, card login should be activated as well. Expressions like 'lower(username)' in the card mapping configuration are not supported if card registration is enabled.

• Enable PIN Login: if checked, it enables users to authenticate using the PIN code. When enabled, fill in the settings found in the PIN Mapping section.

[Advanced] Datasource

• Initial pool size: the number of connections a pool tries to acquire upon startup. The value should be between Min Pool Size and Max Pool Size.

• Min pool size: the minimum number of connections a pool maintains at any given time.

• Max pool size: the maximum number of connections a pool maintains at any given time.

• Max idle time: in seconds. A connection can remain pooled but unused before it is discarded. Zero means idle connections never expire.

• Checkout timeout: the number of milliseconds a client calling getConnection() waits for a connection to be checked-in or acquired when the pool is exhausted. Zero means to wait indefinitely. Setting any positive value causes the getConnection() call to time-out and break with an SQLException after the specified number of milliseconds.

• Max statements per connection: the number of Prepared Statements c3p0 caches a single pooled Connection. If both Max Statements and Max Statements Per Connection are zero, statement caching is not enabled. If Max Statements Per Connection is zero but Max Statements is a non-zero value, statement caching is enabled, and a global limit enforced, but otherwise no limits are set on the number of cached statements for a single Connection. If set, Max Statements Per Connection should be set to the number distinct prepared statements that are used frequently in your application, plus two or three extra so infrequently statements don't force the more common cached statements to be culled. Though Max Statements is the JDBC standard parameter for controlling statement caching, users may find Max Statements Per Connection more intuitive to use.

• Idle connection test period: if it is a number greater than 0, every specified number of seconds, c3p0 tests all the idled, pooled but unchecked-out connections.

• Acquire increment: it determines how many connections at a time c3p0 tries to acquire when the pool is exhausted.

• Acquire retry attempts: it defines how many times c3p0 tries to acquire a new connection from the database before giving up. If this value is less than or equal to zero, c3p0 keeps trying to fetch a connection indefinitely.

• Acquire retry delay: in milliseconds, time of waiting from an attempt to the next one.

• Break after acquire failure: if checked, a pooled Data Source declares itself as broken and permanently closed if a Connection cannot be obtained from the database after making Acquire Retry Attempts to acquire one. If unchecked, the failure to obtain a Connection causes all threads waiting for the pool to acquire a Connection to throw an exception, but the data source remains valid, and attempts to acquire again a call to getConnection().

• Max connection age: the actual maximum time of connection, in seconds. After that period of time, the connection is destroyed and purged from the pool. This differs from Max Idle Time, which refers to the absolute age. Even a Connection which has not been much idle will be purged from the pool if it exceeds Max Connection Age. Zero means no maximum absolute age is enforced.

• Max idle time excess: the number of seconds during which connections in excess of Min Pool Size can remain idle in the pool before being culled. It is intended for those applications that aggressively minimize the number of open Connections, shrinking the pool back towards Min Pool Size if the load level diminishes and Connections acquired are no longer needed, following a spike. If Max Idle Time is set, Max Idle Time Excess Connections should be smaller if the parameter does not have any effect. Zero means no enforcement, excess Connections are not idled out.

• Test connection on check-in: if checked, an operation is performed asynchronously at every connection checkin to verify that the connection is valid. Together with idle Connection Test Period for quite reliable, use always asynchronous Connection testing. Besides, setting an Automatic Test Table or Preferred Test Query usually speeds up all connection tests.

• Test connection on checkout: check it only if necessary. Expensive. If checked, an operation is performed at every connection checkout to verify that the connection is valid. Better choice: verify connections periodically using the Idle Connection Test Period. Besides, setting an Automatic Test Table or Preferred Test Query usually speeds up all connection tests.

• Preferred test query: the query that is executed for all connection tests, when the default Connection Tester (or other implementations of the Query Connection Tester, or of the Full Query Connection Tester) is being used. Defining a preferred Test Query executed quickly in your database may dramatically speeds up Connection tests. If any Preferred Test Query is set, the default Connection Tester executes a getTables() call on the Connection's Database MetaData. On some databases, this maye be executed more slowly than a "normal" database query.

• Unreturned connection timeout: if set, an application checks out but then it fails to check-in [i.e. close()] a Connection within the specified period of time, the pool unceremoniously destroys() the connection. This permits applications with occasional Connection leak to survive, rather than eventually exhausting the connection pool. Zero means no timeout, applications are expected to close() their own Connections. If a non-zero value is set, it should be a value longer than any connection, which should reasonably be checked out. Otherwise, the pool occasionally kills the connections in active use.

• Debug unreturned connection: if checked, and if Unreturned Connection Timeout is set to a positive value, the pool captures the stack trace (through an Exception) of all connection checkouts, and the stack traces are printed at the unreturned checked out Connections timeout. This is intended to debug applications with connection leaks. Use it for applications that occasionally fail to return connections, which leads to the pool growth, and eventually exhaustion (when the pool hits Max Pool Size with all connections checked out and lost). This parameter should only be set while debugging, as capturing the stack trace slows down every connection check out.

• Number helper threads: c3p0 is very asynchronous. Slow JDBC operations are generally performed by helper threads that don't hold contended locks. Spreading these operations over multiple threads can significantly improve performances allowing multiple operations to be performed simultaneously.

Note

Further details about c3p0 are available on site http://www.mchange.com/projects/c3p0/.

User Mapping

Mapping information allows users to search in the custom database:

• Users Table: the database table with username and password information.

• Username Column: the username column in the users table (the username must be written in lower case letters).

• Password Column: the password column in the users table.

• Password Hash Algorithm: if passwords are stored as hash values in the database, select the correct algorithm.

• Password Hash Salted: if checked, the salt which is used to generate the hash code. Check if the password hashes are salted with the user name ("password{username}"). Users can randomize hashes appending or prepending a random string (called salt), to the password before hashing.

Card Mapping

Mapping information allows the user card to search in the custom database:

• Cards Table: the database table which contains the card information. This may or may not be equal to the user table.

• Username Column: the username column in the card table.

• Card Column: the card column in the cards table.

• Card Hash Algorithm: if the cards are stored as hash values in the database, select the correct algorithm:

  • NONE: no hash values selected.

  • SHA.

  • SHA_BASE64.

  • SHA256.

  • SHA256_BASE64.

  • SHA512.

  • SHA512_BASE64.

  • MD5.

  • MD5_BASE64.

• Card PIN Column: the card PIN column in the cards table.

• Card PIN Hash Algorithm: if the card PINs are stored as hash values in the database, select the correct algorithm:

  • NONE: no hash values selected.

  • SHA.

  • SHA_BASE64.

  • SHA256.

  • SHA256_BASE64.

  • SHA512.

  • SHA512_BASE64.

  • MD5.

  • MD5_BASE64.

PIN Mapping

Mapping information allows to search for the user authentication ID into custom database:

• PIN Table: the database table with the PIN information. This may or may not be equal to the user table.

• Username Column: the username column in the authentication ID table.

• PIN Column: the authentication id column in the PIN table.

• ID Hash Algorithm: if the authentication ids are stored as hash values in the database, select the correct algorithm:

  • NONE: no hash values selected.

  • SHA.

  • SHA_BASE64.

  • SHA256.

  • SHA256_BASE64.

  • SHA512.

  • SHA512_BASE64.

  • MD5.

  • MD5_BASE64.

User Details Mapping

User details information:

• User Details Table: the database table which contains the information on user details . This may or may not be equal to the user table.

• Detail search filter: the WHERE condition which is used in the query to search for user's details (e.g. username='{filter}').

• Username Column: the username column in the user detail table (the username must be written in lower case letters).

• Language Column: the locale column in the user detail table.

• Display Name Column: the display name column in the user details table,

• Email Column: the email column in the user detail table.

• Home folder Column: the home folder column in the user detail table.

• Cost Center Column: the cost center column in the user detail table.

• Company Column: the company column inside the user details table.

• Can Login Column: the can login column in the user detail table (true/false).

• Extra Field# Column (#=1..2): extra attribute columns into user detail table.

• Custom Field# Column (#=0..9): custom field attribute columns into user detail table.

Group Mapping

Mapping group names:

• Group Table: the database table which contains information on the group. This table and the users table may correspond if every user belongs only to a single group.

• Username Column: the username column in the groups table (the username must be written in lower case letters).

• Group name Column: the group name column in the groups table.

Alias Mapping

Mapping user aliases:

• Alias Table: the database table that contains alias information. If every user has only a single alias, alias table and the users table correspond.

• Username Column: the username column in the alias table (write the username in lower case letters).

• Alias Column: the alias column in the alias table.

Delegation Mapping

• Delegations Table: pull printing delegation table.

• Username Column: delegated username column.

• Delegating Username Column: delegating username column.

[Advanced] Advanced Features

• Additional group names (,): additional group names separated by a comma.

Deploy Target

• Target Nodes: Target nodes: if any node is selected, the feature is automatically enabled on all of them.

Connection Test

After you have set the configuration, to test the connection to the database, and press the Test configuration button.

To test the user authentication, press the Test password login button, enter the credential and press the Test button.

To test the card login, press the Test card login button, enter the card, and click on the Test button.

To test the PIN login, press the Test PIN login button, enter the PIN code, and click on the Test button.

To save the new configuration, press the Save button.

To edit a provider, select the provider to edit, and press the Edit button. To save changes, press the Save Changes button and then Back.

To delete a provider, select the provider to delete, press the Trash button, and then Confirm.

To save, press the Save changes button and then Back.

Note

After configuration changes are made, restart the Genius Server.

Searching Order

To change the search order, select the two authentication providers that are about to swap places by clicking the checkbox next to their names on the overview. Then click Change order on the top.

New Microsoft AZURE Provider

To create a new Microsoft Azure authentication provider click the corresponding button. To edit a Microsoft Azure authentication provider select it and click Edit.

Connection

• Tenant name: the name of the microsoft domain.

• Default domain: if checked, the user can login without the domain and the tenant name will be used automatically.

• Web/API Client ID: the client ID created inside the azure portal.

• Web/API Secret: the secret created inside the azure portal.

• Confirm Web/API Secret: confirm the above entered secret.

• Client timeout: the amount of time after wich a timeout occurs, when trying to send requests or get responses to or from Microsoft.

Authentication

• Login enabled: if checked, authentication is done against the configured authentication providers.

• Card login enabled: enables card login.

• Card+PIN login enabled: enables Cardpin login.

• PIN login enabled: enables PIN login.

• Native/Public Client ID: the client ID of the Microsoft native/public app created.

• Single-Sign-On Mode: if you want to use single sign on (SSO) choose the mode here. Possible values are:

  • AUTO

  • LOGIN

  • SELECT_ACCOUNT

  • CONSENT

Attribute Mapping

• Username: attribute in Azure AD for the username.

• Display Name: attribute in Azure AD for the display name.

• Printjob Owner: attribute in Azure AD for matching printjob owner. Resulting printjob owner has to be unique!

• Mail: attribute in Azure AD for the mail address.

• Home Folder: the attribute in the Azure AD for the home folder.

• Account Enabled: attribute in Azure AD for the account enabled value.

• Cost Center: attribute in Azure AD for cost center.

• Company: attribute for company name.

• Extra 1: extra attribute 1.

• Extra 2: extra attribute 2.

• Card Attribute: the name of the attribute used to store the card on card registration (write access required)

• Card PIN Attribute: the card pin attribute.

• PIN Attribute: the pin attribute.

• Custom Field #0-9: custom fields for attributes.

• Delegation: attribute for delegation.

Deploy

Choose the target nodes. If any node is selected, the feature is automatically enabled on all of them.

Testing the Connection

Now you can and should test your connection.

To test the user authentication, press the Authentication button, enter the credential and press the Test button.

To test if getting user details works, press the Get user details button, enter the username from which you want to get details and press Test.

To test the card login, press the Test card login button, enter the card ID, and click on the Test button.

To test the PIN login, press the Test PIN login button, enter the PIN code, and click on the Test button.

To test Card+PIN login, press the Card + PIN login button, enter the card ID, enter the card PIN and confirm it. Afterwards click on the Test button.

To test if user groups can be fetched, press the Get user groups button, enter a username and press test.

To get back from a test without performing the test, click the Back button.

To save the new configuration, press the Save button.

To edit a provider, select the provider to edit, and press the Edit button. To save changes, press the Save Changes button and then Back.

To delete a provider, select the provider to delete, press the Trash button, and then Confirm.

To save, press the Save changes button and then Back.

If everything is configured correctly, press Save, then Back. You can Edit existing providers or Delete them. The order of the providers can be changed by clicking on the blue arrows next to the Delete button.

Note

When configuring the provider, make sure to trust the certificates that lead to the Microsoft Graph-API. We recommend to configure the Genius Server to use the Windows truststores to keep certificate handling more simple. For an introduction on this topic, please refer to the whitepaper GB-Whitepaper-SSL-ENG.pdf which can be found in the download area.