Step 2: ArcotID PKI Authentication

CA Strong Authentication Web Services Guide › Authenticating Users › ArcotID PKI Authentication › Step 2: ArcotID PKI Authentication

Step 2: ArcotID PKI Authentication

ArcotID PKI is based on challenge response authentication. The ArcotID PKI Client first fetches the challenge from AuthMinder Server, signs it, and then sends a request to AuthMinder Server to verify the signed challenge.

This section walks you through:

Preparing Request Messages
Invoking the Web Service
Interpreting Response Messages

Preparing Request Messages

For ArcotID PKI authentication, you must prepare the following request messages:

Fetching Challenge
Verifying Signed Challenge

Fetching Challenge

The GetArcotIDChallengeRequestMessage is used to fetch the challenge from AuthMinder Server. The following table lists the elements of this message:

Element

Mandatory

Description

clientTxnId

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

additionalInput/pairs

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.

Verifying Signed Challenge

The VerifySignedChallengeRequestMessage is used to verify the signed challenge. The following table lists the elements of this message:

Element	Mandatory	Description
clientTxnId	No	Specifies the unique transaction identifier that the calling application can include. This identifier helps in tracking the related transactions.
orgName	No	The organization name to which the user belongs to.
signedChallenge	Yes	The challenge that is signed by the ArcotID PKI Client by using user’s ArcotID PKI password.
tokenType	No	The type of authentication token that is expected from AuthMinder Server after successful authentication. See "Verifying the Authentication Tokens" for more information.
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.

Invoking the Web Service

To perform ArcotID PKI authentication:

(Optional) Include the authentication and authorization details in the SOAP header or in the additionalInput element of the GetArcotIDChallenge operation. See chapter, "Managing Web Services Security" for more information on these details.
Use GetArcotIDChallengeRequestMessage and construct the input message.
(Optional) If you are implementing a plug-in, then invoke the additionalInput element type to fill the additional input.
Invoke the GetArcotIDChallenge operation of the ArcotWebFortAuthSvc service to retrieve the challenge from AuthMinder Server.
This operation returns GetArcotIDChallengeResponseMessage, which has the transaction details and also the challenge from the server.
The challenge is sent to the end user through HTML Page.
Invoke the ArcotID PKI Client-side method, SignChallengeEx() to sign the challenge.
The application collects the ArcotID PKI password, and the challenge is signed by the ArcotID PKI Client using the ArcotID PKI password.
(Optional) Include the authentication and authorization details in the SOAP header or in the additionalInput element of the VerifyArcotIDSignedChallenge operation. See chapter, "Managing Web Services Security" for more information on these details.
Use VerifySignedChallengeRequestMessage and construct the input message.
(Optional) If you are implementing a plug-in, then invoke the additionalInput element type to fill the additional input.
Use VerifyArcotIDSignedChallenge operation of the ArcotWebFortAuthSvc service to verify the signed challenge. Optionally, you can also specify the token type that must be returned to the user after successful authentication by using the tokenTpe element.
This operation returns an instance of the VerifySignedChallengeResponseMessage, which provides the transaction details, credential details, and token information.

Interpreting Response Messages

Following are the response messages that are returned as part of ArcotID PKI authentication:

Fetch Challenge Response Message
Verify Signed Challenge Response Message

Fetch Challenge Response Message

For successful transactions, the response message, GetArcotIDChallengeResponseMessage 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
challenge	Challenge returned by AuthMinder Server.
transactionDetails	Contains the following transaction details: 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.

Element

Description

challenge

Challenge returned by AuthMinder Server.

transactionDetails

Contains the following transaction details:

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.

Verify Signed Challenge Response Message

For successful transactions, the response message, VerifySignedChallengeResponseMessage 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.

Method	Description
userName	The name of the authenticating user.
orgName	The organization to which the user belongs to.
authToken	The authentication token returned by AuthMinder Server after successful authentication.
tokenType	The type of authentication token that is returned by AuthMinder Server after successful authentication. See "Verifying the Authentication Tokens" for more information.
daysLeftToExpire	The number of days after which the credential expires.
status	The status of the credential.
remainingUsageCount	The number of times the credential can be used.
createTime	The time when the credential was created.
lastUpdatedTime	The time when the credential was updated last time.
validityStartTime	The date from when the credential is valid.
validityEndTime	The date after which the credential expires.
disableStartTime	The time when the credential has to be disabled.
disableEndTime	The time when the disabled credential has to be enabled.
numberOfFailedAuthAttempts	The total number of failed authentication attempts for the user.
lastSuccessAuthAttemptTime	The time when the last authentication attempt succeeded.
lastFailedAuthAttemptTime	The time when the last authentication attempt failed.
profileName	The profile name with which the credential was created.
profileVersion	The version number of the profile.
notes	The custom attributes that are set for the credential.
transactionDetails	Contains the following transaction details: 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.