Documentation

Introduction

Use the /workflow PATCH endpoint to dictate the end-user login process, configure Device Recognition, enable redirects, customize token settings.

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)

/workflow 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

Workflow Settings /workflow PATCH Endpoint

Use this endpoint to configure the realm's workflow settings, including client-side login process, device recognition, token preferences, and user redirects.

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

Defaulted values in bold

FieldDescriptionAccepted ValuesNote
deviceRecognitionMethodSettings for persistent tokenN / A 
integrationMethodDevice limitation and functionality of clientCertificationEnrollmentAndValidationOnly one option supported
clientSideControlCredential (persistent token) used in the workflowDeviceBrowserFingerprintingOnly one option supported
browserProfileSettingSettings for Device Recognition browser profilesN / A 
fpModeDeliver cookie to browser to compare with browser profile
  • NoCookie
  • Cookie
For browser profile
Deliver cookie to mobile device or use Device Recognition mobile app to compare with mobile profile
  • Cookie
  • MobileApp
For mobile profile
cookieNamePrefixName prepended to cookie nameany

Full cookie name: cookieNamePrefix + company name + hashed value of user ID

For browser and mobile profiles

cookieExpireLengthNumber of hours during which cookie is validany, numericalFor browser and mobile profiles
matchFpIdInCookieRequire match between profile ID in directory and profile ID of current login
  • true
  • false
For browser and mobile profiles
authenticationThresholdPercentage of current profile score matched against stored profile score required to bypass additional authenticationany, defaulted to 90For browser and mobile profiles
updateThresholdPercentage of current profile score matched against stored profile score required to update stored profile after successful additional authenticationany, defaulted to 89For browser and mobile profiles
mobileProfileSettingSettings for Device Recognition mobile profilesN / A 
skipIpMatchSkip IP address matching between device and stored profile
  • true
  • false
 
profileSettingSettings for Device Recognition profilesN / A 
fpExpirationLengthNumber of days during which profile is validany, defaulted to 00 or negative: no expiration
fpExpirationSinceLastAccessNumber of days profile is valid since last accessany, defaulted to 00 or negative: no expiration
allowOnlyOneFpCookiePerBrowserOne cookie allowed per browser
  • true
  • false
 
totalFpMaxCountNumber of Device Recognition profiles allowed per user account at single timenumber, defaulted to -1-1 : no maximum amount
whenExceedingMaxCountAction to take when exceeding max profile amount
  • Allow
  • NotAllow
If totalFpMaxCount sets limit
replaceInOrderByMethod to replace existing profiles with new ones when exceeding max amount
  • CreateTime
  • LastAccessTime
If totalFpMax Count sets limit and " whenExceedingMaxCount": "Allow"
fpAccessRecordsMaxCountNumber of access history records stored per profilenumber, defaulted to 5 
loginScreenSettings for client-side login pagesN / A 
defaultWorkflowWorkflow for end-user login
  • UsernameOnly
  • Username_SecondFactor
  • ValidPersistentTokenOnly
  • UsernameAndPassword
  • UsernameAndPassword_SecondFactor
  • Username_Password
  • Username_SecondFactor_Password
  • ValidPersistentToken_Password
  • ValidPersistentToken_SecondFactor
  • ValidPersistentToken_SecondFactor_Password
 
publicPrivateModeDesignated mode for end-user login
  • PublicPrivate
  • PublicOnly
  • PrivateOnly
 
publicPrivateModeDefaultDefault selection on client-side login page
  • Public
  • Private
  • NoDefault
If " publicPrivateMode": "PublicPrivate"
rememberPublicPrivateUserSelectionAutomatically select end-user's last selected publicPrivateMode option
  • true
  • false
 
showInlinePasswordChangeAllow end-users to update expired passwords during login
  • true
  • false
Requires Web Admin UI configuration
passwordThrottleSettings for password throttlingN / ARefer to Password Throttling Configuration Guide for more information
enabledEnable password throttling in realm
  • true
  • false
 
maxFailedAttemptsNumber of failed attempts allowed before action takes placenumber, defaulted to 5 
intervalNumber of timeUnit during which failed attempts are countednumber, defaulted to 5 
timeUnitUnit of time for interval
  • Minutes
  • Hours
  • Days
 
