Skip to main content
Skip table of contents

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"

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

Configure a custom Internal IDP

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 after the Authentication is complete. The workflows can be used, for instance, to provision users in a 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.

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

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.

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.

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

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

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.