Develop HTTP API Authentication response output filter

Overview

The HTTP API authentication API module will always respond with a json structure on successful execution. The json structure contains key-value pairs based on the item properties populated in the underlying pipe:

  • Key = item property name
  • Value = item property value. A single-value property will result in a text (string) value. A multi-value property will result in a text array value.

In some use cases, for example when using OpenID Connect UserInfo, some of the keys (claims) must contain values which are not text nor text array. One example is the OIDC claim called email_verified which must contain a boolean value.

This is an example of default http api response output:

{
  "email_verified" : "true",
  "roles" : [ "role1", "role2" ],
  "email" : "reine@test.org"
}

In the above example, the email_verified claim contains a text value.

 

This article describes how to develop an output filter and install it on the server.

Setup development project

  • Create a new java project in your IDE
  • Copy these files from your PhenixID Authentication Services instance:
    • <server_root>/lib/logger*.jar
    • <server_root>/lib/vertx-core-*.jar
    • <server_root>/repo/com/phenixidentity/phenix-api-authenticate/<VERSION>/phenix-api-authenticate-<VERSION>-mod.zip
    • <server_root>/repo/com/phenixidentity/phenix-api-authenticate/<VERSION>/phenix-core-<VERSION>-mod.zip

(Change <server_root> and <VERSION> to match your environment)

  • Add the above files to your development project as compile-time libraries
  • Create a new class
  • Add the following code

    package com.phenixidentity.api.authenticate.handler.output.custom; import com.phenixidentity.api.authenticate.handler.output.OutPutHandler; import com.phenixidentity.common.log.Logger; import com.phenixidentity.core.protocol.Document; import org.vertx.java.core.json.JsonObject; public class MyResponseFilter implements OutPutHandler {    private static final Logger LOG = Logger.create(MyResponseFilter.class);    @Override    public void writeToOutPut(com.phenixidentity.core.http.BufferedHttpServerRequest httpRequest, com.phenixidentity.core.protocol.Response response) {        if (response.isSuccess()) {            httpRequest.response().setStatusCode(200);            httpRequest.response().headers().add("Content-Type", "application/json");            Document item = response.firstItem();            if (item != null) {                JsonObject responseoObj = new JsonObject(item.toString().replaceAll("\\\\n", ""));                responseoObj.removeField("id");                                //ADD_YOUR_CODE_HERE                  httpRequest.response().end(responseoObj.encodePrettily());            } else {                httpRequest.response().end("{}");            }        }    } }
  • Change the name of the class to suite your needs
  • Add your code to handle the output claim(s) types. This snippet example will pickout the email_verified claim and change the type to boolean:
if (responseoObj.getValue("email_verified") != null) {
                    String actValue = responseoObj.getValue("email_verified");
                    responseoObj.removeField("email_verified");
                    responseoObj.putBoolean("email_verified", Boolean.parseBoolean(actValue));
                    LOG.debug("Converted email_verified to boolean..");
                }
  • Save and compile the class

Install output filter

  • Copy the compiled class file
  • Add it to your PhenixID Authentication Services server. Place it in the api-module and the folder corresponding to your package. Example:
    com.phenixidentity~phenix-api-authenticate~4.3.0/com/phenixidentity/api/authenticate/handler/output/custom# ls -la -rw-r--r-- 1 root root 3155 apr  8 05:00 MyResponseFilter.class
  • Restart the PhenixID Authentication Services server

Usage

  • Login to Configuration Manager
  • Advanced->Modules
  • Locate the com.phenixidentity~phenix-api-authenticatei module.
  • Add the output filter to the tenant. Example:
{
		"module": "com.phenixidentity~phenix-api-authenticate",
		"enabled": "true",
		"config": {
			"tenant": [
				{
					"id": "t1",
					"allowedOperation": [
						"userinfo_t1"
					]
				},
				{
					"outPutHandler": "com.phenixidentity.api.authenticate.handler.output.custom.MyResponseFilter",
					"id": "mytenant",
					"allowedOperation": [
						"token_claim_pipe"
					]
				}
			]
		},
		"id": "authapi_module"
	},
  • Stage changes
  • Commit changes

Test

Call the api endpoint and verify the response output.

 

Example:

https://pas_server:port/api/authentication/token_claim_pipe?tenant=mytenant

 

Response:

{
  "roles" : [ "role1", "role2" ],
  "email" : "reine@test.org",
  "email_verified" : true
}