SessionToCookie

This document describes how to configure SessionToCookie.

The purpose of this cookie is to support integration scenarios where the target application picks up a cookie value and sends that to PhenixID verification endpoint (using PhenixID HTTP Authentication API).

Please note that this type of integration is not recommended nowadays (as there are more standard ways, like SAML or OpenIDConnect, to be used which doesn't rely on a shared-domain infrastructure).

The authenticator will pickup the authenticated session and set the session_id value in a cookie.

Requirements

- PhenixID version 2.8 or above installed

- PhenixID server and application must share the same domain (for example phenixid.example.org and application.example.org)

- Internal http authenticator set up (with the authentication method(s) that suits your needs)

Installation

The SessionToCookie authenticator is shipped with the platform but must be activated in the backend configuration.

  1. Shutdown the PhenixID service
  2. Open <phenixid_root_folder>/config/boot.json in a text editor
  3. Locate the auth-http object
  4. Add this to config
"v2_classes":{"SessionToCookie":"com.phenixidentity.authn.http.internal.sessioncopy.SessionToCookie"},

Example:

5. Save the file

6. Start the PhenixID service

Configuration Properties

Name Description Default value Mandatory
path Cookie path Yes
successURL The URL to redirect the browser to after successful authentication. Yes
name Name of cookie that will contain the session_id value Yes
domain Domain for cookie. Domain must be part of URL used to reach PhenixID server Yes
useSecure Use secure for cookie (true/false) Yes
includeQueryString Include query string (true/false) when redirecting to success URL false No
pipeID Id of pipe to use for additional validation No
errorLocation URL to redirect to on errors. No

Example configuration

Login to PhenixID configuration portal, go to advanced and click on the pencil next to "Authentication - HTTP".
Add the authenticator configuration:

{
    "alias" : "cookieAuth",
    "name" : "SessionToCookie",
    "configuration" : {
      "path" : "/",
      "name" : "authToken",
      "domain" : "example.org",
      "successURL" : "https://application.example.org/login",
      "useSecure" : "true",
      "errorLocation" : "https://application.example.org/error",
      "includeQueryString" : "true"
    },
    "id" : "a7311245-b205-4390-8b5d-1da96fcbf2a1"
  }

Change the different parameters according to the requirements in the environment.

When done click Stage changes and Commit changes.

Complete configuration example

This example shows a full configuration where a username-password authenticator precedes the SessionToCookie authenticator. 

{
    "name" : "PostUidAndPassword",
    "id" : "unpw",
    "alias" : "unpw",
    "displayName" : "Username Password",
    "configuration" : {
      "errorURL" : "/error/myerrorpage.html",
      "loginTemplate" : "login.template",
      "successURL" : "/secure/authenticate/cookieAuth",
      "pipeID" : "pipeDummy",
      "includeQueryString" : "true"
    }
  },
 {
    "alias" : "cookieAuth",
    "name" : "SessionToCookie",
    "configuration" : {
      "path" : "/",
      "name" : "authToken",
      "domain" : "example.org",
      "successURL" : "https://application.example.org/login",
      "useSecure" : "true",
      "errorLocation" : "https://application.example.org/error",
      "includeQueryString" : "true"
    },
    "id" : "a7311245-b205-4390-8b5d-1da96fcbf2a1"
  }

 

Complete end user flow example

1. User browse to https://application.example.org/login and selects login

2. Browser is redirected to https://phenixid.example.org/secure/authenticate/unpw

3. End user enters username and password

4. On successful authentication, browser is redirected to https://phenixid.example.org/secure/authenticate/cookieAuth

5. Cookie will be set (no end user interaction needed)

6. User is redirected to https://application.example.org/login