Documentation

Introduction

Use the /postauth PATCH endpoint to configure SAML and WS-Federation assertions.

Choose from SAML 2.0 IdP-initiated, SP-initiated, and SP-initiated by Post; and WS-Federation assertions.

Prerequisites

1. Complete the Enablement and Header Steps in the Admin API Guide

2. Have access to the application code that calls to the API endpoint(s)

3. Integrate a membership and profile directory(s) with SecureAuth IdP (Data Realm Settings Endpoint)

4. Gather required information from the Service Provider for the SAML or WS-Federation integration

/postauth Endpoint

The following endpoints are prepended with the URL, https://<SecureAuth IdP Domain>/api/v1/realms/<realm ID>, if running SecureAuth IdP v9.1 – in which realm ID is the ID number of the realm to configure –

or https://<SecureAuth IdP Domain>/api/v2/realms/<realm ID>, if running SecureAuth IdP v9.2 or later

Post Authentication Settings /postauth PATCH Endpoint

Use this endpoint to configure the realm's post authentication settings for a SAML assertion or WS-Federation assertion. 

HTTP MethodEndpointExampleSecureAuth IdP version
PATCH
/postauth
https://secureauth.company.com/api/v1/realms/26/postauth
v9.1
PATCH
/postauth
https://secureauth.company.com/api/v2/realms/26/postauth
v9.2 or later
Field Definitions and Accepted Values for Configuration

Defaulted values in bold

FieldDescriptionAccepted ValuesNote
redirectTypePost-auth action
  • Saml2SpInitiated
  • Saml2IdpInitiated
  • Saml2SpInitiatedByPost
  • WsFederation
 
redirectSettings for redirectionN / A 
userIdMappingSettings for user ID assertionN / A 
mappingUser ID asserted to SP
  • AuthenticatedUserId
  • FirstName
  • LastName
  • Phone1
  • Phone2
  • Phone3
  • Phone4
  • Email1
  • Email2
  • Email3
  • Email4
  • AuxId1
  • AuxId2
  • AuxId3
  • AuxId4
  • AuxId5
  • AuxId6
  • AuxId7
  • AuxId8
  • AuxId9
  • AuxId10
  • GlobalAuxId1
  • GlobalAuxId2
  • GlobalAuxId3
  • GlobalAuxId4
  • GlobalAuxId5
  • Email1UsernameOnly
  • Email2UsernameOnly
  • Email3UsernameOnly
  • Email4UsernameOnly
  • GroupList
  • FullGroupDnLis
  • CustomTokenValue
 
nameIdFormatFormat of user ID, expected by SP
  • urn:oasis:names:tc:SAML:1.1:nameod-format:unspecified
  • urn:oasis:names:tc:SAML:1.1:nameod-format:emailAddress
  • urn:oasis:names:tc:SAML:2.0:nameod-format:kerberos
  • urn:oasis:names:tc:SAML:2.0:nameod-format:persistent
  • urn:oasis:names:tc:SAML:2.0:nameod-format:transient
  • urn:oasis:names:tc:SAML:1.1:nameod-format:WindowsDomainQualifiedName
  • urn:oasis:names:tc:SAML:1.1:nameod-format:X509SubjectName
 
encodeToBase64Encode user ID to Base64
  • true
  • false
 
assertionSettings for assertionN / A 
wsFedReplyTo_SamlTargetUrlAbsolute URL of target resourceany 
samlConsumerUrlURL provided by SP to accept assertionany 
issuerUnique name shared by IdP and SP to enable communicationany 
samlRecipientIdentifiable information of SAML recipient, typically same as samlConsumerUrlany 
samlAudienceBase domain of applicationany 
spStartUrlSP URL at which end-users log inanyFor Saml2SpInitiated or Saml2SpInitiatedByPost assertions
wsFedVersionVersion of WS-Federation
  • 1.2
  • 1.3
 
wsFedSigningAlgorithmAlgorithm used to sign WS-Federation assertion
  • SHA1
  • SHA2
For WsFederation assertions
samlSigningAlgorithmAlgorithm used to sign SAML assertion
  • SHA1
  • SHA2
For Saml assertions
samlOffsetMinutesNumber of minutes IdP subtracts from NotBefore SAML attribute to account for time differences between IdP and SPnumber 
samlValidHoursNumber of hours during which assertion is validnumber 
appendHttpsToTargetUrlAppend HTTPS to wsFedReplyTo_SamlTargetUrl if not included in field
  • true
  • false
 
