Introduction
Use the /realms POST endpoint to create new realms from a template web.config and the /realms/<realm ID> GET endpoint to list the current realm's 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)
/realms Endpoints
The following endpoints are prepended with the URL, https://<SecureAuth IdP Domain>/api/v1 if running SecureAuth IdP v9.1
– or https://<SecureAuth IdP Domain>/api/v2 if running SecureAuth IdP v9.2 or later
Create Realm /realms POST Endpoint
Use this endpoint to create new SecureAuth IdP realms. Once created, the realm is configured with the default, template settings.
| HTTP Method | Endpoint | Example | SecureAuth IdP version |
|---|---|---|---|
POST | /realms | https://secureauth.company.com/api/v1/realms | v9.1 |
POST | /realms | https://secureauth.company.com/api/v2/realms | v9.2 or later |
- Id: The unique ID associated to the created realm, and the ID used for the subsequent endpoints to configure the realm's settings
- Overview: The realm's default Overview settings, configured via the Overview endpoint
- Data: The realm's default Data settings, configured via the Data endpoints
- Workflow: The realm's default Workflow settings, configured via the Workflow endpoint
- AdaptiveAuthentication: The realm's default Adaptive Authentication settings, configured via the Adaptive Authentication endpoint
- MultiFactor: The realm's default Multi-Factor Methods settings, configured via the Multi-Factor Methods endpoint
- PostAuthentication: The realm's default Post Authentication settings, configured via the Post Authentication endpoint
- ApiSetting: The realm's default API settings, configured via the API endpoints
- LogSetting: The realm's default Logs settings, configured via the Logs endpoint
- status: The status of the call, either Success or Failure / Error
- message: Additional information pertaining to the status that is populated only in failure responses
{
"realm": {
"id": 26,
"overview": {
"realmName": "SecureAuth26",
"realmDescription": "",
"companyLogoFile": "~/Images/SecureAuth_Logo_OnBlack.png",
"applicationLogoFile": "~/Images/SecureAuth_Logo_OnBlack.png",
"documentTitle": "Document Title",
"pageHeader": "Page Header",
"theme": "2016 Light",
"usernameDisplay": "AuthenticatedUserId",
"usernameLocation": "NotShown",
"forgotUsernameUrl": "",
"forgotUsernamePageLocation": "PageFooter",
"forgotPasswordUrl": "",
"forgotPasswordPageLocation": "PageFooter",
"restartLoginUrl": "",
"restartLoginPageLocation": "Footer",
"copyrightInformation": "Copyright 2016 SecureAuth Corp. All rights reserved.",
"eulaUrl": "",
"disclaimerPageLocation": "NotShown",
"smtp": {
"serverAddress": "",
"port": 25,
"username": "",
"password": "",
"domain": "",
"useSsl": false
},
"email": {
"logoFile": "~/Images/SecureAuth_Logo_OnBlack.png",
"subject": "SecureAuth One Time Registration Code",
"showPasscodeInSubject": "False",
"senderAddress": "do-not-reply@company.com",
"senderName": "SecureAuth Support",
"template": "OTP/OTPEmailTemplate.ascx"
}
},
"data": {
"membership": {
"dataStoreType": "ADSamAccountName",
"dataStore": {
"server": "LDAP://127.0.0.1/",
"distinguishedName": "DC=domain,DC=com",
"domain": "domain.com",
"allowAnonymousLookup": false,
"connectionMode": "Secure",
"useCyberArkVault": null,
"cyberArkVault": null,
"serviceAccount": "service@domain.com",
"serviceAccountPassword": "***************",
"searchAttribute": "samAccountName",
"searchFilter": "(&(samAccountName=%v)(objectclass=*))",
"useAdvancedAdUserCheck": false,
"validateUserType": "Search",
"userGroupCheckType": "AllowAccess",
"userGroups": "",
"includeNestedGroups": false,
"groupsField": "memberOf",
"maxInvalidPasswordAttempt": 10
}
},
"profile": {
"defaultProvider": "LDAPProfileProvider",
"dataStoreType": "ADSamAccountName",
"ldapDataStore": {
"connectionMode": "Secure",
"connectionString": "LDAP://127.0.0.1/DC=domain,DC=com",
"searchFilter": "(&(samAccountName=%v)(objectclass=*))",
"searchAttribute": "",
"useCyberArkVault": null,
"cyberArkVault": null,
"userGroups": "",
"connectionUsername": "service@domain.com",
"connectionPassword": "***************",
"includeNestedGroups": false
},
"sqlDataStore": {
"sprocGetUserProfile": "",
"sprocUpdateProfile": "",
"allowedGroups": "",
"connectionString": "Data Source=[ServerName];Initial Catalog=[DatabaseName];User ID=[SQLUserName];Password=***************",
"useCyberArkVault": null,
"cyberArkVault": null
},
"oracleDataStore": {
"connectionString": "Data Source=(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1522)))(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=[DBName]))); User Id=[username];Password=***************",
"useCyberArkVault": null,
"cyberArkVault": null,
"sprocGetProfile": "",
"sprocUpdateProfile": ""
},
"azureDataStore": {
"username": "",
"password": "",
"tenantDomain": "",
"clientId": "",
"appKey": ""
},
"webServiceDataStore": {
"username": "FBAService",
"password": "",
"allowedUserGroups": "",
"failover": false,
"mainUrls": []
},
"profileFields": [
{
"propertyName": "FirstName",
"source": "DefaultProvider",
"field": "givenName",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "LastName",
"source": "DefaultProvider",
"field": "sn",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "AuxID1",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "AuxID2",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "AuxID3",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "AuxID4",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "AuxID5",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "AuxID6",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "AuxID7",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "AuxID8",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "AuxID9",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "AuxID10",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "Email1",
"source": "DefaultProvider",
"field": "mail",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "Email2",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "Phone1",
"source": "DefaultProvider",
"field": "telephoneNumber",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "Phone2",
"source": "DefaultProvider",
"field": "mobile",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "Phone3",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "Phone4",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "KbQuestions",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "KbAnswers",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "CertCount",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "CertResetDate",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "GroupList",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": null
},
{
"propertyName": "pinHash",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "MobileResetDate",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "MobileCount",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "CertSerialNumber",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "ExtSyncPwdDate",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "Email3",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "Email4",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "CertExpiration",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "HardwareToken",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "iOSDevices",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": null
},
{
"propertyName": "OATHSeed",
"source": "DefaultProvider",
"field": "",
"dataFormat": "AdvancedEncryption",
"isWritable": false
},
{
"propertyName": "DigitalFP",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainBinary",
"isWritable": false
},
{
"propertyName": "PNToken",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainBinary",
"isWritable": false
},
{
"propertyName": "OneTimeOATHList",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": false
},
{
"propertyName": "AccessHistory",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainBinary",
"isWritable": false
},
{
"propertyName": "OATHToken",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainBinary",
"isWritable": false
},
{
"propertyName": "BehaveBio",
"source": "DefaultProvider",
"field": "",
"dataFormat": "PlainText",
"isWritable": null
}
]
},
"globalAux1": "",
"globalAux2": "",
"globalAux3": "",
"globalAux4": "",
"globalAux5": ""
},
"workflow": {
"deviceRecognitionMethod": {
"integrationMethod": "CertificationEnrollmentAndValidation",
"clientSideControl": "DeviceBrowserFingerprinting"
},
"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": 90,
"updateThreshold": 89
},
"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": false,
"maxFailedAttempts": 5,
"interval": 5,
"timeUnit": "Minutes",
"action": "BlockUseUntilTimeLimitExpires",
"storageLocation": "AuxID1"
}
},
"sessionTimeout": {
"sessionStateName": "ASP.NET_SessionId[SATemplate]",
"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": ""
}
},
"adaptiveAuthentication": {
"ipCountrySetting": {
"enabled": false,
"restrictionType": null,
"inListAction": null,
"ipCountryList": null,
"failureAction": null,
"failureActionRedirect": null,
"requireUsernameBeforeAdaptive": null
},
"userGroupSetting": {
"enabled": false,
"restrictionType": null,
"inListAction": null,
"userGroupList": null,
"failureAction": null,
"failureActionRedirect": null
},
"ipReputationThreatData": {
"enabled": false,
"extremeRiskAction": null,
"extremeRiskRedirect": null,
"highRiskAction": null,
"highRiskRedirect": null,
"mediumRiskAction": null,
"mediumRiskRedirect": null,
"lowRiskAction": null,
"lowRiskRedirect": null,
"ipWhitelist": null,
"requireUsernameBeforeAdaptiveAuth": null
},
"geoVelocity": {
"enabled": false,
"velocityLimit": null,
"failureAction": null,
"failureActionRedirect": null
},
"userRisk": {
"enabled": false,
"highRiskFrom": null,
"highRiskAction": null,
"highRiskRedirect": null,
"mediumRiskFrom": null,
"mediumRiskAction": null,
"mediumRiskRedirect": null,
"lowRiskFrom": null,
"lowRiskAction": null,
"lowRiskRedirect": null,
"noScoreAction": null,
"noScoreRedirect": null,
"profileField": null
},
"analyzeOrder": []
},
"multiFactor": {
"phoneSetting": {
"field1": "VoiceAndSmsText",
"field2": "VoiceAndSmsText",
"field3": "Disabled",
"field4": "Disabled",
"phoneSmsSelected": "Voice",
"isVisible": true,
"defaultCountryCode": null,
"mask": ""
},
"phoneBlocking": {
"blockedSources": [],
"blockRecentlyChangedCarrier": false,
"allowApproveDeleteRecentlyChangedCarrier": false,
"carrierStorageField": "AuxID2",
"enableBlockAllowList": false,
"listAction": null,
"phoneCarriers": null
},
"emailSetting": {
"field1": "True",
"field2": "False",
"field3": "False",
"field4": "False"
},
"knowledgeBasedSetting": {
"enableQuestions": false,
"format": "Base64",
"questionCount": 2,
"doConversion": false
},
"helpDeskSettings": {
"helpDesk1": {
"enabled": false,
"phone": "555-555-1212",
"email": "YourSupport@Company.com"
},
"helpDesk2": {
"enabled": false,
"phone": "",
"email": ""
}
},
"pinSetting": {
"enabled": false,
"openPin": false,
"oneTimeUse": false,
"showWhenEmpty": false
},
"oath": {
"enabled": false,
"passcodeLength": 6,
"passcodeChangeInterval": 60,
"passcodeOffset": 5,
"cacheLockoutDuration": 10
},
"pushNotification": {
"requestType": "Disabled",
"loginRequestTimeout": 1,
"acceptMethod": "AcceptButton",
"companyName": "",
"applicationName": "",
"maxDeviceCount": -1,
"exceedingMaxCountAction": "AllowToReplace",
"replaceOrderBy": "CreatedTime"
},
"yubiKeySetting": {
"enableYubiKeyAuthentication": false,
"validateYubiKey": true,
"storageLocation": "HardwareToken"
},
"multiFactorSetting": {
"inlineInitializeMissingPhone": false,
"inlineInitializeMissingEmail": false,
"inlineInitializeMissingKbAnswers": false,
"inlineInitializeMissingPin": false,
"enableAutoSubmitWhenAvailable": false,
"otpLength": 6,
"enableThrottling": false,
"throttleMaxFailedAttempts": 5,
"throttleInterval": 30,
"throttleTimeUnit": "Minutes",
"throttleAction": "BlockUseUntilTimeLimitExpires",
"throttleStorageLocation": "AuxID1",
"otpValidateThrottleMaxFailedAttempts": null,
"otpValidateThrottleInterval": null,
"otpValidateThrottleTimeUnit": null
},
"registrationMethodOrder": [
"Email",
"KBQ",
"Help",
"PIN",
"Phone",
"OATH"
]
},
"postAuthentication": {
"redirectType": null,
"redirect": null,
"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
}
},
"apiSetting": {
"enableApi": false,
"applicationId": null,
"applicationKey": null,
"enableAuthenticationApi": false,
"enableIdentityManagementUserProperties": false,
"enableIdentityManagementAdminInitiatedPasswordReset": false,
"enableIdentityManagementUserSelfServicePasswordChange": false,
"enableIdentityManagementUserGroupAssociation": false,
"enableSecureAuthCredentialProviderApi": false
},
"logSetting": {
"logInstanceId": "SecureAuth[SATemplate]",
"enableAuditSyslog": false,
"enableAuditEventLog": false,
"enableAuditTextLog": false,
"enableAuditDatabaseLog": false,
"enableAuditExtendedOtpLog": false,
"enableDebugSyslog": false,
"enableDebugEventLog": false,
"enableDebugTextLog": false,
"enableErrorSyslog": false,
"enableErrorEventLog": false,
"enableErrorTextLog": true,
"customErrorMode": "On",
"customErrorRedirect": "customerror.htm",
"syslogSetting": {
"server": "",
"port": 514,
"rfcSpec": "None",
"privateEnterpriseNumber": null
},
"logDatabaseConnectionString": "Data Source=localhost\\SQLEXPRESS;Initial Catalog=Logging;User ID=SecureAuthSQLUser;Password=***************"
}
},
"status": "Success",
"message": []
}
List Realm Settings /realms/<realm ID> GET Endpoint
Use this endpoint to view the realm's current configuration. No settings can be configured at this endpoint.
| HTTP Method | Endpoint | Example | SecureAuth IdP version |
|---|---|---|---|
| GET | /realms/<realm ID> | https://secureauth.company.com/api/v1/realms/26 | v9.1 |
| GET | /realms/<realm ID> | https://secureauth.company.com/api/v2/realms/26 | v9.2 or later |
Realm ID: The unique ID of the SecureAuth IdP realm, generated in the Create Realm endpoint response or acquired from the Web Admin UI as the Realm Name, e.g. SecureAuth26, with 26 being the realm ID