Identity Provider Types: Internal


There are two types of "Internal IDP":

The first one is the Identity Provider that is configured automatically when IDHub is installed. This is the IDHUB_IDP_UP.  This IDP will look up the subject in the user repository (database).  The settings of this IDP cannot be changed, with the exception of "Page Setting"

Other types of Internal IDP will delegate the Authentication to a workflow.


Field Description
Display Name User specified name of the Identity Provider
URL Not used, for informative use only.
Description User specified description of the Identity Provider
Type "Internal"
Subject Defines which attribute is used to identify the Subject
Workflow Select the workflow that will handle the user authentication.
This field will be ignored on the built-in IDP (IDHUB_IDP_UP)
Page Setting Only for the built-in IDP (IDHUB_IDP_UP). This determines the page that is presented to the user to log into the IDHub IDP.
  • Location: the URL (relative path) on which the webpage is available
  • Template: Select a template from the available templates.  The default template (cannot be changed) is at least available.

Note: Be sure the location or template is functional, or you will not be able to log back into IDHub.

This field is not used by other internal IDP types.

Workflow integration

The internal IDP needs a workflow. That workflow is called in two occasions:

  • In case of an authentication request 
  • When the user posts his credentials. 

Below is explained how you can make that workflow. 

The input of the workflow is a  SimpleValueRequest  which contains the following parameters: 

  • type: "authenticationRequest" or "userInputHandlingRequest"
  • idpCode
  • relayState
  • authenticationContext
  • spRequest
  • session
  • headers
  • cookies

In case of a userInputHandlingRequest the input also contains the query parameters.

In case of a backchannel request the parameters field contains the parameters "username" and "password".

The response must be a SimpleValueResponse. The expected fields are:

  • type: "assertion", "page" or "error"
  • value

The expected structure for the "value" field depends on the "type" field.

As you can see the internal idp workflow can give three type of responses. Here we will discuss them all and explain the corresponding expected structure for the "value" field.


You have the possibility to respond with an assertion. In this case the "value" field needs to contain the following fields:

  • subject
  • authenticationContext
  • attributes

The attributes field must be an object with as keys the attribute names and as values the corresponding attribute values in an array.


You have the possibility to respond with a page. This would typically be a login page or an error page. In this case the "value" field needs to contain the field:

  • status

The following fields are optional (but you will probably want to declare at least one of them because a status on its own won't be very useful):

  • headers
  • cookies
  • body

All of these fields, if declared, must be an object with string keys and string values.

If you create a login page, the credentials must be posted to /idhub/authenticate/internalidp. The parameter "idpCode" is also required. If you want the parameters "relayState" and "authenticationContext" to be present in the userInputHandlingRequest, you will also need to include them in this post.


You have the possibility to respond with an error code known by the system. The error handling functionality of the system will handle the error in the same way it handles the same kind of error encountered with another IDP type (e.g. SAML IDP, OAUTH IDP).

Was this article helpful?
2 out of 2 found this helpful
Have more questions? Submit a request



Please sign in to leave a comment.