generateUniqueAssertionIdGenerate GUID to pass to SP
  • true
  • false
 
signSamlAssertionSign SAML assertion
  • true
  • false
 
signSamlMessageSign SAML message
  • true
  • false
 
encryptSamlAssertionEncrypt SAML assertion
  • true
  • false
 
samlDataEncryptionMethodAlgorithm used to encrypt SAML assertion
  • Empty
  • XmlEncAES128KeyWrapUrl
  • XmlEncAES128Url
  • XmlEncAES192KeyWrapUrl
  • XmlEncAES192Url
  • XmlEncAES256KeyWrapUrl
  • XmlEncAES256Url
  • XmlEncDESUrl
  • XmlEncElementContentUrl
  • XmlEncElementUrl
  • XmlEncEncryptedKeyUrl
  • XmlEncNamespaceUrl
  • XmlEncRSA15Url
  • XmlEncRSAOAEPUrl
  • XmlEncSHA256Url
  • XmlEncSHA512Url
  • XmlEncTripleDESKeyWrapUrl
  • XmlEncTripleDESUrl
If "encryptSamlAssertion": true
encryptionCertificateAlgorithm used to encrypt SAML key
  • Empty
  • XmlEncAES128KeyWrapUrl
  • XmlEncAES128Ur
  • XmlEncAES192KeyWrapUrl
  • XmlEncAES192Url
  • XmlEncAES256KeyWrapUrl
  • XmlEncAES256Url
  • XmlEncDESUrl
  • XmlEncElementContentUrl
  • XmlEncElementUrl
  • XmlEncEncryptedKeyUrl
  • XmlEncNamespaceUrl
  • XmlEncRSA15Url
  • XmlEncRSAOAEPUrl
  • XmlEncSHA256Url
  • XmlEncSHA512Url
  • XmlEncTripleDESKeyWrapUrl
  • XmlEncTripleDESUrl
 
acsSamlRequestCertificatePublic key of Assertion Consumer Service (ACS) / SAML Request Certificate in Base64 format, enabling SecureAuth IdP to accept SAML assertionany 
authenticationMethodMethod used to authenticate subject
  • Empty
  • HardwareToken
  • Rfc1510
  • Password
  • PGP
  • Rfc2945
  • Spki
  • Rfc2246
  • Unspecified
  • X509Pki
  • Xkms
  • Rfc3075
 
confirmationMethodMethod used to confirm subject
  • Empty
  • Bearer
  • SenderVouches
  • HolderOfKey
  • Artifact
 
authenticationContextClassAdditional authentication proof requested by SP
  • AuthenticatedTelephony
  • InternetProtocol
  • InternetProtocolPassword
  • Kerberos
  • MobileOneFactorContract
  • MobileOneFactorUnregistered
  • MobileTwoFactorContract
  • MobileTwoFactorUnregistered
  • NomadTelephony
  • Password
  • PasswordProtectedTransport
  • PersonalTelephony
  • PGP
  • PreviousSession
  • SecureRemotePassword
  • Smartcard
  • SmartcardPKI
  • SoftwarePKI
  • SPKI
  • Telephony
  • TimeSyncToken
  • TLSClient
  • Unspecified
  • X509
  • XMLDSig
 
includeSamlConditionsInclude SAML conditions in assertion
  • true
  • false
 

samlResponseInResponseTo

Include SAML Response InResponseTo in assertion
  • true
  • false
 
subjectConfirmationDataNotBeforeInclude SAML SubjectConfirmationDataNotBefore in assertion
  • true
  • false
 
signingCertSerialNumberCertificate for assertionany 
attributesSettings for attributes sent in assertionN / A 
attributeNumberNumber of attribute in list1 - 10 
nameSpecific name of attribute, provided by SPany 
namespaceURL that communicates what is being asserted, provided by SPany 
formatFormat in which attribute is asserted
  • urn:oasis:names:tc:SAML:2.0:attrname-format:basic
  • urn:oasis:names:tc:SAML:2.0:attrname-format:uri
  • urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified
  • Base64Encoded
  • GroupList
 
