Adlib API home page > Documentation > User authentication setup

User authentication setup

The Adlib API offers two (previously three) different methods to validate and retrieve user credentials through the login command:

  • Based on an Adlib database
  • Based on Active Directory
  • Based on an SQL Server membership database (database aspnetdb), only valid from API version 3.6.272.0 up to 3.6.1224.

From Adlib API version 3.6.272.0 up to 3.6.1224, user authentication had to be set up in the web.config file for the wwwopac.ashx, and the authentication details were stored per user, either in an Adlib database, Active Directory or an SQL Server membership database; see the paragraphs 2.1 up to and including 2.3 below for more information.
From wwwopac.ashx 3.6.1225 however, user authentication must be set up in the adlibweb.xml file (again) instead of in web.config, and the authentication details are stored per user, either in an Adlib database or Active Directory, or in both. Per user authentication source (Active Directory or an Adlib database like Borrower or DBuser - see paragraph 2.1 for information about DBuser), you can specify an authentication configuration section in adlibweb.xml, mapping source fields to Adlib XML tags. For Active Directory authentication, use the .NET UserPrincipal property names of a user as the source field names. The wwwopac.ashx will automatically return the Active Directory groups/roles to which the user has been assigned, in the login reply. In the (partially optional) mapping for an Adlib database you could include fields other than the user name and password fields stored in the user details records, not because they are required for authentication but for anything else you might want to do with that data. Do always map the borrower_number field here if you have an Adlib Internet Server web application and you want visitors (borro- wers) to be able to make reservations via your website.
The <defaultGroups> section is used to assign one or more default group names (roles) to every logged-in user. These are returned in the login reply, as well as groups retrieved from the other authentication sources. If you have an Adlib Internet Server web application, these default group names can be used to selectively enable website functionality for all logged-in visitors (via the <authorization> section in globalsettings.xml). You cannot leave the <defaultGroups> section out: at least one (empty or filled) <group> node must be present. The default group names can be any names you find descriptive.
If you specify more than one authentication configuration section, then on login they will be read consecutively from top to bottom to collect all user authentication details from all these sources (when applicable) and deliver those in a single record in Adlib XML format to the client. If the client is an Adlib Internet Server web application, these details can be used for accessing different user-authenticated services like making reservations or adding comments and tags to detail catalogue records. See paragraph 1.1 and 1.2 below for configuration examples.
Although there are two (or three) types of user authentication, login always has to be explicit. The format of the login request is the same for all methods.

1.1 Adlibweb.xml configuration based on an Adlib database

<authenticationConfiguration> 
  <type>Database</type> 
  <databasePath>C:\Adlib SQL\data</databasePath> 
  <database>borrower</database> 
  <userIdField>borrower_name</userIdField> 
  <passwordField>borrower_number</passwordField> 
<!-- Instead of borrower_number, you could use the e-mail_address field, for example. -->
<!-- <passwordField>e-mail_address</passwordField> -->  
<!-- If you have a field in which user groups or roles have been registered, you can include it here. -->
  <groupsField>borrower_category</groupsField> 

  <map> 
    <source>first_name</source> 
    <destination>first_name</destination> 
  </map> 
  <map> 
    <source>last_name</source> 
    <destination>last_name</destination> 
  </map> 
  <map> 
    <source>borrower_name</source> 
    <destination>borrower_name</destination> 
  </map> 
  <map> 
    <source>borrower_number</source> 
    <destination>borrower_number</destination> 
  </map> 
  <map> 
    <source>e-mail_address</source> 
    <destination>e-mail_address</destination> 
  </map> 

<!-- The Internet Server 5 web application can use default groups to selectively enable functionality. -->
  <defaultGroups> 
    <group>Borrower</group> 
    <group>Reserver</group> 
    <group>SDIUser</group> 
    <group>Admin</group>
  </defaulGroups> 
</authenticationConfiguration>

1.2 Adlibweb.xml configuration based on an Active Directory

<authenticationConfiguration> 
  <type>ActiveDirectory</type> 
  <map> 
    <source>GivenName</source> 
    <destination>firstname</destination> 
  </map> 
  <map> 
    <source>Surname</source> 
    <destination>lastname</destination> 
  </map> 
  <map> 
    <source>EmailAddress</source> 
    <destination>email</destination> 
  </map> 
</authenticationConfiguration> 

 

---------------- Obsolete web.config configuration ----------------

2.1 Web.config configuration based on an Adlib database

Add settings similar to the following, inside the system.web section of the web.config file:

<membership defaultProvider="AdlibMembershipProvider" >
  <providers>
    <add name="AdlibMembershipProvider"
      type="Adlib.Security.AdlibMembershipProvider"
      database="D:\ourserver\Adlib\data\dbuser"
      usernamefield="login"
      passwordfield="password"
      domainfield="domain"
      firstnamefield ="firstname"
      lastnamefield="lastname"/>
  </providers>
</membership>

<roleManager defaultProvider="AdlibRoleProvider"
      enabled="true"
      cacheRolesInCookie="true"
      cookieName=".ASPROLES"
      cookieTimeout="30"
      cookiePath="/"
      cookieRequireSSL="true"
      cookieSlidingExpiration="true"
      cookieProtection="All" >
  <providers>
    <add name="AdlibRoleProvider"
      type="Adlib.Security.AdlibRoleProvider"
      database="D:\ourserver\Adlib\data\dbuser"
      usernamefield="login"
      domainfield="domain"
      rolefield="role"/>
  </providers>
