Symantec VIP Integration Kit

PingFederate Authentication API support

You can use the PingFederate Authentication API to integrate the Symantec VIP IdP adapter into your application.

The PingFederate Authentication API provides access to the current state of the authentication flow as a user steps through the PingFederate authentication policy. Learn more in PingFederate Authentication API in the PingFederate documentation.

To integrate the Symantec VIP IdP adapter into your authentication flow, configure your application based on the information in this section.

You can also explore integrating the Symantec VIP IdP adapter into your application using the PingFederate Authentication API Explorer. Learn more in Exploring the Authentication API in the PingFederate documentation.

Models, objects, and error codes

When using the Symantec VIP integration kit through the PingFederate Authentication API, the adapter uses the following state models, action models, objects, and error codes:

State models
Status Request model Action Description

VIP_AUTHENTICATION_REQUIRED
username

The authenticating user’s username.

pushNotificationInfo

An object with data required to complete push notification.

If number matching is enabled, the user must enter the number displayed on their device.

VIPCredentialInfo

An object with details about the VIP credential.

  • initiatePushAuthentication

  • selectVIPCredential

  • checkSecurityCode

  • continue

To continue, the user must authenticate with a credential or approve a push notification.

VIP_CREDENTIAL_REQUIRED
username

The authenticating user’s username.

  • submitVIPCredential

  • continue

The user must submit a credential to complete the enrollment process.

VIP_CREDENTIAL_RESET_REQUIRED
username

The authenticating user’s username.

resettableVipCredentials

A list of VIP Credential Info objects with details about the resettable credentials.

  • resetVIPCredential

  • continue

The user must reset their credential to continue.

VIP_EMAIL_CREDENTIAL_REQUIRED
username

The authenticating user’s username.

  • submitEmailCredential

  • continue

The user must submit an email credential to complete the enrollment process.

VIP_EMAIL_CREDENTIAL_VERIFICATION_REQUIRED
username

The authenticating user’s username.

credentialId

The email credential ID.

credentialType

The type of credential that’s currently going through verification. This can be SMS, Email, or Voice.

errorMessage

An optional error message indicating the error encountered during validation, if applicable.

informationMessage

An optional message containing additional information about the error encountered during validation.

friendlyName

The friendly name of the added credential.

  • validateSecurityCode

  • continue

The user must verify their email credential to complete the enrollment process.

VIP_ENROLLMENT
username

The authenticating user’s username.

vipCredentials

A list of VIP Credential Info objects with details about the credential.

suppressAddCredentials

Indicates whether the user can add credentials.

enableAddingSMSCredential

Indicates whether the user can add an SMS credential.

enableAddingVoiceCredential

Indicates whether the user can add a voice credential.

enableAddingEmailCredential

Indicates whether the user can add an email credential.

  • addVIPCredential

  • continue

  • cancel

The user can either add a credential or continue to the authentication process.

VIP_SMS_CREDENTIAL_REQUIRED
username

The authenticating user’s username.

  • submitSMSCredential

  • continue

The user must submit an SMS credential to complete the enrollment process.

VIP_SMS_CREDENTIAL_VERIFICATION_REQUIRED
username

The authenticating user’s username.

credentialId

The SMS credential ID.

credentialType

The type of credential that’s currently going through verification. This can be SMS, Email, or Voice.

errorMessage

An optional error message indicating the error encountered during validation, if applicable.

informationMessage

An optional message containing additional information about the error encountered during validation.

friendlyName

The friendly name of the added credential.

  • validateSecurityCode

  • continue

The user must verify their SMS credential to complete the enrollment process.

VIP_VOICE_CREDENTIAL_REQUIRED
username

The authenticating user’s username.

  • submitVoiceCredential

  • continue

The user must submit a voice credential to complete the enrollment process.

VIP_VOICE_CREDENTIAL_VERIFICATION_REQUIRED
username

The authenticating user’s username.

credentialId

The voice credential ID.

credentialType

The type of credential that’s currently going through verification. This can be SMS, Email, or Voice.

errorMessage

An optional error message indicating the error encountered during validation, if applicable.

informationMessage

An optional message containing additional information about the error encountered during validation.

friendlyName

The friendly name of the added credential.

  • validateSecurityCode

  • continue

The user must verify their voice credential to complete the enrollment process.
Action models
Status Request model Action Description

initiatePushAuthentication

This action has no model.

This action has no errors.

Initiates push notification authentication.

selectVIPCredential
vipCredentialId

The credential ID to use.

type

The credential type. Possible values are STANDARD_OTP, SMS_OTP, EMAIL_OTP, AND VOICE_OTP.

  • Error: VALIDATION_ERROR

    ErrorDetail: INVALID_VIP_CREDENTIAL_ID: Credential ID isn’t valid.

    AUTHENTICATION_FAILED: Authentication failed.

Select the credential to use for authentication.

checkSecurityCode
securityCode

The security code.

type

The credential type. Possible values are STANDARD_OTP, SMS_OTP, EMAIL_OTP, AND VOICE_OTP.

  • Error: VALIDATION_ERROR

    ErrorDetail: AUTHENTICATION_FAILED: Failed to authenticate successfully with the given security code.

