SAMLIdPServer Component

Properties   Methods   Events   Config Settings   Errors  

The SAMLIdPServer component represents a SAML identity provider.

Syntax

TsbxSAMLIdPServer

Remarks

The identity provider in the SAML (Security Assertion Markup Language) exchange flow represents the server that issues authentication assertions for single sign-on (SSO).

Requests received by the IdP server from known service providers (SP) are processed automatically, in accordance with known SP metadata and IdP options. If the request is correct, the client is redirected to the IdP for authentication. The authentication algorithm depends on the IdP options and may be reduced to a simple IP check, X.509 certificate authentication, or login credentials check.

Property List

---

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

Active Property (SAMLIdPServer Component)

Tells whether the server is active and ready to process requests.

Syntax

property Active: Boolean read get_Active;

Default Value

false

Remarks

This property indicates whether the IdP server is in an active state.

This property is read-only and not available at design time.

AllowIDPSSO Property (SAMLIdPServer Component)

Specifies if IdP-initiated Single Sign-On (SSO) is allowed.

Syntax

property AllowIDPSSO: Boolean read get_AllowIDPSSO write set_AllowIDPSSO;

Default Value

false

Remarks

Set this property to true to allow IdP-initiated Single Sign-Ons. Use AddIdPSSOLink method to add sign-on URLs.

ArtifactResolutionService Property (SAMLIdPServer Component)

The location of the artifact resolution service.

Syntax

property ArtifactResolutionService: String read get_ArtifactResolutionService write set_ArtifactResolutionService;

Default Value

'/idp/ArtifactResolutionService'

Remarks

Use this property to specify the location of the artifact resolution service of this Identity Provider (IdP).

AttributeQueryService Property (SAMLIdPServer Component)

The location of the AttributeQuery service.

Syntax

property AttributeQueryService: String read get_AttributeQueryService write set_AttributeQueryService;

Default Value

'/idp/AttributeQueryService'

Remarks

Use this property to specify the relative URL of the AttributeQuery service provided by this Identity Provider (IdP).

AuthFormTemplate Property (SAMLIdPServer Component)

Defines the default authentication template (login page).

Syntax

property AuthFormTemplate: String read get_AuthFormTemplate write set_AuthFormTemplate;

Default Value

''

Remarks

This property contains the HTML code of the authentication form. You can use it to control the appearance of the login page.

ClientAuth Property (SAMLIdPServer Component)

Enables or disables certificate-based client authentication.

Syntax

property ClientAuth: TsbxClientAuthTypes read get_ClientAuth write set_ClientAuth;

TsbxClientAuthTypes = (
  ccatNoAuth,
  ccatRequestCert,
  ccatRequireCert
);

Default Value

ccatNoAuth

Remarks

Set this property to true to tune up the client authentication type: ccatNoAuth = 0; ccatRequestCert = 1; ccatRequireCert = 2;

EncryptAssertions Property (SAMLIdPServer Component)

Specifies whether to encrypt assertions included into the IdP response.

Syntax

property EncryptAssertions: Boolean read get_EncryptAssertions write set_EncryptAssertions;

Default Value

false

Remarks

Set this property to True to force the component to encrypt the assertions included into the server's response.

EncryptionCertificate Property (SAMLIdPServer Component)

The certificate used to encrypt the assertions.

Syntax

property EncryptionCertificate: TsbxCertificate read get_EncryptionCertificate write set_EncryptionCertificate;

Remarks

Use this property to provide the certificate to be used for encrypting the assertions included into the IdP responses.

The component encrypts assertions automatically if EncryptAssertions is True.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

ErrorOrigin Property (SAMLIdPServer Component)

Indicates the endpoint where the error originates from.

Syntax

property ErrorOrigin: TsbxErrorOrigins read get_ErrorOrigin write set_ErrorOrigin;

TsbxErrorOrigins = (
  eoLocal,
  eoRemote
);

Default Value

eoLocal

Remarks

Use this property to establish whether the reported error originates from a local or remote endpoint.

This property is not available at design time.

ErrorSeverity Property (SAMLIdPServer Component)

The severity of the error that happened.

Syntax

property ErrorSeverity: TsbxErrorSeverities read get_ErrorSeverity write set_ErrorSeverity;

TsbxErrorSeverities = (
  esInfo,
  esWarning,
  esFatal
);

Default Value

esWarning

Remarks

