FMoP TOTP MCF Plugin
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Provision Instance

Provision a user with a TOTP authenticator instance

An end-user needs to be first provisioned with at least one TOTP instance before they can use this feature. Depending on server-side configuration settings, more than one TOTP instance could be provisioned to an end-user.

SOAP element Required Type Description
provisionNewInstance true boolean Set to true in order to provision a new TOTP instance.
newDeviceName false string The name of the device the TOTP is being provisioned to. For example, “Mike’s iPhone” or similar. The intent is to associate a user-friendly name to each TOTP instance, to allow end-users to manage them. This is relevant in particular if end-users are allowed to provision multiple TOTP devices.
newInstanceDigits true integer The OTP’s length. Typically 6 digits. Allowed value range: 4 - 10
newInstanceSecret false string If present, this will be set as the TOTP’s instance secret. Needs to be Base32 encoded.
newInstancePeriodSeconds true integer How frequently a new OTP is generated, in seconds. Allowed value range: 30 - 300
newInstanceUserLabel true string A label to identify an end-user’s account that will appear in the authentication app. Typically a login ID.
newInstanceIssuer true string A label to identify the name of the organization or application that is issuing this TOTP instance. This will appear in the authentication app.
newInstanceHMACAlgorithm true enum A value indicating the HMAC algorithm to be used to calculate the OTP. Refer to WSDL for supported values.
newInstanceSetAsDefault false enum Sets this instance as the new default instance. Default: false

Sample updateUser() SOAP request: 

<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header/>
  <S:Body>
    <updateUser xmlns="http://ws.csd.rsa.com" xmlns:ns2="http://totp.mcf.safearea.com.au" xmlns:ns3="http://ws.kba.csd.rsa.com" xmlns:ns4="http://ws.oobgen.csd.rsa.com" xmlns:ns5="http://trx.csd.rsa.com" xmlns:ns6="http://ws.oobsms.csd.rsa.com" xmlns:ns7="http://ws.oobbio.csd.rsa.com" xmlns:ns8="http://ws.otpmobileapp.csd.rsa.com">
      <request>
        <identificationData>
          <orgName>TOTP</orgName>
          <userName>167659479</userName>
          <userStatus>VERIFIED</userStatus>
          <userType>PERSISTENT</userType>
        </identificationData>
        <messageHeader>
          <apiType>DIRECT_SOAP_API</apiType>
          <requestType>UPDATEUSER</requestType>
          <version>7.0</version>
        </messageHeader>
        <securityHeader>
          <callerCredential>*****</callerCredential>
          <callerId>test</callerId>
          <method>PASSWORD</method>
        </securityHeader>
        <credentialManagementRequestList>
          <acspManagementRequestData>
            <payload xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:TOTPManagementRequest">
              <ns2:provisionNewInstance>true</ns2:provisionNewInstance>
              <ns2:newDeviceName>Mike's phone</ns2:newDeviceName>
              <ns2:newInstanceDigits>6</ns2:newInstanceDigits>
              <ns2:newInstancePeriodSeconds>30</ns2:newInstancePeriodSeconds>
              <ns2:newInstanceUserLabel>167659479</ns2:newInstanceUserLabel>
              <ns2:newInstanceIssuer>SafeArea</ns2:newInstanceIssuer>
              <ns2:newInstanceHMACAlgorithm>SHA1</ns2:newInstanceHMACAlgorithm>
              <ns2:correlationId>93044980380-34243274837-324734832</ns2:correlationId>
            </payload>
          </acspManagementRequestData>
        </credentialManagementRequestList>
      </request>
    </updateUser>
  </S:Body>
</S:Envelope>

Sample response:

SOAP element Always present? Type Description
resultCode Yes string Value will be set to NEW_INSTANCE_PROVISIONED is successful. Other values indicate failure.
revisionId Yes string
newInstanceQRCode Yes, if success string A base64 encoded QR code to be displayed to the end-user in order to provision the TOTP record in the mobile application. The QR code includes the TOTP secret.
newInstanceSecret Yes, if success string The TOTP instance base32 encoded secret.
newInstanceUniqueId Yes, if success string The uniqueId assigned to the new TOTP instance.
TOTPInstance Yes complex type, repeated An sequence of complex object listing the runtime configuration and current status of TOTP instances provisioned to the end-user. 
<?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header/>
  <soapenv:Body>
    <ns1:updateUserResponse xmlns:ns1="http://ws.csd.rsa.com">
      <ns1:updateUserReturn xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns1:UpdateUserResponse">
        <ns1:identificationData>
          <ns1:delegated>false</ns1:delegated>
          <ns1:orgName>TOTP</ns1:orgName>
          <ns1:transactionId>4ff7-:52d5b866981:be232101-_TRX</ns1:transactionId>
          <ns1:userName>295010659</ns1:userName>
          <ns1:userStatus>VERIFIED</ns1:userStatus>
          <ns1:userType>PERSISTENT</ns1:userType>
        </ns1:identificationData>
        <ns1:messageHeader>
          <ns1:apiType>DIRECT_SOAP_API</ns1:apiType>
          <ns1:requestType>UPDATEUSER</ns1:requestType>
          <ns1:timeStamp>2023-07-18T01:16:34.629Z</ns1:timeStamp>
          <ns1:version>7.0</ns1:version>
        </ns1:messageHeader>
        <ns1:statusHeader>
          <ns1:reasonCode>0</ns1:reasonCode>
          <ns1:reasonDescription>Operations were completed successfully