Validates the entered security code.

cancel

This action has no model.

This action has no errors.

Cancels the current authentication step.

submitVIPCredential
vipCredentialId

The credential ID.

securityCode

The security code.

  • Error: VALIDATION_ERROR

    ErrorDetail: SUBMIT_VIP_CREDENTIAL_ERROR: Error adding credential because of an incorrect security code.

Submit a security code to complete the enrollment process of the VIP credential type.

resetVIPCredential
vipCredentialId

The credential ID of the credential to be reset.

securityCode

A security code from the credential to be reset.

nextSecurityCode

The next security code from the credential to reset.

  • Error: VALIDATION_ERROR

    ErrorDetail: INVALID_VIP_CREDENTIAL_ID: Invalid credential ID was provided.

    RESET_VIP_CREDENTIAL_ERROR: Error encountered resetting credential.

Process with two consecutive security codes to reset the credential.

submitEmailCredential
credentialId

The new credential ID (email address) to add.

friendlyName

The friendly name of the email credential.

  • Error: VALIDATION_ERROR

    ErrorDetail: SUBMIT_EMAIL_CREDENTIAL_ERROR: Error adding email credential.

Enter your email credentials. An OTP will be sent to the provided email address.

When the OTP is presented back for verification, this completes the credential addition process.

validateSecurityCode
securityCode

A security code received by the new credential.

  • Error: VALIDATION_ERROR

    ErrorDetail: AUTHENTICATION_FAILED: Authentication failed.

Validate the received security code to prove device ownership and complete the credential addition process.

addVIPCredential
type

The credential type. Acceptable values are VIP Credential, SMS, VOICE, and Email.

If not specified, VIP Credential will be used as the default value.

  • Error: VALIDATION_ERROR

Initiate credential enrollment process.

continue

This action has no model.

This action has no errors.

Continues the current authentication flow.

submitSMSCredential
credentialId

The new credential ID (SMS mobile device number) to add.

friendlyName

The friendly name of the SMS credential.

  • Error: VALIDATION_ERROR

    ErrorDetail: SUBMIT_SMS_CREDENTIAL_ERROR: Error adding SMS credential.

Enter your mobile device number. An OTP will be sent to the provided SMS address.

When the OTP is presented back for verification, this completes the credential addition process.

submitVoiceCredential
credentialId

The new credential ID (voice mobile device number) to add.

friendlyName

The friendly name of the voice credential.

  • Error: VALIDATION_ERROR

    ErrorDetail: SUBMIT_VOICE_CREDENTIAL_ERROR: Error adding voice credential.

Enter your mobile device number. An OTP will be sent to the provided phone number through a voice call.

When the OTP is presented back for verification, this completes the credential addition process.

Objects

Push Notification Info object
Parameter Name Type Description

numberChallengeValue

String

If number matching is enabled, this is the number you must enter on the VIP app.

statusCode

String

The status code of the push notification request.

statusMessage

String

The status message of the push notification request.
VIP Credential Info object
Parameter Name Type Description

id

String

The credential ID.

maskedCredentialId

String

The masked credential ID for display purposes.

friendlyName

String

The credential’s friendly name.

type

String

The credential type. Possible values are:

  • STANDARD_OTP

  • SMS_OTP

  • EMAIL_OTP

  • VOICE_OTP

authenticationInvoked

Boolean

Indicates whether authentication with associated credentials has been initiated:

  • For SMS, voice, and email credentials this means Symantec VIP sent a security code using the respective channel.

  • For STANDARD_OTP credentials, use the code displayed within the app or approve the push notification if push was initiated for authentication.

pushEnabled

Boolean

Indicates whether the credential is push-enabled.

Error codes

If the call flow state hasn’t reached a dead end and the user can still authenticate with a device the PingFederate Authentication API returns an error code.

Top level error codes
Error code Message HTTP status

VALIDATION_ERROR

One or more validation errors occurred.

400

INVALID_ACTION_ID

A push notification was initiated with no underlying support from the credential.

400
Detail level error codes
Error code Message userMessageKey Parent code

INVALID_VIP_CREDENTIAL_ID

Credential ID isn’t valid.

vip.message.invalid.security.code

VALIDATION_ERROR

AUTHENTICATION_FAILED

Message varies based on the error status code returned by the VIP API.

Various message properties associated with vip.status.message.* keys

VALIDATION_ERROR

SUBMIT_EMAIL_CREDENTIAL_ERROR

Error adding an email credential.

VALIDATION_ERROR

SUBMIT_VIP_CREDENTIAL_ERROR

Error adding a credential.

VALIDATION_ERROR

RESET_VIP_CREDENTIAL_ERROR

Error resetting a credential.

VALIDATION_ERROR

SUBMIT_SMS_CREDENTIAL_ERROR

Error adding an SMS credential.

VALIDATION_ERROR

SUBMIT_VOICE_CREDENTIAL_ERROR

Error adding a voice credential.

VALIDATION_ERROR