Use this property to establish whether the error is fatal.

This property is not available at design time.

ExternalCrypto Property (SAMLIdPServer Component)

Provides access to external signing and DC parameters.

Syntax

property ExternalCrypto: TsbxExternalCrypto read get_ExternalCrypto;

Remarks

Use this property to tune-up remote cryptography settings. SecureBlackbox supports two independent types of external cryptography: synchronous (based on the ExternalSign event) and asynchronous (based on the DC protocol and the DCAuth signing component).

This property is read-only.

Please refer to the ExternalCrypto type for a complete list of fields.

FIPSMode Property (SAMLIdPServer Component)

Reserved.

Syntax

property FIPSMode: Boolean read get_FIPSMode write set_FIPSMode;

Default Value

false

Remarks

This property is reserved for future use.

Host Property (SAMLIdPServer Component)

Specifies the host address of the IdP server.

Syntax

property Host: String read get_Host write set_Host;

Default Value

''

Remarks

Use this property to specify the IP address on which to listen to incoming connections. To specify the listening port number, use Port.

IDPSSOPage Property (SAMLIdPServer Component)

Specifies the relative URL of the IdP-initiated SSO page.

Syntax

property IDPSSOPage: String read get_IDPSSOPage write set_IDPSSOPage;

Default Value

'/idpsso'

Remarks

Use this property to specify the address of the Single Sign-On (SSO) page initiated by this Identity Provider (IdP).

IDPSSOPageContent Property (SAMLIdPServer Component)

The content of the IdP-initiated SSO page.

Syntax

property IDPSSOPageContent: String read get_IDPSSOPageContent write set_IDPSSOPageContent;

Default Value

''

Remarks

Use this property to specify the content of the Single Sign-On (SSO) page initiated by this Identity Provider (IdP).

LoginAttemptsLimit Property (SAMLIdPServer Component)

The maximum number of login attempts.

Syntax

property LoginAttemptsLimit: Integer read get_LoginAttemptsLimit write set_LoginAttemptsLimit;

Default Value

3

Remarks

Use this property to set the maximum number of login attempts.

MetadataURL Property (SAMLIdPServer Component)

The IdP's metadata location.

Syntax

property MetadataURL: String read get_MetadataURL write set_MetadataURL;

Default Value

'/idp/metadata'

Remarks

This property specifies the metadata URL of this Identity Provider (IdP).

MetaSigningCertificate Property (SAMLIdPServer Component)

Specifies the metadata signing certificate.

Syntax

property MetaSigningCertificate: TsbxCertificate read get_MetaSigningCertificate write set_MetaSigningCertificate;

Remarks

Use this property to specify the certificate to be used to sign the IdP's metadata.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

OfflineMode Property (SAMLIdPServer Component)

Enables the Offline mode.

Syntax

property OfflineMode: Boolean read get_OfflineMode write set_OfflineMode;

Default Value

false

Remarks

In the Offline mode the server does not open the listening port. Instead, it expects all incoming requests to be provided via the ProcessGenericRequest calls.

The Offline mode is a handy mechanism for attaching the server to external web engines, such as IIS or Tomcat. It lets you leave the HTTP matters to the engine, and only be responsible for handling the actual SAML requests.

Port Property (SAMLIdPServer Component)

The listening port number.

Syntax

property Port: Integer read get_Port write set_Port;

Default Value

80

Remarks

Use this property to specify the port number on which the IdP server should listen for incoming connections. To specify server's IP address use Host.

PreferredSingleLogoutResponseBinding Property (SAMLIdPServer Component)

Specifies the preferred single logout response binding.

Syntax

property PreferredSingleLogoutResponseBinding: TsbxSAMLBindingTypes read get_PreferredSingleLogoutResponseBinding write set_PreferredSingleLogoutResponseBinding;

TsbxSAMLBindingTypes = (
  csbtNone,
  csbtSOAP,
  csbtPAOS,
  csbtRedirect,
  csbtPOST,
  csbtArtifact
);

Default Value

csbtRedirect

Remarks

This value is used by the Identity Provider (IdP) when the default binding is not specified in Service Provider's (SP) metadata file.

The binding is the mechanism of message exchange used by SAML requestors and responders.

PreferredSingleSignOnResponseBinding Property (SAMLIdPServer Component)

Specifies preferred SSO response binding.

Syntax

