• Prudential APIs are private APIs, and each API call needs to be authenticated by an approved authentication method.
• To call an API, the developer must create an app in the API portal and subscribe to the API they want access to.
• That subscription request would be reviewed by the API Owner, and if approved, then the credentials for that app can be used to call the API.
• All developers must use one of the following authentication methods to access a Prudential provided API.

This is an authentication type where the client application presents a X.509 certificate when making the API call. The certificate needs to be either of the two options:-

1. A client-owned certificate can be uploaded, or
2. A Prudential certificate can be generated while creating the app.

Certificate needs to be unique for each application. Certificates provided by developers must not have a validity period greater than 397 days and must be issued from a Trusted Certificate Authority.

Note: if a certificate is shared by multiple applications, please use "Basic Auth+X.509 Certs" authentication

The below table provides details on the type of certificate required.

For details on the Client Certificate Expiry Notifications, please refer to the following link Certificate Expiry

This is an authentication type where a client application needs to present a consumer key/consumer secret(Basic Authentication) that is generated by the API Portal in combination with a certificate that is either generated or uploaded by the App Owner, and this combination uniquely identifies the APP. Apps that use Basic Authentication + X.509 Client Certificates can use the X.509 Client Certificates across multiple applications.

Basic Authentication is a simple form of authentication where the consumer key and consumer secret are combined with a single colon(consumerKey:consumerSecret). The resulting string is Base64 encoded and then prepended with "Basic" and placed in the Authorization header. Consumer Keys and Secrets need to be rotated annually. For details on Key Rotation, please refer to the following link, Key Rotation

An access token is requied to interact with Prudential hosted APIs. Developers must authenticate against a supported authorization server first to retrieve an access token. Direct Authentication to APIs is not permitted.

(insert image here)

• The client requests an access token by authenticating using X.509 certificates with the authorization server.

The authorization server URLs are:

• The authorization server authenticates the client and validates the authorization grant, and if valid, issues an access token.
• The client makes a protected API request to the API server by presenting the access token.
• The API server validates the access token, and if valid, serves the request.

1. Request parameters to fetch Bearer Token

Dev/QA URL:

https://eapi-devcert.prudential.com/gbts/common/oauth/token

Authentication:

cert based (partner need to provide the cert to Prudential)

Query Parameter:

Name: grant_type, Value: client_credentials

Operation:

GET

2. Response from Bearer Token API

Status:

200/400 (Bad Data)/500 (Target system down)

Response body from 200 Success:

{
  "token_type": "Bearer",
  "access_token": "g4z1fYzLPbyJuNenjGAG9i(GfvlD)",
  "expires_in": 3599,
  "status": "approved"
}

This section provides guidelines and best practices on the secure handling of the API Consumer Secret values, as well as the Private Key of the X.509 Certificates, that are issued to the Applications.

The foundational rule for all other security controls is that the API Consumer Secret/Private Key values that are issued to applications must

• Remain private and confidential
• Be protected from unauthorized or unnecessary access

Application owners are expected to comply with the following guidelines:

• Protect the API Consumer Secret/Private Key values wherever they are stored (data-at-rest). Only store keys in secure locations.
• Change or rotate the API Consumer Secret/Private Key values on a regular basis (at least once a year).
• Protect the API Consumer Secret/Private Key values whenever they are being transmitted (data-in-motion) over the network. Only send over secure channels.
• Keep application identities unique and independent. Do not reuse credentials across applications.

Key storage guidelines for the API Consumer Secret/Private Key are as follows:

• Access Controls: Configuration files that store the API Consumer Secret/Private Key MUST have access controls in place such that files are secured from unauthorized access. Verify that access to files containing the credentials are restricted to the fewest number of people and components that are necessary.
• Encryption: Configuration files that store the API Consumer Secret/private key SHOULD be encrypted or password protected as an additional control.

The following are storage anti-patterns:

• Hard-coded Credentials: DO NOT store, embed, or "hard-code" the API Consumer Secret/private key in binaries or source code. Instead store the API Consumer Secret/private key outside of source code in a protected configuration file or an approved secrets manager or security vault.
• Public Repositories: DO NOT store the API Consumer Secret/private key in public repositories or alongside source code. Instead, store the API Consumer Secret/private key in a private repository, separated from source code.
• Security-by-Obscurity: DO NOT attempt to hide or obfuscate the API Consumer Secret/private key in binaries, source code, scripts, or web pages. If the API Consumer Secret/private key are made accessible to a client-side installed application, they MUST be considered compromised and MUST NOT be used for authentication.

Occasionally it may be required that the API Consumer Secret/Private Key be shared with other parties. Use the guidelines below when distributing (sharing) the API Consumer Secret/Private Key values to/with other parties:

• Encryption: The API Consumer Secret/Private Key SHOULD NOT be distributed "in the clear", instead, use some form of encryption to provide confidentiality.
• Password Protected: Password protected .zip file should be used for distribution.
• Traceability: Track who the credentials have been shared with.

