Documentation

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 MethodEndpointExampleSecureAuth 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
Definitions
  • 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
Success Response Example
The following examples show success responses for realm setup. The responses map to the settings available for the UI. For example, the "overview" responses map to Overview Tab Settings. The "data" responses map to Data Tab Configuration. For more mappings, see Admin Guide (versions 9.1+).


{
    "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 MethodEndpointExampleSecureAuth 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
Definitions

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

  • No labels