property PreferredSingleSignOnResponseBinding: TsbxSAMLBindingTypes read get_PreferredSingleSignOnResponseBinding write set_PreferredSingleSignOnResponseBinding;

TsbxSAMLBindingTypes = (
  csbtNone,
  csbtSOAP,
  csbtPAOS,
  csbtRedirect,
  csbtPOST,
  csbtArtifact
);

Default Value

csbtPOST

Remarks

This value is used by the Identity Provider (IdP) when the default binding is not specified in Service Provider's (SP) metadata file.

The binding is the mechanism of message exchange used by SAML requestors and responders.

ServerCertificates Property (SAMLIdPServer Component)

The server's TLS certificates.

Syntax

property ServerCertificates: TsbxCertificateList read get_ServerCertificates write set_ServerCertificates;

Remarks

Use this property to provide a list of TLS certificates for the server endpoint.

A TLS endpoint needs a certificate to be able to accept TLS connections. At least one of the certificates in the collection - the endpoint certificate - must have a private key associated with it.

The collection may include more than one endpoint certificate, and more than one chain. A typical usage scenario is to include two chains (ECDSA and RSA), to cater for clients with different cipher suite preferences.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

SigCanonicalizationMethod Property (SAMLIdPServer Component)

The canonicalization method to use in the signature.

Syntax

property SigCanonicalizationMethod: String read get_SigCanonicalizationMethod write set_SigCanonicalizationMethod;

Default Value

''

Remarks

The URI of the canonicalization method to use in the signature (e.g. http://www.w3.org/TR/xml-exc-c14n/)

SigDigestMethod Property (SAMLIdPServer Component)

The digest method to use.

Syntax

property SigDigestMethod: String read get_SigDigestMethod write set_SigDigestMethod;

Default Value

''

Remarks

The URI of the digest method to use for signing, as defined in XMLDSIG or XMLENC: http://www.w3.org/2000/09/xmldsig#sha256.

SigMethod Property (SAMLIdPServer Component)

The signature method to use.

Syntax

property SigMethod: String read get_SigMethod write set_SigMethod;

Default Value

''

Remarks

The URI specifying the signature method to use for signing, for example http://www.w3.org/2001/04/xmldsig-more#rsa-sha256.

SignAssertions Property (SAMLIdPServer Component)

Specifies whether the assertions included in IdP responses should be signed.

Syntax

property SignAssertions: Boolean read get_SignAssertions write set_SignAssertions;

Default Value

false

Remarks

Set this property to True to automatically sign the assertions included into the Identity Provider (IdP) responses.

SigningCertificate Property (SAMLIdPServer Component)

The certificate to be used by the IdP's for signing.

Syntax

property SigningCertificate: TsbxCertificate read get_SigningCertificate write set_SigningCertificate;

Remarks

Use this property to specify the certificate that shall be used for signing the assertions. Note that this certificate should have a private key associated with it. Use SigningChain to supply the rest of the certificate chain for inclusion into the signature.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

SigningChain Property (SAMLIdPServer Component)

The signing certificate chain.

Syntax

property SigningChain: TsbxCertificateList read get_SigningChain write set_SigningChain;

Remarks

Use this property to provide the chain for the signing certificate. Use the SigningCertificate property, if it is available, to provide the signing certificate itself.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

SignMetadata Property (SAMLIdPServer Component)

Specifies whether the IdP's metadata should be signed.

Syntax

property SignMetadata: Boolean read get_SignMetadata write set_SignMetadata;

Default Value

false

Remarks

Set this property to True to sign the Identity Provider's (IdP) metadata before saving it. Do not forget to assign the signing certificate to the MetaSigningCertificate property.

SignResponse Property (SAMLIdPServer Component)

Specifies whether the IdP responses should be signed.

Syntax

property SignResponse: Boolean read get_SignResponse write set_SignResponse;

Default Value

false

Remarks

Set this property to True to automatically sign the responses sent by this IdP server.

SingleLogoutService Property (SAMLIdPServer Component)

The URL of the single logout service.

Syntax

property SingleLogoutService: String read get_SingleLogoutService write set_SingleLogoutService;

Default Value

'/idp/SingleLogoutService'

Remarks

This property specifies the relative URL of the single logout service.

SingleLogoutServiceBindings Property (SAMLIdPServer Component)

Defines single logout service bindings.

Syntax

property SingleLogoutServiceBindings: String read get_SingleLogoutServiceBindings write set_SingleLogoutServiceBindings;

Default Value

'+Artifact,+POST,+Redirect'

Remarks

Use this property to specify the single logout service bindings.

The binding is the mechanism of message exchange used by SAML requestors and responders.

SingleSignOnService Property (SAMLIdPServer Component)

The URL of the single logout service.

Syntax

property SingleSignOnService: String read get_SingleSignOnService write set_SingleSignOnService;

Default Value

'/idp/SingleSignOnService'

Remarks

This property specifies the relative URL of the single logout (SSO) service.

SingleSignOnServiceBindings Property (SAMLIdPServer Component)

Defines single sign-on service bindings.

Syntax

property SingleSignOnServiceBindings: String read get_SingleSignOnServiceBindings write set_SingleSignOnServiceBindings;

Default Value

'+Artifact,+POST,+Redirect'

Remarks

Use this property to specify the single sign-on service bindings.

The binding is the mechanism of message exchange used by SAML requestors and responders.

SocketSettings Property (SAMLIdPServer Component)

Manages network connection settings.

Syntax

property SocketSettings: TsbxSocketSettings read get_SocketSettings;

Remarks

Use this property to tune up network connection parameters.

This property is read-only.

Please refer to the SocketSettings type for a complete list of fields.

TLSSettings Property (SAMLIdPServer Component)

Manages TLS layer settings.

Syntax

property TLSSettings: TsbxTLSSettings read get_TLSSettings;

Remarks

Use this property to tune up the TLS layer parameters.

This property is read-only.

Please refer to the TLSSettings type for a complete list of fields.

URL Property (SAMLIdPServer Component)

Specifies the base URL of this IdP server.

Syntax

property URL: String read get_URL write set_URL;

Default Value

''

Remarks

Use this property to set the base URL for this Identity Provider (IdP) server.

AddIdPSSOLink Method (SAMLIdPServer Component)

Adds an SSO URL to the list.

Syntax

function AddIdPSSOLink(SPIndex: Integer; URL: String; RelayState: String): Integer;

Remarks

Use this method to add a new single sign-on (SSO) link. The method returns the index of the new link in the internal list of SSO links.

SPIndex specifies the index of the service provider configuration, URL contains the relative URL for the SSO, and RelayState contains the value of the corresponding SAML parameter.

According to SAML 2.0 specification, the RelayState parameter may be used by the SAML binding in order to convey and preserve state information. If this parameter is present in a SAML request message, the responding party must include the same exact parameter into the response to this request.

In many applications, when using IdP-initiated single sign-on, the IdP uses RelayState to indicate to the SP the URL to which it should redirect after the successful sign-on.

AddUser Method (SAMLIdPServer Component)

Registers known user credentials.

Syntax

procedure AddUser(Login: String; Password: String);

Remarks

Call this method to register a pair of known user's credentials with the server.

AddUserWithEmail Method (SAMLIdPServer Component)

Registers known user credentials.

Syntax

procedure AddUserWithEmail(Login: String; Email: String; Password: String);

Remarks

Call this method to register known user's credentials with the server. In addition to Login and Password this method also associates an Email address with this user.

ClearUsers Method (SAMLIdPServer Component)

Clears the database of registered users.

Syntax

procedure ClearUsers();

Remarks

Use this method to remove all stored user credential details.

Config Method (SAMLIdPServer Component)

Sets or retrieves a configuration setting.

Syntax

function Config(ConfigurationString: String): String;

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

DoAction Method (SAMLIdPServer Component)

Performs an additional action.

Syntax

function DoAction(ActionID: String; ActionParams: String): String;

Remarks

DoAction is a generic method available in every component. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insensitive) of the action is provided in the ActionID parameter.

ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....

GetProviderProperty Method (SAMLIdPServer Component)

Returns the value of a custom provider property.

Syntax

function GetProviderProperty(Name: String): String;

Remarks

This method, together with SetProviderProperty, provides an extensible way of managing the Identity Provider's settings that are not available through the primary properties of the component. As SAML usage scenarios evolve and new providers appear, the list of supported properties can be extended.

The following properties are currently supported:

• ContactPerson
• OrganizationName
• OrganizationDisplayName
• OrganizationURL
• OrganizationLang

LoadSPMetadata Method (SAMLIdPServer Component)

Loads the metadata required for information exchange with the service provider.

Syntax

function LoadSPMetadata(FileName: String): Integer;

Remarks

The Service provider (SP) may have a lot of different options and requirements for interactions with the Identity provider (IdP). Usually all these options together with X.509 certificates needed for data exchange are stored in XML metadata files. Use this method to load metadata from such file generated by the service provider.

FileName specifies the metadata file name.

ProcessGenericRequest Method (SAMLIdPServer Component)

Processes a generic HTTP SAML request.

Syntax

function ProcessGenericRequest(Request: TBytes): TBytes;

Remarks

Use this method to process a generic well-formed HTTP SAML request obtained elsewhere. This is a handy mechanism to bind the SAML processor to an external web engine.

The Request parameter is expected to contain a full HTTP request, including the HTTP method string (GET, POST) and all the headers. The returned value contains a full HTTP response that should be supplied back to the requestor. You can edit some parts of the response (for example, by adding some custom HTTP headers).

You can use this method with or without the OfflineMode.

RemoveIdPSSOLink Method (SAMLIdPServer Component)

Removes the specified SSO link.

Syntax

procedure RemoveIdPSSOLink(Index: Integer);

Remarks

Multiple URLs may be used on an IdP to initiate the single sign-on (SSO) session. You can add new links using AddIdPSSOLink, and remove ones that are no longer needed with RemoveIdPSSOLink.

RemoveSP Method (SAMLIdPServer Component)

Removes an SP from the list of trusted service providers.

Syntax

procedure RemoveSP(Index: Integer);

Remarks

Use this method to remove information about a service provider from the server.

RemoveUser Method (SAMLIdPServer Component)

Unregister user credentials.

Syntax

procedure RemoveUser(Login: String);

Remarks

Use this method to 'forget' the credentials of the user specified by the Login.

SaveMetadata Method (SAMLIdPServer Component)

Saves the IdP configuration to a metadata file.

Syntax

procedure SaveMetadata(FileName: String);

Remarks

Use this method to save the Identity Provider (IdP) configuration in the form of XML metadata in the file specified by FileName. This file may be transferred to service providers (SP) to adjust their interaction processes.

SaveMetadataToStream Method (SAMLIdPServer Component)

Saves the IdP configuration to a metadata file.

Syntax

procedure SaveMetadataToStream(Stream: TStream);

Remarks

Use this method to save the Identity Provider (IdP) configuration in the form of XML metadata into the Stream. This metadata may be transferred to service providers (SP) to adjust their interaction processes.

SetProviderProperty Method (SAMLIdPServer Component)

Sets the value of a custom provider property.

Syntax

procedure SetProviderProperty(Name: String; Value: String);

Remarks

This method, together with GetProviderProperty, provides an extensible way of managing the Identity Provider's settings that are not available through the primary properties of the component. As SAML usage scenarios evolve and new providers appear, the list of supported properties can be extended.

The following properties are currently supported:

• ContactPerson
• OrganizationName
• OrganizationDisplayName
• OrganizationURL
• OrganizationLang

Start Method (SAMLIdPServer Component)

Starts the IdP server.

Syntax

procedure Start();

Remarks

Use this method to start listening for incoming connections.

Stop Method (SAMLIdPServer Component)

Stops the IdP server.

Syntax

procedure Stop();

Remarks

Call this method to stop listening for incoming connections.

Accept Event (SAMLIdPServer Component)

Reports an incoming connection.

Syntax

type TAcceptEvent = procedure (
  Sender: TObject;
  const RemoteAddress: String;
  RemotePort: Integer;
  var Accept: Boolean
) of Object;

property OnAccept: TAcceptEvent read FOnAccept write FOnAccept;

Remarks

This event is fired when a new connection from RemoteAddress:RemotePort is ready to be accepted. Use the Accept parameter to accept or decline it.

Subscribe to Connect event to be notified of every connection that has been set up.

AssertionCreated Event (SAMLIdPServer Component)

Notifies the application about the creation of a new assertion.

Syntax

type TAssertionCreatedEvent = procedure (
  Sender: TObject;
  ConnectionID: Int64;
  AssertionOrigin: Integer;
  const AssertionType: String;
  var Content: String
) of Object;

property OnAssertionCreated: TAssertionCreatedEvent read FOnAssertionCreated write FOnAssertionCreated;

Remarks

Use this event to track the creation of a new SAML assertion (upon request from the browser or the SP).

