Documentation

Introduction

Use the /overview PATCH and POST endpoints to customize client-side login pages, integrate an SMTP server, configure outgoing emails, and upload logos.

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. (OPTIONAL) Have an SMTP server with which to integrate to receive SecureAuth emails

/overview Endpoints

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

Overview Settings /overview PATCH Endpoint

Use this endpoint to configure the realm's overview settings, including general realm description, SMTP server integration, SecureAuth email messaging, and client-side login page information.

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

Defaulted values in bold

FieldDescriptionAccepted ValuesNote
realmNameAutomatically assigned when created and cannot be changed

N / A

 
realmDescriptionInternal note to briefly describe purpose of realmany 
companyLogoFileLogo image that appears on client-side login pagesfile path, .png, .jpeg, .gif

Must upload image to appliance using /overview/companylogo endpoint

Uploading image also changes field to new file path

applicationLogoFileLogo image that appears on the Secure Portal page that is associated to realmfile path, .png, .jpeg, .gif

Must upload image to appliance using /overview/applicationlogo endpoint

Uploading image also changes field to new file path

documentTitleTitle that displays on the browser tab of client-side login pagesany 
pageHeaderTitle that displays at the top of client-side login pages, typically same as documentTitleany 
themeTheme selected for look and feel of client-side pages
  • 2012
  • 2013
  • 2016 Light
  • Legacy
  • OTP App Default

The 2012 and Legacy themes are deprecated in SecureAuth IdP v9.2

For appliances upgraded to version 9.2, if either the 2012 or Legacy theme was implemented prior to the upgrade, that theme will be converted to the 2016 Light theme

usernameDisplayProperty mapped to the directory attribute of preferred username displayed on (some) post-authentication pages
  • AuthenticatedUserId
  • FirstName
  • LastName
  • Phone1
  • Phone2
  • Phone3
  • Phone4
  • Email1
  • Email2
  • Email3
  • Email4
  • AuxId1
  • AuxId2
  • AuxId3
  • AuxId4
  • AuxId5
  • AuxId6
  • AuxId7
  • AuxId8
  • AuxId9
  • AuxId10
  • Email1UsernameOnly
  • Email2UsernameOnly
  • Email3UsernameOnly
  • Email4UsernameOnly
  • CustomToken
 
usernameLocationWhere the preferred username is displayed on post-authentication page
  • NotShown
  • ShowInHeader
 
forgotUsernameUrlURL of forgot username realm for end-users to access during loginfull URL or /<Forgot Username realmName> 
forgotUsernamePageLocationWhere forgot username URL is displayed on client-side login pages
  • PageFooter
  • UnderInputField
 
forgotPasswordUrlURL of forgot password realm for end-users to access during loginfull URL or /<Forgot Password realmName> 
forgotPasswordPageLocationWhere forgot password URL is displayed on client-side login pages
  • PageFooter
  • UnderInputField
 
restartLoginUrlURL to restart end-users' login processdefaulted to <current realm>/restart.aspx, otherwise full URL of preferred destination 
restartLoginPageLocationWhere restart login URL is displayed on client-side login pages
  • NotShown
  • Footer
  • Header
  • Dynamic
 
copyrightInformationCopyright information displayed in the footer of the client-side pagesany 
eulaUrlURL for company's end-user license agreementfull URL 
disclaimerPageLocationWhere disclaimer information is displayed on client-side pages
  • NotShown
  • PageFooter
 
smtpSettings for SMTP server integrationN / ARequired to enable SecureAuth emails, including OTPs and other account notifications

serverAddress

Address of SMTP server through which SecureAuth emails are sentanyRequired field for SMTP configuration
portSMTP's required portany, default 25Required field for SMTP configuration
usernameUsername of the SMTP account that has rights to send emailsany 
passwordPassword associated to the SMTP account usernameany 
domainDomain name of the SMTP serveranyRequired only for authentication purposes, otherwise leave empty
useSslEnable Secure Socket Layer that acts as encrypted tunnel through which emails are sent
  • true
  • false
 
emailSettings for SecureAuth emailsN / A 
logoFileLogo image that appears on SecureAuth emailsfile path, .png, .jpeg, .gif

Must upload image to appliance using /overview/emaillogo endpoint

Uploading image also changes field to new file path

subjectSubject of the OTP emailany 
showPasscodeInSubjectEnable passcode information to display in email subject
  • true
  • false
 
senderAddressEmail address that displays in the From fieldany 
senderNameAlias name for the email address that displays in the From fieldany 
templateTemplate used for SecureAuth OTP emails
  • OTPEmailTemplate
  • OTPEmailTemplate2013
  • Custom Template Name**
** Non-SecureAuth IdP template that must be added to appliance through Web Admin UI before setting template to custom name via API
Parameters and Response Examples
ParametersSuccess Response
{
	"realmName": "SecureAuth26",
	"realmDescription": "",
	"companyLogoFile": "~/Images/SecureAuth_Logo_OnBlack.png",
	"applicationLogoFile": "~/Images/SecureAuth_Logo_OnBlack.png",
	"documentTitle": "Secure Access",
	"pageHeader": "Secure Access to App",
	"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": "OTPEmailTemplate"
	}
}
{
"status": "Success",
"message": []
}

Upload Company Logo /overview/companylogo POST Endpoint

Use this endpoint to upload a company logo image to the appliance and apply it to the realm. This image displays on the client-side login pages.

HTTP MethodEndpointExampleSecureAuth IdP version
POST
/overview/companylogo
https://secureauth.company.com/api/v1/realms/26/overview/companylogo
v9.1
POST
/overview/companylogo
https://secureauth.company.com/api/v2/realms/26/overview/companylogo
v9.2 or later
Instructions & Notes

Upload the file to the appliance and set the companyLogoFile field

The request content-type must be multipart / form-data

Accepted formats for the file are .png, .jpeg, and .gif

Upload Application Logo /overview/applicationlogo POST Endpoint

Use this endpoint to upload an application logo image to the appliance and apply it to the realm. This image displays on the Secure Portal page that is configured to include this realm.

HTTP MethodEndpointExampleSecureAuth IdP version
POST
/overview/applicationlogo
https://secureauth.company.com/api/v1/realms/26/overview/applicationlogo
v9.1
POST
/overview/applicationlogo
https://secureauth.company.com/api/v2/realms/26/overview/applicationlogo
v9.2 or later
Instructions & Notes

Upload the file to the appliance and set the applicationLogoFile field

The request content-type must be multipart / form-data

Accepted formats for the file are .png, .jpeg, and .gif

Upload Email Logo /overview/emaillogo POST Endpoint

Use this endpoint to upload an email logo image to the appliance and apply it to the realm. This image displays in emails sent to end-users by SecureAuth, including OTP messages and account update notifications.

HTTP MethodEndpointExampleSecureAuth IdP version
POST
/overview/emaillogo
https://secureauth.company.com/api/v1/realms/26/overview/emaillogo
v9.1
POST
/overview/emaillogo
https://secureauth.company.com/api/v2/realms/26/overview/emaillogo
v9.2 or later
Instructions & Notes

Upload the file to the appliance and set the SMTP > LogoFile field

The request content-type must be multipart / form-data

Accepted formats for the file are .png, .jpeg, and .gif

  • No labels