valueSecureAuth IdP Profile Property mapped to directory attribute that contains attribute data to assert
  • AuthenticatedUserId
  • FirstName
  • LastName
  • Phone1
  • Phone2
  • Phone3
  • Phone4
  • Email1
  • Email2
  • Email3
  • Email4
  • AuxId1
  • AuxId2
  • AuxId3
  • AuxId4
  • AuxId5
  • AuxId6
  • AuxId7
  • AuxId8
  • AuxId9
  • AuxId10
  • GlobalAuxId1
  • GlobalAuxId2
  • GlobalAuxId3
  • GlobalAuxId4
  • GlobalAuxId5
  • Email1UsernameOnly
  • Email2UsernameOnly
  • Email3UsernameOnly
  • Email4UsernameOnly
  • GroupList
  • FullGroupDnLis
  • CustomTokenValue
 
groupFilterExpressionFurther filter attribute by including groups that start a certain way to send over only necessary group informationany 
extendedSamlAttributesSettings for extended SAML attributesN / AFor Saml assertions
endpointConfigurationSettings for WS-Trust endpointsN / AFor WSFederation assertions
hostBase DNS address of public SecureAuth IdP URLany
endpointsSettings for endpointsN / A
idWS-Trust endpoint nameN / A
enabledEnable endpoint
  • true
  • false
endpointPathWS-Trust endpoint pathN / A
authenticationTypeType of authentication supportedN / A
securityModeType of security modeN / A
typeWS-Trust typeN / A
requestBlockingSettings for WS-Trust request blockingN / A
useAdaptiveAuthforIpBlockingUse Adaptive Authentication IP settings for WS-Trust assertions
  • true
  • false
enableRequestBlockingBlock WS-Trust requests via blocking engine in WS-Trust STS
  • true
  • false
conditionLogicCondition login for blocking rules
  • AND
  • OR
ipAddressBlockingRuleCreate list of allowed or denied IP addresses
  • Allow
  • Deny
ipAddressesList of IP addresses allowed or denied based on ipAddressBlockingRuleany
applicationBlockingRuleCreate list of allowed or denied applications
  • Allow
  • Deny
applicationsList of applications allowed or denied based on applicationBlockingRuleany
userAgentBlockingRulesCreate list of allowed or denied user agents
  • Allow
  • Deny
userAgentsList of user agents allowed or denied based on userAgentBlockingRulesany
redirectPageSecureAuth IdP assertion redirectN / A 
formsAuthenticationSettings for forms authenticationN / A 
nameName of forms authentication tokenany, defaulted to .ASPXFORMSAUTH 
loginUrlURL to which end-user is direct upon token expiration to create a new one

URL path, /<SecureAuth IdP Realm Name>

defaulted to SecureAuth.aspx

 
domainDomain name for forms authenticationanyBlank defaults to IdP appliance domain
requireSslRequire SSL to view token
  • true
  • false
 
cookieModeHow to deliver cookie
  • UseUri
  • UseCookie
  • AutoDetect
  • UseDeviceProfile
 
isSlidingExpirationToken is valid as long as end-user interacts with page
  • true
  • false
 
timeoutNumber of minutes cookie is validnumber, defaulted to 10 
machineKeySettings for machine keyN / A 
validationAlgorithm used to encrypt cookie
  • MD5
  • SHA1
  • TripleDES
  • AES
  • HMACSHA256
  • HMACSHA384
  • HMACSHA512
  • Custom
 
decryptionAlgorithm used to decrypt cookie
  • Auto
  • DES
  • _3DES
  • AES
 
validationKeyKey to validate and enable SSOanyMust generate in Web Admin UI
decryptionKeyKey to decrypt and enable SSOanyMust generate in Web Admin UI
authenticationCookiesSettings for authentication cookiesN / A 
preAuthenticationCookieName of cookie generated from begin siteany, defaulted to PreAuthToken1 
postAuthenticationCookieName of cookie that communicates to IdP that user is authenticatedany, defaulted to PostAuthToken1 
isPersistentEnable persistent cookie
  • true
  • false
 
cleanUpAuthCookieRemove preAuthenticationCookie after authentication
  • true
  • false
 
