Step 2 CA Auth ID PKI Authentication

CA Auth ID PKI is based on challenge response authentication. The CA Auth ID PKI Client first fetches the challenge from CA Strong Authentication Server, signs it, and then sends a request to CA Strong Authentication Server to verify the signed challenge.
aa813test
2112722
CA Auth ID PKI is based on challenge response authentication. The CA Auth ID PKI Client first fetches the challenge from CA Strong Authentication Server, signs it, and then sends a request to CA Strong Authentication 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 CA Auth ID 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 CA Strong Authentication Server. 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.
additionalInput/pairs
No
CA Strong Authentication’s additionalInput element enables you to set additional inputs if you want to augment CA Strong Authentication’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 CA Strong Authentication 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 CA Auth ID PKI Client by using user’s CA Auth ID PKI password.
tokenType
No
The type of authentication token that is expected from CA Strong Authentication Server after successful authentication. See "Verifying the Authentication Tokens" for more information.
additionalInput/pairs
No
CA Strong Authentication’s additionalInput element enables you to set additional inputs if you want to augment CA Strong Authentication’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 CA Strong Authentication 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 CA Auth ID PKI authentication:
  1. (
    Optional
    ) Include the authentication and authorization details in the SOAP header or in the additionalInput element of the GetArcotIDChallenge operation. See "Managing Web Services Security" for more information on these details.
  2. Use GetArcotIDChallengeRequestMessage and construct the input message.
  3. (
    Optional
    ) If you are implementing a plug-in, then invoke the additionalInput element type to fill the additional input.
  4. Invoke the GetArcotIDChallenge operation of the ArcotWebFortAuthSvc service to retrieve the challenge from CA Strong Authentication Server.
    This operation returns GetArcotIDChallengeResponseMessage, which has the transaction details and also the challenge from the server.
  5. The challenge is sent to the end user through HTML Page.
  6. Invoke the CA Auth ID PKI Client-side method, SignChallengeEx() to sign the challenge.
    The application collects the CA Auth ID PKI password, and the challenge is signed by the CA Auth ID PKI Client using the CA Auth ID PKI password.
  7. (
    Optional
    ) Include the authentication and authorization details in the SOAP header or in the additionalInput element of the VerifyArcotIDSignedChallenge operation. See "Managing Web Services Security" for more information on these details.
  8. Use VerifySignedChallengeRequestMessage and construct the input message.
  9. (
    Optional
    ) If you are implementing a plug-in, then invoke the additionalInput element type to fill the additional input.
  10. 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 CA Auth ID 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 the section, "Error Codes" for more information on the SOAP error messages.
 
Element
 
 
Description
 
challenge
Challenge returned by CA Strong Authentication Server.
transactionDetails
Contains the following transaction details:
message
A string that defines the status of the operation.
reasoncode
Unique code that is sent by CA Strong Authentication Server if the operation fails.
responseCode
Unique code that is sent by CA Strong Authentication Server if the operation fails.
transactionID
Unique identifier of the transaction.
additionalOutput
The output for the additionalInput that was passed to CA Strong Authentication 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 the section, "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 CA Strong Authentication Server after successful authentication.
tokenType
The type of authentication token that is returned by CA Strong Authentication 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 CA Strong Authentication Server if the operation fails.
responseCode
Unique code that is sent by CA Strong Authentication Server if the operation fails.
transactionID
Unique identifier of the transaction.
additionalOutput
The output for the additionalInput that was passed to CA Strong Authentication Server.