There are 3 ways to provide authentication credentials to Polaris Application Services.
Accessing Polaris Application services requires the use of an access token and secret. An access token and secret may be issued by calling the staff authentication method.
POST /api/.../authentication/staffuser
The staff authentication method utilizes standard HTTP Basic Authentication via the HTTP Authorization header. When the user agent wants to send the server authentication credentials it may use the Authorization header.
The Authorization header is constructed as follows:
It is important to note that the Domain name must be included with the username. For example, if the user agent is a member of the MYLIB domain, has 'Aladdin' as the username and 'opensesame' as the password then the combined "username:password" would appear as:
The header with Base64 encoding is formed as follows:
The return object from the staff authentication method contains an an access token and access secret. This pair of strings will be used for all other Polaris Application Service calls. The authorization header will use the PAS scheme and does not need to be Base64 encoded. The site code, access token and secret are combined into a string "siteDomain:token:secret" and will appear as:
ASP.NET Forms Authentication may be used with the Polaris.ApplicationServices Web API. An ASP.NET WebForm may be used to create a login page.
This should validate the user and create a Forms Authentication cookie which contains a Forms Authentication ticket. The cookie should be
named "LeapWebApp". The ticket's
Once the browser receives the forms authentication cookie, all proceeding calls to services on the same domain will automatically contain the cookie in the underlying HTTP request. This includes JavaScript XHR calls.
When Polaris.ApplicationServices receives a web request, it will examine the cookies contained within the header. If it finds a cookie with the name "LeapWebApp", it will attempt to decrypt the cookie to extract the ticket. If a valid ticket has been provided, the service will assign the ticket.name as the calling principal on the thread. This will represent the PolarisUser.
In order for encryption and decryption of the Forms Authentication Ticket to work properly between separate IIS Web Applications, the underlying machine keys must be in synch. Web.config's <machinekey> element must be the same for the .NET website hosting the login page and the .NET Web API service.
How To: Configure MachineKey in ASP.NET 2.0
Easiest way to generate MachineKey
When configured, bearer tokens may be used with the Polaris.ApplicationServices Web API. OAuth must be enabled and configured to use OpenID Connect and PKCE (Proof Key Code Exchange).
The header will be similar to:
The bearer token must include the "upn" (user principal name) claim. This name should be in the form of an email address and must exist as a staff user in the Polaris database.
If a user is not authorized to perform a specific operation in Polaris, an HTTP 403 response code will be returned. Polaris allows for operator overrides. The override credentials will be passed in via the standard HTTP Proxy-Authorization header or the custom Polaris-Override-Authorization custom.
The credentials are combined in the following format and then Base 64 encoded.
Example:
The custom header supports multiple permission overrides for a single API call.
They may also be added as a single header value by providing the overrides in a comma delimited list:
Important! The Authorization header with the access token and secret are still required.
When OAuth 2 support is enabled, refer to System Administration Permissions for permission overrides.