Parameters and Response Examples
ParametersSuccess Response
SAML Assertion
{
	"redirectType": "Saml2IdpInitiated",
	"redirect": {
		"userIdMapping": {
			"mapping": "AuthenticatedUserId",
			"nameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
			"encodeToBase64": false
		},
		"assertion": {
			"wsFedReplyTo_SamlTargetUrl": "https://application.com/login",
			"samlConsumerUrl": "https://application.com/saml",
			"issuer": "uniquename",
			"samlRecipient": "https://application.com/saml",
			"samlAudience": "www.application.com",
			"spStartUrl": "",
			"wsFedVersion": "1.2",
			"wsFedSigningAlgorithm": "SHA2",
			"samlSigningAlgorithm": "SHA2",
			"samlOffsetMinutes": 5,
			"samlValidHours": 1,
			"appendHttpsToSamlTargetUrl": true,
			"generateUniqueAssertionId": true,
			"signSamlAssertion": false,
			"signSamlMessage": true,
			"encryptSamlAssertion": false,
			"samlDataEncryptionMethod": "Empty",
			"samlKeyEncryptionMethod": "Empty",
			"encryptionCertificate": "",
			"acsSamlRequestCertificate": "",
			"authenticationMethod": "Empty",
			"confirmationMethod": "Empty",
			"authenticationContextClass": "Unspecified",
			"includeSamlConditions": true,
			"samlResponseInResponseTo": true,
			"subjectConfirmationDataNotBefore": false,
			"signingCertSerialNumber": ""
		},
	"attributes": [
			{
				"attributeNumber": 1,
				"name": "emailAddress",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "Email1",
				"groupFilterExpression": ""
			},
			{
				"attributeNumber": 2,
				"name": "lastName",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "LastName",
				"groupFilterExpression": ""
			},
			{
				"attributeNumber": 3,
				"name": "",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "AuthenticatedUserId",
				"groupFilterExpression": ""
			},
			{
				"attributeNumber": 4,
				"name": "",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "AuthenticatedUserId",
				"groupFilterExpression": ""
			},
			{
				"attributeNumber": 5,
				"name": "",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "AuthenticatedUserId",
				"groupFilterExpression": ""
			},
			{
				"attributeNumber": 6,
				"name": "",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "AuthenticatedUserId",
				"groupFilterExpression": ""
			},
			{
				"attributeNumber": 7,
				"name": "",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "AuthenticatedUserId",
				"groupFilterExpression": ""
			},
			{
				"attributeNumber": 8,
				"name": "",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "AuthenticatedUserId",
				"groupFilterExpression": ""
			},
			{
				"attributeNumber": 9,
				"name": "",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "AuthenticatedUserId",
				"groupFilterExpression": ""
			{
				"attributeNumber": 10,
				"name": "",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "AuthenticatedUserId",
				"groupFilterExpression": ""
			}
		],
		"extendedSamlAttributes": null,
		"redirectPage": "Authorized/SAML20IdPInit.aspx"
	},
	"formsAuthentication": {
		"name": ".ASPXFORMSAUTH",
		"loginUrl": "SecureAuth.aspx",
		"domain": "",
		"requireSsl": true,
		"cookieMode": "UseDeviceProfile",
		"isSlidingExpiration": true,
		"timeout": 10
	},
	"machineKey": {
		"validation": "SHA1",
		"decryption": "Auto",
		"validationKey": "AutoGenerate,IsolateApps",
		"decryptionKey": "AutoGenerate,IsolateApps"
	},
	"authenticationCookie": {
		"preAuthenticationCookie": "PreAuthToken1",
		"postAuthenticationCookie": "PostAuthToken1",
		"isPersistent": false,
		"cleanUpAuthCookie": true
	}
}
{
"status": "Success",
"message": []
}
WS-Federation Assertion
{
	"redirectType": "WsFederation",
	"redirect": {
		"userIdMapping": {
			"mapping": "AuthenticatedUserId",
			"nameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
			"encodeToBase64": false
		},
		"assertion": {
			"wsFedReplyTo_SamlTargetUrl": "https://portal.office.com",
			"samlConsumerUrl": "",
			"issuer": "uniquename",
			"samlRecipient": "",
			"samlAudience": "",
			"spStartUrl": "https://portal.office.com/login",
			"wsFedVersion": "1.2",
			"wsFedSigningAlgorithm": "SHA2",
			"samlSigningAlgorithm": "SHA2",
			"samlOffsetMinutes": 0,
			"samlValidHours": 1,
			"appendHttpsToSamlTargetUrl": true,
			"generateUniqueAssertionId": true,
			"signSamlAssertion": false,
			"signSamlMessage": true,
			"encryptSamlAssertion": false,
			"samlDataEncryptionMethod": "Empty",
			"samlKeyEncryptionMethod": "Empty",
			"encryptionCertificate": "",
			"acsSamlRequestCertificate": "",
			"authenticationMethod": "Empty",
			"confirmationMethod": "Empty",
			"authenticationContextClass": "Unspecified",
			"includeSamlConditions": true,
			"samlResponseInResponseTo": true,
			"subjectConfirmationDataNotBefore": false,
			"signingCertSerialNumber": ""
		},
	"attributes": [
			{
				"attributeNumber": 1,
				"name": "",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "AuthenticatedUserId",
				"groupFilterExpression": ""
			},
			{
				"attributeNumber": 2,
				"name": "",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "AuthenticatedUserId",
				"groupFilterExpression": ""
			},
			{
				"attributeNumber": 3,
				"name": "",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "AuthenticatedUserId",
				"groupFilterExpression": ""
			},
			{
				"attributeNumber": 4,
				"name": "",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "AuthenticatedUserId",
				"groupFilterExpression": ""
			},
			{
				"attributeNumber": 5,
				"name": "",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "AuthenticatedUserId",
				"groupFilterExpression": ""
			},
			{
				"attributeNumber": 6,
				"name": "",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "AuthenticatedUserId",
				"groupFilterExpression": ""
			},
			{
				"attributeNumber": 7,
				"name": "",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "AuthenticatedUserId",
				"groupFilterExpression": ""
			},
			{
				"attributeNumber": 8,
				"name": "",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "AuthenticatedUserId",
				"groupFilterExpression": ""
			},
			{
				"attributeNumber": 9,
				"name": "",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "AuthenticatedUserId",
				"groupFilterExpression": ""
			{
				"attributeNumber": 10,
				"name": "",
				"nameSpace": "",
				"format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
				"value": "AuthenticatedUserId",
				"groupFilterExpression": ""
			}
		],
		"endpointConfiguration": {
			"host": "",
			"endpoints": [
				{
					"id": "UsernameMixed05",
					"enabled": false,
					"endpointPath": "/2005/usernamemixed",
					"authenticationType": "Password",
					"securityMode": "Mixed",
					"type": "WS-Trust 2005"
				},
				{
					"id": "WindowsTransport05",
					"enabled": false,
					"endpointPath": "/2005/windowstransport",
					"authenticationType": "Windows",
					"securityMode": "Transport",
					"type": "WS-Trust 2005"
				},
				{
					"id": "IssuedTokenMixedAsymmetricBasic25605",
					"enabled": false,
					"endpointPath": "/2005/issuedtokenmixedasymmetricbasic256",
					"authenticationType": "SAML Token (Asymmetric)",
					"securityMode": "Mixed",
					"type": "WS-Trust 2005"
				},
				{
					"id": "UsernameMixed13",
					"enabled": false,
					"endpointPath": "/13/usernamemixed",
					"authenticationType": "Password",
					"securityMode": "Mixed",
					"type": "WS-Trust 1.3"
				},
				{
					"id": "WindowsTransport13",
					"enabled": false,
					"endpointPath": "/13/windowstransport",
					"authenticationType": "Windows",
					"securityMode": "Transport",
					"type": "WS-Trust 1.3"
				},
				{
					"id": "IssuedTokenMixedAsymmetricBasic25613",
					"enabled": false,
					"endpointPath": "/13/issuedtokenmixedasymmetricbasic256",
					"authenticationType": "SAML Token (Asymmetric)",
					"securityMode": "Mixed",
					"type": "WS-Trust 1.3"
				}
			]
		},
		"requestBlocking": {
			"useAdaptiveAuthForIpBlocking": true,
			"enableRequestBlocking": false,
			"conditionLogic": "OR",
			"ipAddressBlockingRule": null,
			"ipAddresses": null,
			"applicationBlockingRule": null,
			"applications": null,
			"userAgentBlockingRules": null,
			"userAgents": null
		},
		"redirectPage": "Authorized/WSFedProvider.aspx"
	},
	"formsAuthentication": {
		"name": ".ASPXFORMSAUTH",
		"loginUrl": "SecureAuth.aspx",
		"domain": "",
		"requireSsl": true,
		"cookieMode": "UseDeviceProfile",
		"isSlidingExpiration": true,
		"timeout": 10
	},
	"machineKey": {
		"validation": "SHA1",
		"decryption": "Auto",
		"validationKey": "AutoGenerate,IsolateApps",
		"decryptionKey": "AutoGenerate,IsolateApps"
	},
	"authenticationCookie": {
		"preAuthenticationCookie": "PreAuthToken1",
		"postAuthenticationCookie": "PostAuthToken1",
		"isPersistent": false,
		"cleanUpAuthCookie": true
	}
}
Related Documentation
  • No labels