Previous Topic: Assigning Credentials to UsersNext Topic: Fetching OATH Tokens

CA AuthMinder Web Services Guide › Performing Bulk Operations › Uploading OATH Tokens

Uploading OATH Tokens

This section walks you through the following topics for uploading the OATH tokens in bulk:

Preparing the Request Message

The UplodaOATHTokensRequestMessage is used to bulk upload the OATH tokens in the AuthMinder database.The following table lists the elements of this request message.

Element

Mandatory

Description

Common Elements

clientTxId

No

The unique transaction identifier that the calling application can include. This identifier helps in tracking the related transactions.

additionalInput/pairs

No

AuthMinder’s additionalInput element enables you to set additional inputs if you want to augment AuthMinder’s authentication capability by specifying additional information. In such cases, you need to set the extra information in name-value pairs.

  • name (The name with which you want to create the key pair.)
  • value (The corresponding value for name.)

    Note: You can add more than one of these elements.

Some of the pre-defined additional input parameters include:

  • AR_WF_LOCALE_ID
    Specifies the locale that AuthMinder will use while returning the messages back to your calling application.
  • AR_WF_CALLER_ID
    This is useful in tracking transactions. You can use session ID or client transaction ID (clientTxnId) for specifying this information.

Common Key Elements

orgDetails/orgName

No

Indicates the name of the organization for which you want to upload the OATH tokens.

orgDetails/isGlobal

No

Indicates whether you want to apply the OATH tokens at the global level. If you choose this option, then the OATH tokens will be available to all the organizations present in the system.

remark

No

A text message to identify the OATH tokens.

key

Yes

The key that is used to generate the OTP.

OATH Token (keyContainer) Elements

Note: You can pass the OATH token information using the following elements or include this information in an XML file and upload that file using the "inputXml" element.

version

Yes

The version of the schema that defines the OATH token information. The supported value for this element is 1.0.

EncryptionMethod/ algorithm

Yes

The encryption method that is used to encrypt the sensitive

information. For example, the Secret element.

EncryptionMethod/IV

Yes

Base64-encoded value of the Initialization Vector that is used in the encryption scheme. This is required only for "AES128-CBC" among other supported algorithms.

TokenInfo/Manufacturer

No

The manufacturer information of the OATH token.

TokenInfo/SerialNo

No

The unique serial number of the OATH token.

TokenInfo/Model

No

The unique model number that provides information about the make of the OATH token.

TokenInfo/AdditionalInfo

No

Extra information that you want to set for the OATH tokens. This information is set in name-value pairs.

  • Name
    Indicates the name with which you want to create the key pair.
  • Value
    Indicates the corresponding value for the name.

Key/KeyAlgorithm

Yes

The algorithm that is used to generate the OTP. The supported values are:

  • HOTP: Indicates that the event-based OTPs are supported.
  • TOTP: Indicates that the time-based OTPs are supported.

Key/KeyId

Yes

The unique identifier of the token.

Key/OTPFormat/Length

Yes

Indicates the character length of the OTPs that are generated using the OATH token.

Key/Secret

Yes

The shared secret that is used to generate OTPs.

Key/Counter

No

The counter that is used to generate OTPs in case of the HOTPs. This counter defines the number of times the user can use their OTP.

Key/Time

No

The time (in seconds) to start counting time steps in case of TOTPs.

Key/TimeInterval

No

The time-step window that is used to generate TOTPs. OTPs generated within a window are same.

This value is in seconds.

XML Information

inputXml

No

The XML file that defines the key container for One Time Passwords that have to be issued by AuthMinder Server.

Invoking the Web Service

To upload OATH tokens for users in bulk:

  1. (Optional) Include the authentication and authorization details in the SOAP header or in the additionalInput element of the UploadOATHTokens operation. See chapter, "Managing Web Services Security" for more information on the header elements.
  2. (Optional) If you are implementing a plug-in, then invoke the additionalInput element type to fill the additional input.

    This type provides the additional information that is set as a name-value pair.

  3. Use UploadOATHTokensRequestMessage and construct the input message by using the details obtained in preceding steps.
  4. Invoke the UploadOATHTokens operation of the ArcotWebFortBulkOperationsSvc service to upload the OATH tokens.

    This operation returns an instance of the UploadOATHTokensResponseMessage that includes the transaction details and batch identifier.

Interpreting the Response Message

For successful transactions, the response message, UploadOATHTokenResponse returns the elements explained in the following table. These elements are included in the SOAP body. If there are any errors, then the Fault response is included in the SOAP body. See appendix, "Error Codes" for more information on the SOAP error messages.

Element

Description

message

A string that defines the status of the operation.

reasonCode

Unique code that is sent by AuthMinder Server if the operation fails.

responseCode

Unique code that is sent by AuthMinder Server if the operation fails.

transactionID

Unique identifier of the transaction.

additionalOutput

The output for the additionalInput that was passed to AuthMinder Server.

batchID

The unique identifier that helps to identify the batch of the uploaded token.