Authentication

Description: Authentication Service

Manages user authentication and login.

**Method:** _POST_

URL: http://pmapi/auth

Starts the authentication process, displaying either the online or offline authentication page.

Output:
Status Codes:

200 -- Authentication completed. The user service will be populated with the user's information if authentication was successful.
400 -- Bad Request: Authentication is already in progress
403 -- Forbidden: Authentication failed, or could not be attempted.
500 -- Internal Server Error: Basic settings not configured.

Once begun, all other service requests will be rejected with 403-Forbidden status code until the authentication process completes.

If device is online, initializes the login process and shows the login page. This page is configured in User Settings under the "login_url" key as the base URL, and the constant "/pg/session/create" path. This page is expected to perform an authorization grant oAuth authentication.

If device is offline, and offline login was previously configured, displays the offline login page.

The offline login web app is configured in the Boot document, with the element "offlineName". This web app will be extracted, and the filename configured in webApp document "main" element will be used to start the login process. This web page will be called with two query string parameters:

t = token
u = username

Where:

token is a token that must be used to call the authentication service to complete authentication (see below)
username is the username of the offline user.

Method: POST

URL: http://pmapi/auth/setup

Starts the offline authentication setup process, displaying the offline authentication setup page.

Output:
Status Codes:

200 -- Setup completed.
400 -- Bad Request: Authentication is already in progress, user is not already authenticated online, boot document does not contain offline package configuration, offline package setup element not configured, or keychain is already configured for this user.

The filename configured in offline webApp document "setup" element will be used to start the setup process. This web page will be called with two query string parameters:

t = token
u = username

Where:

token is a token that must be used to call the authentication service to complete the setup process
username is the username of the offline user.

Method: POST

URL: http://pmapi/auth/update

Starts the offline authentication management process, displaying the offline management setup page where a user should be able to change their password.

Output:
Status Codes:

200 -- Update completed.
400 -- Bad Request: Authentication is already in progress, user is not already authenticated online, boot document does not contain offline package configuration, offline package setup element not configured, or keychain is already configured for this user.

The filename configured in offline web app document "manage" element will be displayed. This web page will be called with two query string parameters:

t = token
u = username

Where:

token is a token that must be used to call the authentication service to complete the setup process
username is the username of the offline user.

It is expected this web page will in turn call the http://pmapi/auth/{token}/update to complete the process of updating the users password.

Method: PUT

URL: http://pmapi/auth/{token}/authenticate

Authenticates a user's offline password.

Input: Query string elements:

p = password

Where token is the token passed to the authentication page when started. See http://pmapi/auth above. password is the user's password to authenticate.

Output:
Status Codes:

200 -- Password is valid. The authentication page will now be closed, and the http://pmapi/auth request will complete.
400 -- Bad Request: Authentication is not already in progress, or query string elements are not as expected.
403 -- Forbidden: Provided password did not validate.
404 -- Not Found: Token is invalid, or the system is not expecting the authenticate request at this time.

Method: PUT

URL: http://pmapi/auth/{token}/setup

Input: Query string elements:

p = password

Where token is the token passed to the authentication page when started. See http://pmapi/auth/setup above. password is the user's password to configure.

Output:
Status Codes:

200 -- The password was saved. The authentication setup page will now be closed, and the http://pmapi/auth/setup request will complete.
400 -- Bad Request: Authentication setup is not already in progress, or query string elements are not as expected, or user is no longer authenticated online.
404 -- Not Found: Token is invalid, or the system is not expecting the setup request at this time.

Method: PUT

URL: http://pmapi/auth/{token}/update

Input: Query string elements:

o = old password
p = new password

Where token is the token passed to the authentication page when started. See http://pmapi/auth/update above. old password is the users original password. new password is the new offline password to store for the user.

Output:
Status Codes:

200 -- The password was saved. The authentication setup page will now be closed, and the http://pmapi/auth/setup request will complete.
400 -- Bad Request: Authentication setup is not already in progress, or query string elements are not as expected, or user is no longer authenticated online.
403 -- Forbidden: The old password does not match
404 -- Not Found: Token is invalid, or the s ystem is not expecting the setup request at this time.

Method: DELETE

URL: http://pmapi/auth

Cancels a current in-process login or setup, resetting the authentication service to allow a new POST request.

Output:
Status Codes: