IPWorks Auth 2020 C++ Builder Edition

Questions / Feedback?

SAML Component

Properties   Methods   Events   Configuration Settings   Errors  

The SAML component is used to obtain security tokens and assertions.

Syntax

TipaSAML

Remarks

The SAML component provides an easy-to-use interface to obtain security tokens and assertions. The component can also be used to parse assertions and inspect the claims within.

The component has built in support for working with Microsoft SharePoint Online and Microsoft Dynamics CRM Online. This support means only a minimum of information needs to be supplied to the component.

Microsoft SharePoint Online and Dynamics CRM Online

To begin working with SharePoint Online or Dynamics CRM Online first set the AuthMode to the appropriate value. The component will automatically populate several properties to known values. Set the User, Password, ApplicationURN properties and call GetSecurityToken. For instance:


component.AuthMode = SAMLAuthModes.amDynamicsCRM; //dynamic crm
component.User = "user@mycrm.onmicrosoft.com";
component.Password = "password";
component.ApplicationURN = "urn:crmapac:dynamics.com";
component.GetSecurityToken();
After calling GetSecurityToken the SecurityTokenXML property will be populated.

ADFS and Others

When working with ADFS or another Security Token Service (STS) the GetAssertion method may be used to obtain an assertion. To begin set AuthMode to either amADFS or amCustom. Then set LocalSTS, User, Password, and ApplicationURN. For instance:


component.AuthMode = SAMLAuthModes.amADFS;
component.User = "administrator";
component.Password = "admin";
component.LocalSTS = "https://adfs.contoso.com";
component.ApplicationURN = "https://fsweb.contoso.com/ClaimsAwareWebAppWithManagedSTS/";
component.GetAssertion();
If the assertion is signed the component will use the certificate specified in SignerCert to verify the signature. If SignerCert is not set the component will attempt to parse the certificate present in the assertion to perform verification.

After the assertion is parsed and the signature is verified (if present) the following properties will be populated:

Parsing an Assertion

The component may also be used to parse an existing assertion without contacting a STS. To parse an existing assertion call ParseAssertion with the assertion XML. If the assertion is signed the component will use the certificate specified in SignerCert to verify the signature. If SignerCert is not set the component will attempt to parse the certificate present in the assertion to perform verification.

After the assertion is parsed and the signature is verified (if present) the following properties will be populated:

Property List


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

ApplicationURNThe application's Uniform Resource Name (URN).
AssertionIdThe assertion id.
AssertionIssueInstantThe time in UTC that the assertion was issued.
AssertionIssuerThe assertion issuer.
AssertionNotBeforeThe date on which the assertion becomes valid.
AssertionNotOnOrAfterThe time at which the assertion expires.
AssertionSubjectThe subject of the assertion.
AssertionVersionThe version of the assertion.
AssertionXMLThe assertion XML.
AuthModeThe authentication mode.
CertEncodedThe certificate (PEM/base64 encoded).
CertStoreThe name of the certificate store for the client certificate.
CertStorePasswordIf the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
CertStoreTypeThe type of certificate store for this certificate.
CertSubjectThe subject of the certificate used for client authentication.
ClaimCountThe number of records in the Claim arrays.
ClaimIssuerNameThe name of the issuer.
ClaimOriginalIssuerThe name of the original issuer.
ClaimPropertyCountThe number of properties in the claim.
ClaimPropertyIndexSelects a property.
ClaimPropertyNameThe name of the property.
ClaimPropertyValueThe value of the property.
ClaimTypeNameThe type name of the claim.
ClaimValueThe value of the claim.
ClaimValueTypeThe type of value.
FederationSTSThe URL of the federation Security Token Service (STS).
FederationURNThe federation Uniform Resource Name (URN).
LocalSTSThe local Security Token Service (STS).
PasswordThe user's password.
ProxyAuthSchemeThis property is used to tell the component which type of authorization to perform when connecting to the proxy.
ProxyAutoDetectThis property tells the component whether or not to automatically detect and use proxy system settings, if available.
ProxyPasswordThis property contains a password if authentication is to be used for the proxy.
ProxyPortThis property contains the TCP port for the proxy Server (default 80).
ProxyServerIf a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.
ProxySSLThis property determines when to use SSL for the connection to the proxy.
ProxyUserThis property contains a user name, if authentication is to be used for the proxy.
SecurityTokenXMLThe security token XML.
SignerCertEncodedThe certificate (PEM/base64 encoded).
SignerCertStoreThe name of the certificate store for the client certificate.
SignerCertStorePasswordIf the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
SignerCertStoreTypeThe type of certificate store for this certificate.
SignerCertSubjectThe subject of the certificate used for client authentication.
SSLAcceptServerCertEncodedThe certificate (PEM/base64 encoded).
SSLCertEncodedThe certificate (PEM/base64 encoded).
SSLCertStoreThe name of the certificate store for the client certificate.
SSLCertStorePasswordIf the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
SSLCertStoreTypeThe type of certificate store for this certificate.
SSLCertSubjectThe subject of the certificate used for client authentication.
SSLServerCertEncodedThe certificate (PEM/base64 encoded).
UserThe username.
AttrCountThe number of records in the Attr arrays.
AttrNameThe Name provides the local name (without prefix) of the attribute.
AttrNamespaceAttribute namespace.
AttrPrefixAttribute prefix (if any).
AttrValueAttribute value.
XChildCountThe number of records in the XChild arrays.
XChildNameThe Name property provides the local name (without prefix) of the element.
XChildNamespaceNamespace of the element.
XChildPrefixPrefix of the element (if any).
XChildXTextThe inner text of the element.
XElementThe name of the current element.
XNamespaceThe namespace of the current element.
XParentThe parent of the current element.
XPathProvides a way to point to a specific element in the document.
XPrefixThe prefix of the current element.
XSubTreeA snapshot of the current element in the document.
XTextThe text of the current element.

Method List


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

ConfigSets or retrieves a configuration setting.
GetAssertionGets the assertion.
GetSecurityTokenGets the security token.
ParseAssertionParses the specified assertion.

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.

CharactersFired for plain text segments of the input stream.
CommentFired when a comment section is encountered.
EndElementFired when an end-element tag is encountered.
ErrorInformation about errors during data delivery.
PIFired when a processing instruction section is encountered.
SSLServerAuthenticationFired after the server presents its certificate to the client.
SSLStatusShows the progress of the secure connection.
StartElementFired when a begin-element tag is encountered in the document.

Configuration Settings


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

AssertionXPathThe XPath to the assertion.
DecryptAssertionWhether to decrypt the assertion.
EncryptedAssertionXPathThe XPath to the encrypted assertion.
RawRequestReturns the raw HTTP request.
RawResponseReturns the raw HTTP response.
UserRealmThe URL of a web service to determine the LocalSTS (if any).
BuildInfoInformation about the product's build.
CodePageThe system code page used for Unicode to Multibyte translations.
LicenseInfoInformation about the current license.
UseInternalSecurityAPITells the component whether or not to use the system security libraries or an internal implementation.

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks Auth 2020 C++ Builder Edition - Version 20.0 [Build 8155]