Internal IDP

Built-in Internal IDP

The first one is the Identity Provider that is configured automatically when signing up to TrustBuilder. Its code name is 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"

Custom Internal IDP

Custom Internal IDP handles the Authentication through a workflow.

From the admin portal, go to Identity Providers tab > Custom Internal IDP.

Field	Description
Display Name	The display name of the Identity Provider
URL	Not used, for informative use only.
Description	User specified description of the Identity Provider
Type	"Internal"
Provisioning Workflow	Select a workflow that will be executed each time an Authentication is successfully finished. The workflow can be used, for instance, to update last login on user in an external user database.
Subject	Primary attribute that is used to identify the Subject
Manage Certificates	You can manage certificates from the Certificates configuration page. You can also add or import certificates from the Identity provider configuration. Context → Defines what the certificate is used for. Key - Signing: Used to sign messages to the IDP Key - Encryption: Used to decrypt the messages (assertions) sent from the IDP Key - TLS: Used to initiate a secure connection (TLS) to the IDP Trust - Signing: Used to verify the signature of messages sent by the IDP Trust - TLS: Used to accept a secure connection (TLS) from the IDP Certificate Alias → The alias of the certificate to use for this context. Used From → Defines from when this certificate may be used. In some cases these periods may overlap for the same context (eg. during a certificate renewal), but in other cases they may never overlap (Key - Signing, Key - TLS). Used Until → Defines until when this certificate may be used. See Certificates
Workflow	Select the workflow that will handle the user authentication. This field will be ignored on the built-in IDP (`IDHUB_IDP_UP`)
Token Validation Workflow	Select the workflow that will handle the token validation. This workflow has the full power of token validation and setting claims during a Token Exchange. For this to be used, an OAuth SP must have token exchange enabled and this IDP has to enabled there.
Page Setting	Only for the built-in IDP (`IDHUB_IDP_UP`). This field is not used by other internal IDP types. This determines the page that is presented to the user to log into the TrustBuilder 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. Make sure the location or template is functional. Otherwise, you may not be able to log back into TrustBuilder.

Workflow

Description

The internal IDP needs a Workflow (defined in the Workflow field).

Note that there are other fields Provisioning Workflow and Token Validation Workflow - those have thier specific uses.

That Workflow is called when user interacts with the Internal IDP - the trigger can be:

Authentication request (i.e. after Internal IDP was selected to execute the authentication).
Posting credentials (i.e. HTTP request with credentials and matching open authentication in the current session is received).

Below is explained how you can make that workflow.

Input

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

Field	Description
type	`authenticationRequest` or `userInputHandlingRequest` (depending on the authentication context)
idpCode	code uniquely identifying an IDP (workflow may handle multiple IDPs and distinguish the behavior)
relayState	state identifier
authenticationContext	context of Authentication
sp_request	context from SP Request
session	context from Session
request_headers	from incoming HTTP request
request_cookies	from incoming HTTP request
parameters	only for `userInputHandlingRequest` Contains a union of query parameters and POST parameters. For credentials, it also contains the parameters `username` and `password`.

Test Input Type Example

JS

function is_authreq(workItem) {
	if (workItem.input.type === "authenticationRequest") {
		tb.log("Request is authenticationRequest", 'custom_internal_idp', 'INFO');
		return "yes";
	} else if (workItem.input.type === "userInputHandlingRequest")
		tb.log("Request is userInputHandlingRequest", 'custom_internal_idp', 'INFO');
		return "no";
	} else {
		throw new Error("unexpected_request_type");
	}
}

Output

The response must be a SimpleResponse type. The expected fields are:

Field

Description

type

one of:

assertion
page
error

value

structure depends on the type field - see below

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.

Assertion

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.

Assertion Output Example

JS

workItem.output = tb.simpleResponse({
	type: 'assertion',
	value: {
		subject: workItem.username,
		authenticationContext: "",
		attributes: {
		}
	}
});

Page

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.

Page Output Example

JS

var headers = { "Content-Type": "text/html; charset=utf-8" };

workItem.response = {
	"type": "page",
	"value": {
		"status": 200,
		"body": filledtemplate,
		"headers": headers
	}
};

workItem.output = tb.simpleResponse(workItem.response, 0, 0);

Error

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).

Error List

