How to add Token Introspection to PhenixID Authentication Services OAuth2 Authorization Server

Prerequisites

- PAS 3.x (next version) or higher installed. (Please contact PhenixID support if you need immidiate patch for version 3.2.)

- OpenID Connect Provider configured using Scenarios->OIDC

- The PhenixID OIDC token endpoint must have returned an OAuth2 access_token, which value is bound to the session as an alias.

Install output filter

By default, the PhenixID Authentication Services API endpoints only return string values. For token introspection, a boolean value for the Active claims must be returned. This require an output filter to be added to the installation.

1. Download file from https://files.phenixid.se/s/WqBZatKybztbEjG

2. Shutdown PhenixID Authentication Services

3. Place the file in <phenixid_root>/mods/com.phenixidentity~phenix-api-authenticate~<VERSION>/com/phenixidentity/api/authenticate/handler/output/custom/.
Change <VERSION> to your current version.
Create the custom folder.

4. Start PhenixID Authentication Services

5. Login to configuration manager

6. Click the Advanced tab

7. Open Modules (click on the pen)

8. Locate the api module (com.phenixidentity~phenix-api-authenticate)

9. Locate the tenant for the OpenID Connect Provider configured

10. Add the output handler. 

{
		"module": "com.phenixidentity~phenix-api-authenticate",
		"enabled": "true",
		"config": {
			"tenant": [
				{
					"id": "t1",
					"displayName": "Tenant1",
               "outPutHandler": "com.phenixidentity.api.authenticate.handler.output.custom.OIDCIntrospectionOutPutHandler",
					"allowedOperation": [
						"introspect"
					]
}
			]
		},
		"id": "authapi_module"
	}

11. Click Stage Changes and Commit Changes

Add token inspection as an allowed operation

- Login to configuration manager

- Click the Advanced tab

- Open Modules (click on the pen)

- Locate the api module (com.phenixidentity~phenix-api-authenticate)

- Locate the tenant for the OpenID Connect Provider configured

- Add inspect as an allowed operation.

Example:

{
		"module": "com.phenixidentity~phenix-api-authenticate",
		"enabled": "true",
		"config": {
			"tenant": [
				{
					"id": "t1",
					"displayName": "Tenant1",
               "outPutHandler": "com.phenixidentity.api.authenticate.handler.output.custom.OIDCIntrospectionOutPutHandler",
					"allowedOperation": [
						"introspect"
					]
}
			]
		},
		"id": "authapi_module"
	}

NB! If you have multiple logical OpenID Connect Providers (=tenants) and you would like to configure different token introspect logic for different providers, then rename introspect to something unique for the tenant, for example introspect_t1. Also make sure to set the pipe id to the same value (see later step).

- Click Stage Changes and Commit Changes

 

Add pipe to perform token introspection

- Click the Advanced tab

- Open Pipes (click on the pen)

- Add this pipe.

{
		"id": "introspect",
		"valves": [
			{
                "name": "RPBasicAuthentictionValve",
                "enabled": "true",
                "config": {}
            },
            {
				"name": "SessionLoadValve",
				"config": {
					"id": "{{request.token}}",
					"proceed_on_error": "true"
				}
			},
			{
				"name": "ItemCreateValve",
				"config": {
					"dest_id": "dataholder"
				}
			},
			{
				"name": "PropertyAddValve",
				"config": {
					"name": "active",
					"value": "true",
					"exec_if_expr": "session!=null"
				}
			},
			{
				"name": "PropertyAddValve",
				"config": {
					"name": "username",
					"value": "{{session.user_id}}",
					"exec_if_expr": "session!=null"
				}
			},
			{
				"name": "PropertyAddValve",
				"config": {
					"name": "active",
					"value": "false",
					"exec_if_expr": "session===null"
				}
			}
		],
		"created": "2020-03-20T12:46:06.466Z"
	}

- If the introspect operation was named something else, set the same value as the pipe id.

- If you would like the introspect endpoint to respond with additional claims, please add it by adding more PropertyAddValve object with name=<claim_name> and value=<{{session.<session_property_name>}}. The session property must exist (set in on the token endpoint execution flow).
Make sure to follow the standard for introspection return claims (https://tools.ietf.org/html/rfc7662#section-2.2)

- Click Stage Changes and Commit Changes

Add introspection endpoint and authentication method to Discovery data

- Click the Advanced tab

- Click OIDC_OP

- Locate the OP configuration for the OP provider (tenant)

- Add the token introspection endpoint by adding the config parameter introspection_endpoint with a value pointing to the pipe previously added. Also, add the tenant ID to the URL. 

- Add token authentication method (basic auth) by adding the parameter introspection_endpoint_auth_methods_supported.

"introspection_endpoint" : "https://<PAS_SERVER>/api/authentication/introspect?tenant=<TENANT_ID>",
"introspection_endpoint_auth_methods_supported" : [
                "client_secret_basic"
            ]


FULL EXAMPLE:
{
        "id": "t1",
        "tenant": "t1",
        "guide_ref": "guides.authentication.oidc.uidpwdsms",
        "config": {
            "authorization_endpoint": "https://demo.phenixid.net/oidc/authenticate/oidc_otp",
            "userinfo_endpoint": "https://demo.phenixid.net/api/authentication/userinfo?tenant=t1",
            "revocation_endpoint": "https://demo.phenixid.net/api/authentication/revoke?tenant=t1",
            "introspection_endpoint": "https://demo.phenixid.net/api/authentication/introspect?tenant=t1",
            "issuer": "https://demo.phenixid.net/t1",
            "token_endpoint": "https://demo.phenixid.net/api/authentication/2a4b03b4-7073-4728-9149-6bb7409187e7?tenant=t1",
            "jwks_uri": "https://demo.phenixid.net/oidc_otp/.well-known/openid-configuration/jwks",
            "response_types_supported": [
                "code"
            ],
            "grant_types_supported": [
                "authorization_code"
            ],
            "subject_types_supported": [
                "public"
            ],
            "id_token_signing_alg_values_supported": [
                "RS256"
            ],
            "scopes_supported": [
                "openid"
            ],
            "token_endpoint_auth_methods_supported": [
                "client_secret_basic"
            ],
            "introspection_endpoint_auth_methods_supported" : [
                "client_secret_basic"
            ]
            "claims_supported": [
                "iss",
                "ver",
                "sub",
                "given_name",
                "family_name"
            ],
            "end_session_endpoint": "https://demo.phenixid.net/oidc/authenticate/logout/",
            "request_parameter_supported": "true",
            "signStore": "956bee24-98f0-41a5-9e27-76f8c89d1e1d"
        },
        "created": "2019-10-21T07:59:30.621Z"
    }


- If the introspect operation was named something else, set the same value as the last part of the introspection_endpoint uri.

Example:

"introspection_endpoint": "https://demo.phenixid.net/api/authentication/introspection_t1?tenant=t1",

Test

Use a HTTP rest client for testing and debugging. Follow the document OAuth2 Token introspection - integration guide for developers to structure the HTTP requests properly.