</ns1:reasonDescription>
          <ns1:statusCode>200</ns1:statusCode>
        </ns1:statusHeader>
        <ns1:credentialManagementResponseList xsi:type="ns1:CredentialManagementResponseList">
          <ns1:acspManagementResponseData>
            <ns1:acspAccountId>295010659@TOTP</ns1:acspAccountId>
            <ns1:callStatus>
              <ns1:statusCode>SUCCESS</ns1:statusCode>
              <ns1:statusDescription>TOTP Instance ZQlTjS6K created</ns1:statusDescription>
            </ns1:callStatus>
            <ns1:payload xmlns:ns2="http://totp.mcf.safearea.com.au" xsi:type="ns2:TOTPManagementResponse">
              <ns2:resultCode>NEW_INSTANCE_PROVISIONED</ns2:resultCode>
              <ns2:newInstanceQRCode>iVBORw0KGgoAAAANSUhEUgAAAMgAAADIAQAAAACFI5MzAAAB8ElEQVR42u2Y3UpEMQyEA32tQl49&#13;
kNcqxJnpHl0vvEsuFIuelX4LbZLJz9Hqp2X/5PeSMFthqzL29rOXNgZI4keUm16xUnv9BH9jAb5O&#13;
T8EhAluzDmytHCRnnYccnyJVusDZ2gN593UfkRPf1zft9BGtTKgDMoRM8nsutJHwWHzCq1AIHmc/&#13;
d+slkOCmN/c2xu2YmQ8Q5hIOtu0w85VaOUAgP94gNlgFfu+jn8CXihwMxSe/6DVBcLQxs0qQ33lF&#13;
rpdQ4xsEMdtML94mB0hxs7DtAYVs1r+zJgikyM2AIBc/HU4eIMkihNqXPJ1BQ6mYIJL4YY1A4Kh7&#13;
yD4HCM9eSi1jAM2/FN9KWITgRdmrMrH9FblewtwK9XNewm/jmCA0FYMDQ6ckZg5MENpHuXP72M2u&#13;
AaKmlCrh8Ck6B4vsBKHAYS1gqNIuGtpPSmODREI9LiZ0DhCGzJTDh3BL+SOE6aR5TjNQcOqaIK5R&#13;
ge0JpVyV9rG0lcijxc24k1AOkWdMRYGQQ+nZAYKUuqqgSnC6ZvABwsW5jp3JWZxgug8QDsBqSpL7&#13;
Yo69Td59RBM+Wzo31aaeyDWT+waWzzysnjFEWMzV+VRtPytsO+FMZyx6rOLHwyeI3sBYZO+kwius&#13;
AXLfwI6q+b1OvSmxj/z/r+aPkQ+u8w+o80gNYAAAAABJRU5ErkJggg==</ns2:newInstanceQRCode>
              <ns2:newInstanceSecret>4MHIOSRF66VAGWQUAPFEJNSG5ETNRP6YZW373CRPKOJ5Y2A4SWUQ====</ns2:newInstanceSecret>
              <ns2:newInstanceUniqueId>ZQlTjS6K</ns2:newInstanceUniqueId>
              <ns2:revisionId>1</ns2:revisionId>
              <ns2:TOTPInstance>
                <ns2:digits>6</ns2:digits>
                <ns2:intervalSeconds>30</ns2:intervalSeconds>
                <ns2:uniqueID>ZQlTjS6K</ns2:uniqueID>
                <ns2:deviceName>Mike's phone</ns2:deviceName>
                <ns2:issuedTimeStamp>2023-07-18T11:16:34.757+10:00</ns2:issuedTimeStamp>
                <ns2:remainingAttempts>3</ns2:remainingAttempts>
                <ns2:hmacAlgorithm>SHA1</ns2:hmacAlgorithm>
                <ns2:status>PROVISIONED</ns2:status>
              </ns2:TOTPInstance>
            </ns1:payload>
          </ns1:acspManagementResponseData>
        </ns1:credentialManagementResponseList>
      </ns1:updateUserReturn>
    </ns1:updateUserResponse>
  </soapenv:Body>
</soapenv:Envelope>