====== Authentication ======

===== Custom Authorization for (REST) services =====

For setting up a custom authentication service for API's (on service package) the following is needed:

^Rule type ^Description ^
| Authentication service rule (type custom)| Umbrella for the authentication |
| Timeout activity | Activity that optionally contains logic that will be run on timeout | 
| Authentication Activity | Activity with purpose of authenticating the requestor.  |

===== Configuring the Authentication service =====

    - On Serivce tab: Indicate a timeout activity (implementation can be empty) and Indicate a Authentication Activity (needs implementation, described later.)
    - On Custom tab: (choose Use externally stored credentials, must match the "Use external authentication" setting on operator page which is the result of the authentication activity)    

    * [[https://docs.pega.com/bundle/platform-23/page/platform/security/configure-login-using-custom-authentication-service.html | (docs.pega.com) Configure-login-using-custom-authentication-service]]

===== Implementing the Authentciation activity =====

The purpose of the activity is to do the actual authentication. Successfull authentication is indicated by a couple of parameters:
  - pyOperPage must be a data-admin-operator-id (the identified operator) clipboard page (as java object) 
  - pyUserIdentifier -> operator identifier. 

The following can be used in a java step (where myStepPage is the operator page):
 
<code>
tools.putParamValue("pyOperPage", myStepPage);
tools.putParamValue("pyUserIdentifier", myStepPage.getString("pyUserIdentifier"));
</code>
 

Likely a token of some sort is expected in the http headers send by client/user to authenticate. 
In the authentication context the http headers can be read via following example: 

<code>
ClipboardPage pxRequestorPage = tools.findPage("pxRequestor");

javax.servlet.http.HttpServletRequest request = (javax.servlet.http.HttpServletRequest) pxRequestorPage.getObject("pxHTTPServletRequest");
authToken = request.getHeader("Authorization");
</code>

In the example the Authorization header is fetch into a local variable authToken. 


To summarize the flow of the activity:
  - Get credentials from header
  - Verify if credentials are valid and identify the client/consumer/user
  - Iompose Operator Page (read from db or use template opertor)
  - Indicate success by setting the expected pyOperPage and pyUserIdentifier. \\ (If either of the parameters are missing the result will be a 401 unauthorized response.)

  * [[https://docs.pega.com/bundle/platform/page/platform/security/configure-custom-or-kerberos-login-authentication.html| (Docs.Pega.Com) Configure custom loginauthentication]]
  * [[https://support.pega.com/question/how-authenticate-user-custom-authentication-activityll | (Support.Pega.Com) question on how to configure a authentication activity.]]

{{tag>[pega custom_authentciation API]}}