| Warning |
|---|
Using Web User authentication currently gives you all the permissions of the User in Aptify that runs the eBiz web site. This user may have elevated permissions, so you will have to implement any limitations the Web User should have in your own logic. This should be addressed in future versions of the API. |
Prerequisites
The Aptify database connected to Aptify SOA must support the Web Users Authentication Provider and have it linked to the HTML5 Web Service Application. The services layer in IIS needs anonymous authentication, and ONLY anonymous authentication, turned on. The services layer should be using HTTPS.
Types Of Authentication Provider
There are seven types of authentication provider available in aptify.
...
SQL User Authentication Provider (SQL)
With this provider a non-trusted user is authenticated against a SQL server database. This provider expects the two request parameters ‘Username’ and ‘Password’ in querystring. The user have logon authority against the database and also is user in Aptify.
Domain User Authentication Provider (Domain)
...
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.
...
...
Web User Authentication Provider (Web)
Authenticate an Aptify WebUser. Web User authentication relies on HTTPS for encryption. The Web User login endpoint supports both GET and POST actions. For GET, use query parameters to send the user name and password; for POST, send them as form data.This provider will recreate the UserCredentials on token validation if they have been lost.
IIS Managed Authentication Provider (IIS)
...
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
...
.
...
...
vNext Authentication Provider (vNext)
Authenticates user against Aptify Web.Once validated it produce some additional information corresponding to that user.
...
Domain User(with container) Authentication Provider (DomainWithContainer)
Authenticates a user against a windows domain and aptify.
...
SQL User (needs input with container) Authentication Provider (SQLNeedsInputWithContainer)
Authenticates a user using SQL Server database .
Endpoint
| Cached? | No |
User authentication relies on HTTPS for encryption. Before attempting to authenticate, you should try the UserInformation endpoint. This is lighter-weight than authentication, and will give you your token if you've already authenticated.
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 user name 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
| Cached? | No |
| Code Block |
|---|
https://<service base>/AptifyServicesAPI/Services/Authentication/Login/<Authentication Provider>Web |
Parameters (GET, as Query Parameters)
| Parameter Name |
|---|
| UserName |
| Password |
Following example illustrated using web user authentication provider.
Example
Endpoint Example using Web Authentication Provider:
| Code Block |
|---|
https://<service base>/AptifyServicesAPI/Services/Authentication/Login/webWeb?UserName=username&Password=password |
...
| Code Block |
|---|
{
UserName: "username",
Password: "password"
} |
Response Body (
...
Authenticated) Example
| Code Block |
|---|
{
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 master eBiz User application pool user running the AptifyServicesAPI site
AptifyUser: "AptifyUserName" // User Name of the master eBiz Userapplication pool user running the AptifyServicesAPI site
} |
Note that Here you will get back three separate IDs related to the Web User 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
| Code Block |
|---|
{
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
} |
Note the lack of a TokenId, the empty LinkId, and the presence of an error message.
| Warning |
|---|
Do not rely on anything but the ErrorInfo and ErrorMessage; other information may be removed in future versions of the API. |
Token Use
The TokenId you receive is a GUID you will use to make requests to authenticated endpoints. You send it as a header, prefixed by authentication provider "Web" and a single space character:. The following example illustrates the header for identifying an authenticated web user.
| Header Name | Header Value |
|---|---|
| AptifyAuthorization | <Authentication Provider> <TokenId> |