The following are key distribution anti-patterns:

• Clear Text: DO NOT use any method or channel that sends the credentials in "clear text" (unencrypted).
• E-Mail: DO NOT send the API Consumer Secret/Private Key using e-mail: Email is not a secure communications channel, and the API Consumer Secret/Private Key will be stored allowing unauthorized or unnecessary access.
• IM or Teams: DO NOT share the API Consumer Secret/Private Key using IM or Teams. The credentials will be stored allowing unauthorized or unnecessary access.
• Community Posts: DO NOT share security credentials in community posts or support channels like Stack Overflow.
• Developer Tools: DO NOT share cURL commands or Postman configurations that contain the API Consumer Secret/Private Key values.
• Support: DO NOT share the API Consumer Secret/Private Key with support teams. Support teams should not ask for the API Consumer Secret/Private Key. If this is required, the credentials MUST be changed after the issue is resolved.
• Screen Shares: DO NOT share screens during group meetings or trouble-shooting sessions that contain the API Consumer Secret/Private Key.

Prudential standards mandate that the Consumer Key and the Consumer Secret are required to be rotated with a maximum expiration frequency of a year. The API portal supports both automatic and manual key rotation.

The following steps are followed for automatic key rotation:

• Upcoming Key Rotation Email (Day 1): This is the first step in the process. If an application is determined to have an upcoming key rotation, an email would be sent to the primary and secondary developer app owner letting them know that in 14 days, the app key will be rotated. Developer app owners don't need to do anything at this time.
• Clone Existing Developer Application (Day 14): After 14 days the key rotation tool will clone/copy the existing developer application. It will copy all of the existing application meta-data and attributes, but it will assign a new API Consumer Key and Secret. All existing API subscriptions will remain.
  • At this point there are two applications. The new/cloned application and the original application. The credentials (API Key and Secret) are both active and will continue to work, i.e., they can still be used to authenticate.
  • An email will be sent to the primary and secondary developer app owners notifying them of the key rotation occurrence and asking them to log into the API Developer Portal to retrieve the new credentials.
• Change Credentials (Days 14-27): Application Owners will have 14 days to change their API Consumer Keys and Secret to the new values.
  • The primary developer app owner should log into the API Developer Portal and retrieve the credentials (consumer key and secret) and start updating their clients with the new credentials.
  • During this two-week period, both the old and new developer application credentials will continue to work.
• Disable Original Developer Application (Day 28): After 14 days, the original developer application will have its credentials revoked/disabled. An email will be sent to the primary and secondary developer app owners notifying them the credentials for the original developer app were revoked. At this time any client using those credentials will have its API requests fail with a 401 error.
• Delete Original Developer Application (Day 42): 14 days after the original developer application has been disabled, it will be permanently deleted. Any API requests that use the old API Consumer Keys and Secret will fail.

As an Application Owner you can choose to manually rotate your API Consumer Key and Secret at any time using the "Rotate App" feature in the Apps tab of the API Developer Portal. Once you select the "Rotate App" button, the following process applies:

• Rotate App (Rotation-Date | Day 1): A new application with a new API Consumer Key and Secret is cloned/copied from the current application.
  • At this point there are two applications: 1) the new/cloned application and 2) the current/rotated application.
  • The credentials (API Consumer Key and Secret) for both applications are active and can be used to authenticate
  • The current application and it's associated API Consumer Key and Secret will remain active for 14 days from the Rotation-Date
• Change Credentials (Days 1-13): Application Owners will have 14 days from the Rotation-Date to change the API Consumer Keys and Secret to the new values.
  • All storage locations, files, and/or configuration times that reference the old credentials MUST be updated in the next 14 days. It is the responsibility of the application team to know where and how to make these updates
  • During this two week period, both the old and new application credentials will continue to work
• Disable Original Developer Application (Revoke-Date | Day 14): 14 days after the Rotation-Date, the original developer application will have its credentials revoked/disabled and the application will no longer be usable. At this time any client application that makes API requests using the old credentials will fail with a 401 error.
• Delete Original Developer Application (Delete-Date | Day 28): 14 days after the Revoke-Date, the original developer application will be permanently deleted.

The X.509 Client Certificates must not have a validity period greater than 397 days (13 months). Four reminder email notifications are sent out to the applications owners whose certificates are due to expire. The first reminder email is sent out 30 days before certificate expiry, while subsequent emails are sent out 15 days, 7 days, and 1 day before expiry.

The app owner would in these 30 days need to:

• Generate/upload a new certificate from the portal, without deleting the old certificate. An app can have up to 2 functioning certificates at any given time.
• Update the client to send the new certificate
• Manually delete the old certificate in the portal (recommended)

If the new certificate in not uploaded by the expiry date, the transactions start failing. The certificate expiry date cannot be extended under any circumstance.