</roleManager>

For this authentication method, you need to have an extra Adlib database containing fields for the user name, password, role, domain, first name and last name. The field names must be used in the configuration code above. Via Adlib Designer you can create the extra .inf file in your data dictionary; the database attributes in the code above must contain the path to this .inf file, in our case dbuser.inf without the file extension. After you've done this, you must still convert the .inf file into a table in your Adlib SQL database, with the Adlib CBFtoSQL tool. In Designer, you must also create a data source for this database in your application structure, along with screens to be able to enter user credentials into records.
In the database(s) available to your API application users, which must be protected by user authentication, you must apply the Adlib record access rights mechanism, which means that you'll have to add some fields there as well for user names and possibly their access rights. See the Designer Help for information about how to do this. When you're finished, you'll be able to decide per record if it must be accessible to certain users or not.
Along with the correct user authentication setup in the web.config, wwwopac.ashx will automatically apply access rights where applicable, whether you explicitly login or not. If you do not login, or login with a user name not listed in a record, access to the record will depend on the Default access rights set for the database. If you do login, access to a record will depend on the access rights assigned to this user in the record.
Note that with this authentication method the user names, possibly their access rights and the record owner are stored in retrievable catalogue records, and users with access to those records will be able to read this data from the records if said fields have been included in the detail fields specification in adlibweb.xml. However, if the authorisation type Rights has been applied, only the owner of a record will be able to change this authorisation data; other users cannot change it.
Access rights applied to roles, as is common with other Adlib access rights mechanisms, cannot be applied through wwwopac.ashx yet.

Notes about the web.config code

  • The domainfield, firstnamefield and lastnamefield are optional attributes.
  • The firstname and lastname nodes in the XML result of the login command are specific for user authentication based on an Adlib database, and require that the firstnamefield and lastnamefield attributes are specified.

2.2 Web.config configuration based on Active Directory

This method uses the built-in ActiveDirectoryMembership- Provider and AuthorizationStoreRoleProvider provided by the ASP.NET framework.
Here’s an example of a possible configuration. Inside the connection strings group, include your LDAP server configuration:

<add name="ADService" connectionString="LDAP://myldapserver.mydomain.com/DC=mydomain,DC=com" />

Add the following settings inside the system.web section:

<membership defaultProvider="AspNetActiveDirectoryMembershipProvider" >
  <providers>
    <add name="AspNetActiveDirectoryMembershipProvider"
      type="System.Web.Security.ActiveDirectoryMembershipProvider"
      connectionStringName="ADService"
      attributeMapUsername="SAMAccountName"/>
  </providers>
</membership>

For more information about setting up this type of user authentication, please see:

http://msdn.microsoft.com/en-us/library/system.web.security.activedirectorymembershipprovider.aspx

http://msdn.microsoft.com/en-us/library/system.web.security.authorizationstoreroleprovider.aspx

2.3 Web.config configuration based on an SQL Server membership database (database aspnetdb)

This method uses the built-in SqlMembershipProvider and SqlRoleProvider provided by the ASP.NET framework.
Here’s an example of a possible configuration. Inside the connection strings group, include your SQL Server configuration:

<add name="sql-membership" connectionString="Data Source=SQLSERVER2008;Initial Catalog=sql-membership;uid=sql-membership-user;password=sql-membership-password;"/>

Add the following settings inside the system.web section:

<membership defaultProvider="AspNetActiveDirectoryMembershipProvider" >
<providers>
<add connectionStringName="adlib-sql-membership" enablePasswordReset="true"
enablePasswordRetrieval="false" requiresQuestionAndAnswer="false"
requiresUniqueEmail="true" passwordFormat="Hashed" maxInvalidPasswordAttempts="5"
passwordAttemptWindow="10" applicationName="AppTest" minRequiredPasswordLength="5"
minRequiredNonalphanumericCharacters="0" name="AspNetMembershipProvider"
type="System.Web.Security.SqlMembershipProvider" />
</providers>
</membership>
<roleManager defaultProvider="AdlibRoleProvider"
enabled="true"
cacheRolesInCookie="true"
cookieName=".ASPROLES"
cookieTimeout="30"
cookiePath="/"
cookieRequireSSL="true"
cookieSlidingExpiration="true"
cookieProtection="All" >
<providers>
<add name="SqlProvider"
type="System.Web.Security.SqlRoleProvider"
connectionStringName="adlib-sql-membership"
applicationName="/"
</providers>
</roleManager>

For more information about setting up this type of user authentication, please see:

http://msdn.microsoft.com/en-us/library/system.web.security.sqlmembershipprovider.aspx

http://msdn.microsoft.com/en-us/library/system.web.security.sqlroleprovider.aspx

Note: membership providers and roles providers are independent modules with a link between them based on the user name and domain (or application name). It’s possible to combine membership and role providers supported by different methods. For instance, you can set up an Active Directory membership provider with a roles provider that is supported by an Adlib database.