Internal error code	SAML error code	Description
ACCESS_DENIED	ACCESS_DENIED	Access denied
ACCOUNT_BLOCKED	ACCOUNT_BLOCKED	Account is blocked
AUTHN_FAILED	AUTHN_FAILED	The responding provider was unable to successfully authenticate the principal.
BAD_REQUEST	BAD_REQUEST	Bad request
CERTIFICATE_NOT_FOUND	CERTIFICATE_NOT_FOUND	A required certificate was not found
INSTALL_NOT_OK	INSTALL_NOK	Installation is not completed, complete installation and retry
INTERNAL_SERVER_ERROR	MessageKeys.INTERNAL_SERVER_ERROR	Internal server error
INVALID_ATTR_NAME_OR_VALUE	urn:oasis:names:tc:SAML:2.0:status:InvalidAttrNameOrValue	Unexpected or invalid content was encountered within a <saml:Attribute> or <saml:AttributeValue> element.
INVALID_NAME_ID_POLICY	urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy	The responding provider cannot or will not support the requested name identifier policy.
INVALID_PARAMETERS	INVALID_PARAMETERS	There are some parameters with invalid values in the request.
MESSAGE_VALIDATION_FAILED	MESSAGE_VALIDATION_FAILED	The parsing of a third party message has failed.
MISSING_PARAMETERS	MISSING_PARAMETERS	There are some parameters missing in the request.
NO_AUTHN_CONTEXT	NO_AUTHN_CONTEXT	The specified authentication context requirements cannot be met by the responder.
NO_AVAILABLE_IDP	NO_IDPS	Used by an intermediary to indicate that none of the supported identity provider <Loc> elements in an <IDPList> can be resolved or that none of the supported identity providers are available.
NO_PASSIVE	urn:oasis:names:tc:SAML:2.0:status:NoPassive	Indicates that the responding provider cannot authenticate the principal passively, as has been requested.
NO_PROXY_SP	NO_PROXY_SP	No Gateway Service Provider found
NO_SUBJECT	SP_SUBJECT_NOT_FOUND	here is no value present for the attribute used as subject for the Service Provider you are trying to access
NO_SUPPORTED_IDP	urn:oasis:names:tc:SAML:2.0:status:NoSupportedIDP	Used by an intermediary to indicate that none of the identity providers in an <IDPList> are supported by the intermediary.
PROXY_COUNT_EXCEEDED	urn:oasis:names:tc:SAML:2.0:status:ProxyCountExceeded	Indicates that a responding provider cannot authenticate the principal directly and is not permitted to proxy the request further.
REQUEST_DENIED	REQUEST_DENIED	The SAML responder or SAML authority is able to process the request but has chosen not to respond. This status code MAY be used when there is concern about the security context of the request message or the sequence of request messages received from a particular requester.
REQUEST_UNSUPPORTED	urn:oasis:names:tc:SAML:2.0:status:RequestUnsupported	The SAML responder or SAML authority does not support the request.
REQUEST_VERSION_DEPRECATED	urn:oasis:names:tc:SAML:2.0:status:RequestVersionDeprecated	The SAML responder cannot process any requests with the protocol version specified in the request.
REQUEST_VERSION_TOO_HIGH	urn:oasis:names:tc:SAML:2.0:status:RequestVersionTooHigh	The SAML responder cannot process the request because the protocol version specified in the request message is a major upgrade from the highest protocol version supported by the responder.
REQUEST_VERSION_TOO_LOW	urn:oasis:names:tc:SAML:2.0:status:RequestVersionTooLow	The SAML responder cannot process the request because the protocol version specified in the request message is too low.
RESOURCE_NOT_RECOGNIZED	urn:oasis:names:tc:SAML:2.0:status:ResourceNotRecognized	The resource value provided in the request message is invalid or unrecognized.
TOO_MANY_RESPONSES	urn:oasis:names:tc:SAML:2.0:status:TooManyResponses	The response message would contain more elements than the SAML responder is able to return.
UNKNOWN_ATTR_PROFILE	urn:oasis:names:tc:SAML:2.0:status:UnknownAttrProfile	An entity that has no knowledge of a particular attribute profile has been presented with an attribute drawn from that profile.
UNKNOWN_PRINCIPAL	urn:oasis:names:tc:SAML:2.0:status:UnknownPrincipal	The responding provider does not recognize the principal specified or implied by the request.
UNKNOWN_ARTIFACT_ISSUER	UNKNOWN_ARTIFACT_ISSUER	The issuer of a SAML artifact response could not be identified.
UNKNOWN_SP	UNKNOWN_SP	The Service Provider is not known to us.
UNSUPPORTED_BINDING	urn:oasis:names:tc:SAML:2.0:status:UnsupportedBinding	The SAML responder cannot properly fulfill the request using the protocol binding specified in the request.
WRONG_AUTHENTICATION_METHOD	WRONG_AUTHENTICATION_METHOD	There was a problem finding the authentication method
WRONG_USER	IDP_WRONG_USER	Mismatch between logged on user and incoming user