The ConnectionID identifies the connection that requested the assertion. AssertionOrigin and AssertionType specify the type of assertion that was prepared and its disposition, and Content contains the body of the assertion. You can alter the body if required, but please keep in mind that changes may invalidate signed assertions.

AssertionReceived Event (SAMLIdPServer Component)

Notifies the application about the receipt of an assertion.

Syntax

type TAssertionReceivedEvent = procedure (
  Sender: TObject;
  ConnectionID: Int64;
  AssertionOrigin: Integer;
  var Content: String
) of Object;

property OnAssertionReceived: TAssertionReceivedEvent read FOnAssertionReceived write FOnAssertionReceived;

Remarks

Use this event to track the receipt of a SAML assertion from the remote party.

The ConnectionID identifies the connection that requested the assertion. AssertionOrigin specifies the disposition of the assertion, and Content contains its body. You can alter the body if required, but please keep in mind that changes may invalidate signed assertions.

Connect Event (SAMLIdPServer Component)

Reports an accepted connection.

Syntax

type TConnectEvent = procedure (
  Sender: TObject;
  ConnectionId: Int64;
  const RemoteAddress: String;
  RemotePort: Integer
) of Object;

property OnConnect: TConnectEvent read FOnConnect write FOnConnect;

Remarks

The component fires this event to report that a new connection has been established. ConnectionId indicates the unique ID assigned to this connection. The same ID will be supplied to any other events related to this connection, such as SessionClosed or SessionEstablished.

Disconnect Event (SAMLIdPServer Component)

Fires to report a disconnected client.

Syntax

type TDisconnectEvent = procedure (
  Sender: TObject;
  ConnectionID: Int64
) of Object;

property OnDisconnect: TDisconnectEvent read FOnDisconnect write FOnDisconnect;

Remarks

The component fires this event when a connected client disconnects.

Error Event (SAMLIdPServer Component)

Information about errors during data delivery.

Syntax

type TErrorEvent = procedure (
  Sender: TObject;
  ErrorCode: Integer;
  const Description: String
) of Object;

property OnError: TErrorEvent read FOnError write FOnError;

Remarks

The event is fired in case of exceptional conditions during message processing.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the section.

ExternalSign Event (SAMLIdPServer Component)

Handles remote or external signing initiated by the server protocol.

Syntax

type TExternalSignEvent = procedure (
  Sender: TObject;
  ConnectionID: Int64;
  const OperationId: String;
  const HashAlgorithm: String;
  const Pars: String;
  const Data: String;
  var SignedData: String
) of Object;

property OnExternalSign: TExternalSignEvent read FOnExternalSign write FOnExternalSign;

Remarks

Assign a handler to this event if you need to delegate a low-level signing operation to an external, remote, or custom signing engine. Depending on the settings, the handler will receive a hashed or unhashed value to be signed.

The event handler must pass the value of Data to the signer, obtain the signature, and pass it back to the component via the SignedData parameter.

OperationId provides a comment about the operation and its origin. It depends on the exact component being used, and may be empty. HashAlgorithm specifies the hash algorithm being used for the operation, and Pars contains algorithm-dependent parameters.

The component uses base16 (hex) encoding for the Data, SignedData, and Pars parameters. If your signing engine uses a different input and output encoding, you may need to decode and/or encode the data before and/or after the signing.

A sample MD5 hash encoded in base16: a0dee2a0382afbb09120ffa7ccd8a152 - lower case base16 A0DEE2A0382AFBB09120FFA7CCD8A152 - upper case base16

A sample event handler that uses the .NET RSACryptoServiceProvider class may look like the following: signer.OnExternalSign += (s, e) => { var cert = new X509Certificate2("cert.pfx", "", X509KeyStorageFlags.Exportable); var key = (RSACryptoServiceProvider)cert.PrivateKey; var dataToSign = e.Data.FromBase16String(); var signedData = key.SignHash(dataToSign, "2.16.840.1.101.3.4.2.1"); e.SignedData = signedData.ToBase16String(); };

MetadataRequest Event (SAMLIdPServer Component)

Notifies the application about the metadata request.

Syntax

type TMetadataRequestEvent = procedure (
  Sender: TObject;
  ConnectionID: Int64;
  var Metadata: String
) of Object;

property OnMetadataRequest: TMetadataRequestEvent read FOnMetadataRequest write FOnMetadataRequest;