actionAction to take when maxFailedAttempts is reached during interval:timeUnit
  • BlockUserUntilTimeLimitExpires
  • LockUserAfterExceedingAttempts
 
storageLocationProperty that contains the timestamps and count of failed password attempts
  • AuxID1
  • AuxID2
  • AuxID3
  • AuxID4
  • AuxID5
  • AuxID6
  • AuxID7
  • AuxID8
  • AuxID9
  • AuxID10
  • Email1
  • Email2
  • Email3
  • Email4
  • Phone1
  • Phone2
  • Phone3
  • Phone4
 
sessionTimeoutSettings for browser session during workflowN / A 
sessionStateNameName of session stateany, defaulted to ASP.NET_SessionId<realm ID> 
idleTimeoutLengthNumber of minutes during which end-user must interact with browser before session expires and re-authentication is requirednumber, defaulted to 10 
displayTimeoutMessageDisplay message when session times out
  • Disabled
  • DisplayTimeout
  • AutoRestart
 
tokenPersistenceSettings for persistent token (Device Recognition profiles)N / A 
validatePersistentTokenCheck validity of token
  • true
  • false
 
renewPersistentTokenGenerate new token once previous one is validated
  • true
  • false
 
redirectSettings for workflow redirectsN / A 
invalidPersistentTokenRedirectURL to which end-users are redirected if persistent token is invalidURL path, /<SecureAuth IdP Realm Name>/<realm name> supported if realms on same appliance   
tokenMissingRedirectURL to which end-users are redirected if persistent token is missingURL path, /<SecureAuth IdP Realm Name>
profileMissingRedirectURL to which end-users are redirected if profile is missingURL path, /<SecureAuth IdP Realm Name>, defaulted to profilemissing.aspx
mobileRedirectSecureAuth IdP realm to which end-users are redirected if on mobile devicerealmName, e.g. SecureAuth14 
mobileIdentifiersIdentifiers of mobile devices to enable mobileRedirectany, defaulted to ios,iphone,ipad,android,wp7 
terminationPointSettings for load balancer integrationN / A 
clientFqdnFully Qualified Domain Name (FQDN) set as client point of termination for SecureAuth IdP validationFQDN 
sslTerminationCertificateTrusted SSL certificate for bi-lateral authentication with SecureAuth IdP not acting as termination pointcertificate BLOBNot required if providing sslCertificateAddress
sslCertificateAddressLoad balancer FQDN where SSL connection is terminatedFQDNNot required if providing sslTerminationCertificate
sslTerminationPointFQDN of where sslTerminationCert is terminated to allow SecureAuth IdP to validate informationFQDN 
customIdentityConsumerSettings for pre-authentication workflowN / A 
receiveTokenType of token received by SecureAuth IdP from other site
  • SendTokenOnly
  • None
  • Token
  • ClearTextQueryString
  • XORBase64QueryString
  • SendXORBase64Only
  • ReceiveTokenOnly
 
requireBeginSiteEnable pre-authentication page for workflow
  • true
  • false
 
beginSiteType of pre-authentication begin site
  • Custom
  • BasicAuthentication
  • CertificateFinderV1
  • CertificateFinderV2
  • ClientSideSsl
  • FingerprintFinder
  • FormPost
  • MultiWorkflow
  • NativeCertificateFinder
  • WindowsSso
  • WindowsSsoSkipWorkflow
  • CiscoIse
  • YubiKey
Begin sites may require Web Admin UI configuration
windowsSsoUserImpersonationRun SecureAuth IdP as user or service name when using IWA (Kerberos)
  • true
  • false
 
windowsSsoWindowsAuthenticationEnable Windows Desktop SSO (Kerberos)
  • true
  • false
 
yubiKeyProvisionPageURL of end-user YubiKey provisioning pageURL path 
customBeginSiteUrlURL of pre-authentication begin siteURL pathIf "beginSite": "Custom", otherwise null
receiveTokenDataTypeLocation of user ID in token received by SecureAuth IdP
  • Name
  • UserData
 
