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.
See Certificates |
Workflow | Select the workflow that will handle the user authentication. |
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 ( This determines the page that is presented to the user to log into the TrustBuilder IDP.
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
andToken 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 |
(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 Contains a union of query parameters and POST parameters. For credentials, it also contains the parameters |
Test Input Type Example
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:
|
value | structure depends on the |
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
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
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 |