Authentication with Aptify Services API

Aptify SOA supports secure access to its web services.  In most cases, service endpoints require the caller to be authenticated before the endpoint can be accessed.  When a service endpoint requires an authenticated user, a token is provided to the service.  If the token is valid, access will be granted.  If no token is provided or the token is invalid, the service endpoint will return Not Found (404) as the response code.  Not Found is used instead of Forbidden (403) or Unauthorized (401) to reduce the information provided to unauthorized callers.  Any response other than Not Found lets the caller know that an endpoint exists.

Aptify provides applications that target two different types of users.  The first user type is primarily an association’s staff.  The second other type is the association’s members.  The former uses Aptify User accounts and the latter uses Web User accounts. 

Aptify Users are individually licensed users with complete control over security at all levels, UI, Business Layer, and Database. 

Web Users are not individually licensed users.  They become available and are used by Aptify e-Business and other applications like Aptify Mobile for Members.  Aptify does not limit the number of Web Users.  Web Users and applications used by Web Users include authentication and authorization using a separate model from Aptify Users.  Aptify’s authentication endpoints support both Aptify Users and Web Users based on information configured in metadata.

There are four types of Authentication Providers.  The first three apply to Aptify Users.  The remaining Provider applies to Web Users:

DomainUser Authentication

Authentication based on a Windows Domain. Authentication is performed by validating logon to the domain using the username and password provided. If it is successful then the user is logged in as a trusted user to Aptify.  All operations within endpoints that require authentication will impersonate the Domain User. 

SQL User Authentication

Authentication occurs against a SQLLogin that uses SQL Server Authentication, not Windows Authentication.  This provider expects the service request to include the UserName and Password for the User.  The SQLLogin must exist, the password match and be an active, licensed User in Aptify.  All database operations through authenticated service endpoints will use this Login.

 IIS Managed Authentication

Authentication based on a Windows Domain.  Authentication is performed by validating login to the domain user.  This is similar to DomainUser authentication but relies on IIS to authenticate the user at the Windows level, once that has been performed then this provider verifies the user is a valid User in the Aptify.  If it is successful then the user is logged in as a trusted user to Aptify.  All operations within endpoints that require authentication will impersonate the Domain User.

Web User Authentication

Authentication based on the Web Users Entity stored in Aptify. User Name and Password must be provided in the service request.  The User Name and Password will be used against the Web Users information and verify that the Web User is active.  The Web User login endpoint supports both GET and POST actions. For GET, use query parameters to send the username and password; for POST, send them as form data.

Web User Authentication Example

Prerequisites:

The Aptify database connected to Aptify SOA must support the Web Users Authentication Provider and have it linked to the Service Application represented. The services layer in IIS needs anonymous authentication, and ONLY anonymous authentication turned on. The services layer should be using HTTPS.

Endpoint

https://<service base>/AptifyServicesAPI/Services/Authentication/Login/Web

Parameters (GET, as Query Parameters)

Endpoint Example using Web Authentication Provider:

https://<service base>/AptifyServicesAPI/Services/Authentication/Login/Web?UserName=username&Password=password

Request Body (POST, as Form Data)

{
	UserName: "username",
	Password: "password"
}

Response Body (Authenticated) Example

{
	UserId: 1,						// Web User ID
	UserName: "UserName",
	Email: "name@email.com",
	FirstName: "Firstname",
	LastName: "Lastname",
	Title: "Title",
	LinkId: 2						// Person ID
	CompanyId: 3
	TokenId: "abcdefg",				// Token to send with future service requests
	Server: "server",
	Database: "Aptify",
	AptifyUserID: 4,				// User ID of the application pool user running the AptifyServicesAPI site
	AptifyUser: "AptifyUserName"	// User Name of the application pool user running the AptifyServicesAPI site
}

Here you will get back three separate IDs related to web user who is logging in:

• UserId is the ID of web User in Aptify.
• LinkId is the ID of Person Record in Aptify which is linked to Web user record.  Person ID is the canonical representation of a person in the system. 
• AptifyUserId is the ID of the user record in Aptify that is executing the website.

Response Body (Unsuccessful) Example

{
	LinkId: "",						
	ErrorInfo: {
		ErrorType: "W",
		ErrorMessage: "Incorrect User ID or Password"
	},
	Server: "server",
	Database: "Aptify",
	AptifyUserID: 4,				// User ID of the master eBiz User
	AptifyUser: "AptifyUserName"	// User Name of the master eBiz User
}

The TokenId you receive is a GUID you will use to make requests to authenticated endpoints. You send it as a header, prefixed by "Web" and a single space character. The following example illustrates the header for identifying an authenticated web user.