Remarks

The component uses this event to notify the application about an incoming metadata request. The suggested metadata text is provided through the Metadata parameter. The application can adjust it as required if it needs to.

Notification Event (SAMLIdPServer Component)

This event notifies the application about an underlying control flow event.

Syntax

type TNotificationEvent = procedure (
  Sender: TObject;
  const EventID: String;
  const EventParam: String
) of Object;

property OnNotification: TNotificationEvent read FOnNotification write FOnNotification;

Remarks

The component fires this event to let the application know about some event, occurrence, or milestone in the component. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in the EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the component, the exact action it is performing, or the document being processed, one or both may be omitted.

SessionClosed Event (SAMLIdPServer Component)

This event is fired when the IdP server has closed a session.

Syntax

type TSessionClosedEvent = procedure (
  Sender: TObject;
  ConnectionID: Int64
) of Object;

property OnSessionClosed: TSessionClosedEvent read FOnSessionClosed write FOnSessionClosed;

Remarks

ConnectionID contains the identifier of the closed session.

SessionEstablished Event (SAMLIdPServer Component)

This event is fired when a new session has been established.

Syntax

type TSessionEstablishedEvent = procedure (
  Sender: TObject;
  ConnectionID: Int64;
  const Username: String
) of Object;

property OnSessionEstablished: TSessionEstablishedEvent read FOnSessionEstablished write FOnSessionEstablished;

Remarks

ConnectionID contains the identifier of the new session, Username specifies the client's address and Username.

VerifyCredentials Event (SAMLIdPServer Component)

Passes user credentials to the application for verification.

Syntax

type TVerifyCredentialsEvent = procedure (
  Sender: TObject;
  ConnectionID: Int64;
  const Username: String;
  const Password: String;
  const Body: String;
  var Accept: Boolean
) of Object;

property OnVerifyCredentials: TVerifyCredentialsEvent read FOnVerifyCredentials write FOnVerifyCredentials;

Remarks

Subscribe to this event to be notified about authentication attempts and adjust the acceptance result as required. This event fires after the user credentials have been validated against the configured database, and the value of the Accept parameter reflects the outcome of the validation.

The Username and Password parameters contain the provided credentials, and the Body parameter contains the unparsed form data.

Certificate Type

Provides details of an individual X.509 certificate.

Remarks

This type provides access to X.509 certificate details.

Fields

Constructors

>

constructor Create();

Creates a new object with default field values.

ExternalCrypto Type

Specifies the parameters of external cryptographic calls.

Remarks

External cryptocalls are used in a Distributed Cryptography (DC) subsystem, which allows the delegation of security operations to the remote agent. For instance, it can be used to compute the signature value on the server, while retaining the client's private key locally.

Fields

Constructors

>

constructor Create();

Creates a new ExternalCrypto object with default field values.

SocketSettings Type

A container for the socket settings.

Remarks

This type is a container for socket-layer parameters.

Fields

Constructors

>

constructor Create();

Creates a new SocketSettings object.

TLSSettings Type

A container for TLS connection settings.

Remarks

The TLS (Transport Layer Security) protocol provides security for information exchanged over insecure connections such as TCP/IP.

Fields

Constructors

>

constructor Create();

Creates a new TLSSettings object.

Config Settings (SAMLIdPServer Component)

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

SAMLIdPServer Config Settings

Base Config Settings

Trappable Errors (SAMLIdPServer Component)

SAMLIdPServer Errors

	1048577   Invalid parameter value (SB_ERROR_INVALID_PARAMETER)
	1048578   Component is configured incorrectly (SB_ERROR_INVALID_SETUP)
	1048579   Operation cannot be executed in the current state (SB_ERROR_INVALID_STATE)
	1048580   Attempt to set an invalid value to a property (SB_ERROR_INVALID_VALUE)
	1048581   Certificate does not have its private key loaded (SB_ERROR_NO_PRIVATE_KEY)
	1048581   Cancelled by the user (SB_ERROR_CANCELLED_BY_USER) 
	30408705   Invalid binging name (SB_ERROR_SAML_INVALID_BINDING_NAME)
	30408706   Invalid binding type (SB_ERROR_SAML_INVALID_BINDING_TYPE)
	30408707   Base directory not set (SB_ERROR_SAML_SP_BASE_DIRECTORY_NOT_SET)