Axiell WebAPI home page > Documentation > User authentication setup

WebAPI Browser

User authentication setup

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

Based on an Axiell Collections database
Based on Active Directory
Based on a SQL Server membership database (database aspnetdb), only valid from WebAPI version 3.6.272.0 up to 3.6.1224.

From Axiell WebAPI 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 Axiell Collections database, Active Directory or a 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 Axiell Collections database or Active Directory, or in both. Per user authentication source (Active Directory or an Axiell Collections 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 Axiell AdlibXML 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 Axiell Collections 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 Axiell Internet Server web application and you want visitors (borrowers) 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 Axiell 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 Axiell AdlibXML format to the client. If the client is an Axiell 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 Axiell Collections database

<authenticationConfiguration> 
  <type>Database</type> 
  <databasePath>C:\Axiell 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 6 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 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 Axiell 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 SQL Server database, with the Axiell 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 WebAPI application users, which must be protected by user authentication, you must apply the Collections 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 Collections 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 Axiell Collections 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 a 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 Axiell Collections database.