Learn how to configure app credentials.
Note: This topic relates to setting up managing app security within the platform. For detailed information about how to set up your app to authenticate with an API hosted on the platform, refer to App Security Options and Setup.
When your app sends messages to an API, your app's credentials identify it as the sender of the message. Very few APIs accept anonymous messages; in general, you'll need to set identify your app with every message.
As part of setting up your app, you must set up your app security on the App Details page, following these high-level steps (more details provided below):
There are several choices available to you in terms of security configuration for your app. You'll need to make sure you choose a security mechanism that's acceptable for the API or APIs you want your app to use.
The choices are:
For more detailed information about application security options, refer to App Security Options and Setup.
Each API is pre-configured as follows:
The credential approach configured in the app must match the protocol supported by the API as defined in these policies. Review the API documentation to verify the supported protocols.
Configure Security Credentials:
To authenticate your app when placing API calls, you must include your App ID and either a Shared Secret or your Public Key for PKI-based authentication (in the form of a CER or CSR).
The Security section of the App Details page includes the Show Keys function that displays the Shared Secret and Public Key options for generating or importing the credentials required to authenticate your app in the sandbox or production environments. When deciding on the type of security credentials you'll use for your app, it's a good idea to review the API documentation for APIs you'll want your app to use, to verify what the API supports and any requirements it might have.
When an app is initially created using the Add New App function, a shared secret is either provided, or is generated automatically. You can view the Shared Secret in the App Details > Security section by clicking Show Keys and selecting Click to View. You can use the Regenerate Key option to issue a new shared secret.
Note: Depending on the platform settings specified by your Administrator, the shared secret displayed on the App Details page might be encrypted. If the shared secret is encrypted and you need the actual value, you can decrypt it using the app's private key.
If you would like to use PKI-based encryption, you can use the Public Key option. The Import Credentials function allows you to upload a Certificate Signing Request (CSR) with your public key embedded or an X.509 Certificate (CER).
If you are using OAuth 1.0a and the Authentication Code and Resource Owner Password Credentials grant, or OAuth 2.0 and the Authentication Code and Implicit grant, you must specify a Redirect URL and Application Type, then configure an authorization screen. This task is performed in addition to configuring security credentials and is optional based on your requirements.
All settings relating to OAuth for the app are set up on the app's OAuth Profile page. See App OAuth Profile.
Once you've created your app, you can manage app security via the Security section of the App Details page.
By default, only the App ID is displayed. Clicking Show Keys provides access to multiple buttons, allowing you to complete the following activities relating to your app's security:
When the buttons are visible, you can click Hide Keys to collapse the display again.
If you have an app that you have defined on another system that includes an App ID or Shared Secret you can transfer it to the platform based on the following scenarios:
When you register your app, you have the option to specify an App Runtime ID and Shared Secret. If you do not specify values, they are generated for you.
These two values are used to identify your app when using the platform.
The Shared Secret is a binary hashed value known only to you and to the platform. In the Security Credentials section of the App Details page you'll see an option to view and manage your app's Shared Secret.
The Shared Secret approach follows the WS-Security digest authentication mechanism.
When generated by the platform for the app, the Shared Secret is a 40-character alphanumeric value. An example is shown below.
1008877afabf32efb31f9c974dbeaa688bed0769
When you initially create an app using the Add a New App function, either you provide a value for the shared secret or it is automatically generated. If for any reason it becomes necessary, you can regenerate the shared secret later.
Note: Depending on the platform settings specified by your Administrator, the shared secret displayed on the App Details page might be encrypted. If the shared secret is encrypted and you need the actual value, you can decrypt it using the app's private key.
Note: Depending on the platform settings specified by your Administrator, the shared secret displayed on the App Details page might be encrypted. You can decrypt it using the app's private key.
If the version of the platform that you're using is set to display the shared secret as an encrypted value, you'll need to decrypt to get your app's actual shared secret value so you can use it when sending request messages to platform APIs.
If you uploaded a certificate/CSR for your app, the platform uses your app's public key to encrypt the plain text shared secret. You can then use your app's private key to decrypt and arrive at the plain text key.
It's important that you make sure you use the private key that corresponds to your app's public key that was uploaded to the platform. If the keys don't match, decryption will not give you the correct plain text value, or will fail completely.
If you have any doubt that the keys match, there are a couple of things you could do:
The approach you use to decrypting the encrypted shared secret value will depend on the tools and technologies you're using for your app. Basically you'll need to accomplish these steps:
Below is an example of an approach that would work if you have access to the Java runtime environment.
You can also use the command-line decryption tool. For more information, see To use the command-line decryption tool to decrypt the shared secret.
import java.io.FileInputStream;
import java.security.KeyStore;
import java.security.PrivateKey;
import javax.crypto.Cipher;
/**
* Akana, Inc. Copyright (C) 2000-2015, All rights reserved
*
* This software is the confidential and proprietary information of Akana, Inc.
* and is subject to copyright protection under laws of the United States of America and
* other countries. The use of this software must be in accordance with the license
* agreement terms you entered into with Akana, Inc.
*/
/**
* Copyright (c) 2015, Akana, Inc. All rights reserved.
*/
public class AppSharedSecretDecryptionTest {
/**
* @param args
*/
public static void main(String[] args) {
try {
// Copy encrypted shared secret from portal's App details page using View Shared Secret button "Click TO View" button
String encryptedSharedSecret = "--copy--encrypted--shared--secret--from--portal--here";
// base64 decode to take away encoding cover to get encrypted bytes
byte[] encryptedSharedSecretBytes = org.apache.commons.codec.binary.Base64.decodeBase64(encryptedSharedSecret);
// make sure you are using the private key that corresponds to the certificate uploaded for the app
KeyStore ks = KeyStore.getInstance("PKCS12");
FileInputStream fis = new FileInputStream("/path/to/keystore");
try {
ks.load(fis, "keystore-password".toCharArray());
} finally {
fis.close();
}
PrivateKey pvtkey = (PrivateKey)ks.getKey("key-alias", "key-password".toCharArray());
// Shared Secret was encrypted with RSA algorithm with PKCS1 padding.
Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-1AndMGF1Padding");
cipher.init(Cipher.DECRYPT_MODE, pvtkey);
// Decode
byte[] sharedSecret = cipher.doFinal(encryptedSharedSecretBytes);
// prints the shared secret on screen. Use this shared secret in the app runtime
System.out.println("Shared Secret = " + new String(sharedSecret));
} catch (Throwable t) {
t.printStackTrace();
}
}
}
Note: If there is no certificate/CSR for your app, and the platform is set to display the shared secret as an encrypted value, you'll need to contact your Administrator to get the shared secret value.
If the version of the platform you are using is set to display your app's shared secret value in an encrypted format, you'll need to decrypt it so that you can use the shared secret when sending request messages to platform APIs.
The platform includes a tool that you can run at the command line to decrypt the shared secret, if you have Java installed. Follow the instructions below.
java -jar AppSharedSecretDecryptionTest.jar project.properties
For general information about the decryption process, refer to How do I decrypt an encrypted shared secret? above.
Before you add an app to the platform, review the following rules for generating an App ID or Shared Secret to determine the best approach for adding and managing your apps.
App ID:
Shared Secret:
If you use the Public Key option, you must import an existing X.509 Certificate (CER) or Certificate Signing Request (CSR). Usage of either public key option is based on your requirements. The Tenant can be configured with an internal Certificate Authority, and could also be configured with a set of Trusted CA Certificates apart from the internal Certificate Authority.
The following rules apply:
Prerequisites:
Based on the established public key strategy for your platform at least one of the following Public Key options must be established on the Tenant before you can successfully import a Certificate Signing Request (CSR) or X.509 Certificate (CER).
Configuring an internal Platform Certificate Authority is a post installation task that is performed by the Site Administrator. In most cases, a formal CA (for example, VeriSign) that aligns with the security policy requirements is uploaded, in addition to any Trusted CA Certificates that may be required.
If you receive an error message indicating that the X.509 Certificate or Certificate Signing Request (CSR) you are attempting to import is not trusted or that a Certificate Authority does not exist.
Import Certificate Signing Request (CSR):
X.509 Certificates (CER):
A Certificate Signing Request (CSR) is a file that includes encoded information generated by a web server. It is sent from an applicant to Certificate Authority to request a digital certificate. The CSR contains information identifying the applicant and the public key chosen by the applicant. Before creating a CSR, the applicant first generates a key pair, keeping the private key secret. The corresponding private key is not included in the CSR, but is used to digitally sign the entire request.
A CSR file typically has a .CSR extension but can have other extensions based on the source application that generated the file. The Tenant supports the PEM (which is a BASE64 encoded PKCS10) for Certificate Signing Requests.
In the platform, a CSR is used to send a request to the Certificate Authority stored on the Tenant to request an X.509 Certificate.
The Tenant must be configured with a Certificate Authority prior to importing a CSR. This task is performed by the Site Administrator.
A Trusted Certificate Authority (CA) is a third party identity that is qualified with a specified level of trust. Trusted CA Certificates are used when an identity is being validated as the entity it claims to be. Certificates imported into Tenant must be issued by a Trusted CA Authority.
Trusted CA Certificates must be configured prior to importing X.509 certificates for platform apps. This task is performed by the Site Administrator.
The platform Certificate Authority and Trusted CA Certificate files are stored on the Tenant. The Tenant is a distinct developer portal and community that is logical separated from any other communities that may be hosted in the same product instance. The Tenant is managed by the Site Administrator.
There are a variety of different tools you can you can use to generate a Certificate Signing Request (CSR). For example, Keytool and OpenSSL are popular CSR generation tools.
In the context of the platform the process is as follows:
For your app's credentials, you can import either a certificate signing request (CSR) or an X.509 certificate (CER).
If you import a CSR file, the platform uses its internal Certificate Authority to create the CER from the request.
For your app's credentials, you can import either a certificate signing request (CSR) or an X.509 certificate (CER).
You can modify your app's credentials as needed. Remember to enter some meaningful comment regarding why you are changing the credentials.
If necessary, you can remove the credentials for your app. You'll need to provide information about why you are making the change.
Later, you can use the Import Credentials function to import a new Certificate Signing Request (CSR) or certificate (CER). See How do I import a certificate signing request?
After the Certificate Signing Request is imported and the certificate is generated, you can download the app certificate.