sendTokenDataTypeLocation of user ID in token sent by SecureAuth IdP
  • UserId
  • Password
  • Phone1
  • Phone2
  • Phone3
  • Phone4
  • Email1
  • Email2
  • Email3
  • Email4
  • AuxId1
  • AuxId2
  • AuxId3
  • AuxId4
  • AuxId5
  • AuxId6
  • AuxId7
  • AuxId8
  • AuxId9
  • AuxId10
  • FirstName
  • LastName
  • Custom
 
userIdCheckCheck for "Cisco-specific" user ID
  • true
  • false
For Cisco ASA integrations only
allowTransparentSsoEnable transparent SSO between associated realms / applications
  • true
  • false
 
delimiterXOR delimiter used with shared secret to encrypt user IDany 
getSharedSecretShared secret sent to SecureAuth IdP, provided by SPnumber, 1 - 223 
setSharedSecretShared secret sent by SecureAuth IdPnumber, 1 - 223 
fbaWebServiceSettings for FBA Web ServiceN / A 
enabledEnable FBA Web Service
  • true
  • false
 
usernameUsername for FBA Web Service communicationany 
passwordPassword associated to usernameany 
Parameters and Response Examples
ParametersSuccess Response
{
	"deviceRecognitionMethod": {
		"integrationMethod": "CertificationEnrollmentAndValidation",
		"clientSideControl": null
	},
	"browserProfileSetting": {
		"fpMode": "NoCookie",
		"cookieNamePrefix": "SecureAuthDFP_",
		"cookieExpireLength": 168,
		"matchFpIdInCookie": false,
		"authenticationThreshold": 90,
		"updateThreshold": 89
	},
	"mobileProfileSetting": {
		"fpMode": "Cookie",
		"cookieNamePrefix": "SecureAuthDFP_",
		"cookieExpireLength": 72,
		"matchFpIdInCookie": true,
		"skipIpMatch": true,
		"authenticationThreshold": 100,
		"updateThreshold": 90
	},
	"profileSetting": {
		"fpExpirationLength": 0,
		"fpExpirationSinceLastAccess": 0,
		"allowOnlyOneFpCookiePerBrowser": false,
		"totalFpMaxCount": -1,
		"whenExceedingMaxCount": "Allow",
		"replaceInOrderBy": "CreateTime",
		"fpAccessRecordsMaxCount": 5
	},
	"loginScreen": {
		"defaultWorkflow": "Username_SecondFactor_Password",
		"publicPrivateMode": "PublicPrivate",
		"publicPrivateDefault": "Private",
		"rememberPublicPrivateUserSelection": true,
		"showUserIdTextbox": false,
		"showInlinePasswordChange": false
		"passwordThrottle": {
			"enabled": true,
			"maxFailedAttempts": 5,
			"interval": 14,
			"timeUnit": "Minutes",
			"action": "LockUserAfterExceedingAttempts",
			"storageLocation": "AuxID3"
		}
	},
	"sessionTimeout": {
		"sessionStateName": "ASP.NET_SessionId220",
		"idleTimeoutLength": 10,
		"displayTimeoutMessage": "Disabled"
	},
	"tokenPersistence": {
		"validatePersistentToken": true,
		"renewPersistentToken": false
	},
	"redirect": {
		"invalidatePersistentTokenRedirect": "",
		"tokenMissingRedirect": "",
		"profileMissingRedirect": "profilemissing.aspx",
		"mobileRedirect": "",
		"mobileIdentifiers": "ios,iphone,ipad,android,wp7"
	},
	"terminationPoint": {
		"clientFqdn": "",
		"sslTerminationCertificate": "",
		"sslCertificateAddress": "",
		"sslTerminationPoint": ""
	},
	"customIdentityConsumer": {
		"receiveToken": "SendTokenOnly",
		"requireBeginSite": false,
		"beginSite": "Custom",
		"windowsSsoUserImpersonation": false,
		"windowsSsoWindowsAuthentication": false,
		"yubiKeyProvisionPage": "",
		"customBeginSiteUrl": "",
		"receiveTokenDataType": "Name",
		"sendTokenDataType": "UserId",
		"userIdCheck": true,
		"allowTransparentSso": false,
		"delimiter": "",
		"getSharedSecret": 111,
		"setSharedSecret": 111
	},
	"fbaWebService": {
		"enabled": false,
		"username": "",
		"password": ""
	}
}
{
"status": "Success",
"message": []
}
Related Documentation
  • No labels