External/adapter-based PKI bridge

External/adapter-based PKI bridge

The adapter-based PKI bridge is an included PKI bridge that can be used with user certificate authentication. The adapter-based PKI bridge is available with the com.worklight.core.auth.ext.UserCertificateAdapterBasedPKI class name, and is configured by adding parameters to the realm definition. An adapter is required for this PKI bridge to work, and must be uploaded before any user connects with this configuration. The adapter-based PKI bridge is useful if the PKI can be accessed with an adapter (such as a REST API).

Requirements for use

For the adapter-based PKI bridge, an adapter must be added in the console and the parameters for the bridge must be configured in the realm definition. The following example shows a realm definition for wl_userCertificateAuthRealm with the adapter-based PKI that uses an adapter called PKIAdapter:
<realm name="wl_userCertificateAuthRealm"
       loginModule="UserCertificateLoginModule">
  <className>com.worklight.core.auth.ext.UserCertificateAuthenticator</className>
  <parameter name="dependent-user-auth-realm"
             value="WASLTPARealm" />
  <parameter name="pki-bridge-class"
             value="com.worklight.core.auth.ext.UserCertificateAdapterBasedPKI" />
  <parameter name="adapter-pki-bridge-init-procedure"
             value="PKIAdapter.init" />
  <parameter name="adapter-pki-bridge-identity-validation-procedure"
             value="PKIAdapter.validateIdentity" />
  <parameter name="adapter-pki-bridge-csr-requirements-procedure"
             value="PKIAdapter.getCSRRequirements" />
  <parameter name="adapter-pki-bridge-csr-validation-procedure"
             value="PKIAdapter.validateCSR" />
  <parameter name="adapter-pki-bridge-certificate-generation-procedure"
             value="PKIAdapter.generateCertificate" />
  <parameter name="adapter-pki-bridge-identity-from-certificate-procedure"
             value="PKIAdapter.getIdentityFromCertificate" />
  <parameter name="adapter-pki-bridge-certificate-validation-procedure"
             value="PKIAdapter.validateCertificate" /> 
</realm>
Configuration parameters

The following adapter-based PKI bridge parameters are available.
adapter-pki-bridge-init-procedure

Required
An adapter procedure called to initialize the PKI bridge on each call. Requires a single parameter for the configuration available in the realm definition. The following example shows a sample value of this parameter:
{"adapter-pki-bridge-csr-validationprocedure":"
PKIBridgeAdapter.validateCSR","adapter-pki-bridge-identity-fromcertificate-
procedure":"PKIBridgeAdapter.identityFromCertificate","pkibridgeclass":"
com.worklight.core.auth.ext.UserCertificateAdapterBasedPKI","adapterpki-
bridge-identity-validationprocedure":"
PKIBridgeAdapter.identityVerify","adapter-pki-bridge-csrrequirements-
procedure":"PKIBridgeAdapter.csrRequirements","adapter-pkibridge-
certificate-generationprocedure":"
PKIBridgeAdapter.generateCertificate","adapter-pki-bridgecertificate-
validationprocedure":"
PKIBridgeAdapter.certificateVerify","adapter-pki-bridge-initprocedure":"
PKIBridgeAdapter.init","dependent-user-authrealm":"
WASLTPARealm"}
adapter-pki-bridge-identity-validation-procedure

Optional
An adapter procedure called that allows the adapter to determine whether the user identity from the dependent realm is allowed to generate a certificate. This procedure is optional. By default, the PKI bridge always returns YES. Requires a single userIdentity parameter. The following example shows a sample value of this parameter:
{"deviceId":"C146B473-DA25-46A7-8A79-E8CE5E9270EE","userIdentity":
{"userName":"user@ibm.com","attributes":
{"LtpaToken":"dHwRqHp61ukJCkEFBMRd6g63uV1bDg0rmGBU2cuBrinFp+7L7BVb
+4OebyIRMOoKLhHldLxj9JIPiWH4s16tHtNjddBxxbd9rdjZUgnicVY8+6GM8uTEwleRW
+lVzzwJX0Htvfa2iOQD9KAWLXkNHgneiELIANjAUxGsMzJGGg2K8LYYWeBhE0JGqJcb8WFFLYH4T5
Cgb9C+qXpre/KF/MNTrv2WQF9kWjPmMlPuT1Lh1tY9oSSqN20DNNZ8VcQ8p26po5yBMvtDMtn4/
EzfdhKYeTNFzQEmQpR66caQJlRV++m/
Oq4EiZBBzkOY6zpBVtmUzcH3D2xh5PYYVcFO8g=="},"displayName":""},"appId":"UserCert"}
The procedure must return an object with the following format:
{valid: "YES"}

Options for valid:

YES - The user is allowed to generate a certificate.

NO_USE_DEPENDENT_REALM_ONLY - The user is allowed to log in to the dependent realm, but is not allowed to generate a certificate.

NO - The user is not allowed to log in at all, and is not allowed to generate a certificate.

adapter-pki-bridge-csr-requirements-procedure

Optional
Build a set of requirements that must be in a CSR that the client generates. This procedure is optional. By default, the CSR requirements include the commonName that is equal to the user name from the dependent realm user identity. The procedure has a single parameter called userIdentity with the following format:
{"deviceId":"C146B473-DA25-46A7-8A79-E8CE5E9270EE","userIdentity":
{"userName":"user@ibm.com","attributes":
{"LtpaToken":"dHwRqHp61ukJCkEFBMRd6g63uV1bDg0rmGBU2cuBrinFp+7L7BVb
+4OebyIRMOoKLhHldLxj9JIPiWH4s16tHtNjddBxxbd9rdjZUgnicVY8+6GM8uTEwleRW
+lVzzwJX0Htvfa2iOQD9KAWLXkNHgneiELIANjAUxGsMzJGGg2K8LYYWeBhE0JGqJcb8WFFLYH4T5
Cgb9C+qXpre/KF/MNTrv2WQF9kWjPmMlPuT1Lh1tY9oSSqN20DNNZ8VcQ8p26po5yBMvtDMtn4/
EzfdhKYeTNFzQEmQpR66caQJlRV++m/
Oq4EiZBBzkOY6zpBVtmUzcH3D2xh5PYYVcFO8g=="},"displayName":""},"appId":"UserCert"}
This procedure must return a JSON object in the following format:
{ commonName: "user@ibm.com", additionalSubject: { "O": "IBM" }, additionalAttributes: {} }

commonName - This attribute is a required entry used as the CN attribute in the CSR. This value must match a user in the user registry of the application server.

additionalSubject - This attribute is a required JSON object containing key/value pairs for each additional attribute that must be in the subject of the CSR, such as O for organization. If no additional attributes are required, use an empty JSON object.

additionalAttributes - This attribute is a required JSON object containing key/value pairs for each additional attribute that must be included in the CSR. If no additional attributes are required, use an empty JSON object.

adapter-pki-bridge-csr-validation-procedure

Optional
This procedure is called after a client sends a CSR that follows a request. It is responsible for ensuring that all of the CSR attributes that were requested in the requirements exist in the CSR. This procedure is optional. By default, the PKI bridge always returns YES. The procedure has a single parameter csr containing a JSON object with the following format:
{"csr":"MIICXzCCAUcCADAbMRkwFwYDVQQDFBBsaXpldEB1cy5pYm0uY29tMIIBIjANBgkqhkiG9w0
BAQEFAAOCAQ8AMIIBCgKCAQEAt9A8WLa0NqAjizn9ccZFUPBLCCGEBCUQAgNPZKcf3wW2LhQ75
MEMfLyahZvqSBFd7IMMstRrpKiobx6PTGiMCkNB7lOzNa88tCHv81+wHaTIu2QggqpBMFPhvBdTbS
93pafEQ7kXEGBk+uU7vwalUIHQyQT1+9ZaiH4ssf8Ybi
+qYmGrOH4CjvO7h93l0sAyOOWqcGBnOCcb1+YJP9F/
EyHLNfdr1FTDAAp0ERtUqVMDeJIRxscFnqZ1GG0rXCEJqAl3IHvrn6BiLrmQOxA5oE
+Lk4ry6cizw1yxYY1mWZq9eTCQQbMGBS/Aa+4KBOG3NCCL
+e4YKN2RJ0m2bcHRswIDAQABoAAwDQYJKoZIhvcNAQEFBQADggEBAHHOJbrGBCZCiDi3hXzVzji7
1euKMf8IUjGe+sfr+Sy5sfx9k
+icvKixImHCxSy0PeKp4QICSgfZxk2xQzHhYVgdeB0Uv2WT7FjPngRjAgLL1jxu7LIkEMKWgiGiJMPg
54gOx8kWuj5uE9vqpWGRK0dGuPNlnQxh50pSgZi4PhRGz2nCBF6WdQFNmHDqssijk//
CUHWbNvMTIWyuHhXEhtwkplc0dAp1b3hHBywYM9Vae9fUmfpbHDb0yvjBjCHvceRjwkoQG6ABfh9
9ucE1NWO51Rc03XqGnHKsnk16BlqSH0YpM/sVWYrmio/F9h75aNX+Sz5EhkB7t/n4301aPOo="}
csr is the CSR in DER format and is represented in base64.
The procedure must return a JSON object with the following format:
{valid: "YES"}

or
{valid: "NO"}

Options for valid:

YES - The CSR meets the requirements from the PKI.

NO - The CSR does not meet the requirements from the PKI. Authentication fails.

adapter-pki-bridge-certificate-generation-procedure

Required
This procedure is responsible for requesting a certificate from the PKI and returning a certificate. This procedure is required and has one required parameter csr, which has the following format:
{"deviceId":"C146B473-DA25-46A7-8A79-
E8CE5E9270EE","csr":"MIICXzCCAUcCADAbMRkwFwYDVQQDFBBsaXpldEB1cy5pYm0uY29tMIIBIjA
NBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAt9A8WLa0NqAjizn9ccZFUPBLCCGEBCUQAgNPZK
cf3wW2LhQ75MEMfLyahZvqSBFd7IMMstRrpKiobx6PTGiMCkNB7lOzNa88tCHv81+wHaTIu2Qggq
pBMFPhvBdTbS93pafEQ7kXEGBk+uU7vwalUIHQyQT1+9ZaiH4ssf8Ybi
+qYmGrOH4CjvO7h93l0sAyOOWqcGBnOCcb1+YJP9F/
EyHLNfdr1FTDAAp0ERtUqVMDeJIRxscFnqZ1GG0rXCEJqAl3IHvrn6BiLrmQOxA5oE
+Lk4ry6cizw1yxYY1mWZq9eTCQQbMGBS/Aa+4KBOG3NCCL
+e4YKN2RJ0m2bcHRswIDAQABoAAwDQYJKoZIhvcNAQEFBQADggEBAHHOJbrGBCZCiDi3hXzVzji7
1euKMf8IUjGe+sfr+Sy5sfx9k
+icvKixImHCxSy0PeKp4QICSgfZxk2xQzHhYVgdeB0Uv2WT7FjPngRjAgLL1jxu7LIkEMKWgiGiJMPg
54gOx8kWuj5uE9vqpWGRK0dGuPNlnQxh50pSgZi4PhRGz2nCBF6WdQFNmHDqssijk//
CUHWbNvMTIWyuHhXEhtwkplc0dAp1b3hHBywYM9Vae9fUmfpbHDb0yvjBjCHvceRjwkoQG6ABfh9
9ucE1NWO51Rc03XqGnHKsnk16BlqSH0YpM/sVWYrmio/F9h75aNX+Sz5EhkB7t/
n4301aPOo=","userIdentity":{"userName":"lizet@us.ibm.com","attributes":
{"LtpaToken":"dHwRqHp61ukJCkEFBMRd6g63uV1bDg0rmGBU2cuBrinFp+7L7BVb
+4OebyIRMOoKLhHldLxj9JIPiWH4s16tHtNjddBxxbd9rdjZUgnicVY8+6GM8uTEwleRW
+lVzzwJX0Htvfa2iOQD9KAWLXkNHgneiELIANjAUxGsMzJGGg2K8LYYWeBhE0JGqJcb8WFFLYH4T5
Cgb9C+qXpre/KF/MNTrv2WQF9kWjPmMlPuT1Lh1tY9oSSqN20DNNZ8VcQ8p26po5yBMvtDMtn4/
EzfdhKYeTNFzQEmQpR66caQJlRV++m/
Oq4EiZBBzkOY6zpBVtmUzcH3D2xh5PYYVcFO8g=="},"displayName":""},"appId":"UserCert"}
csr is the CSR in DER format and is represented in base64.
The procedure must return a base64 string of the X.509 certificate in DER format in a JSON object with the following format:
{ certificateBase64: "<BASE64 STRING OF THE X.509 CERTIFICATE>" }

adapter-pki-bridge-certificate-validation-procedure

Optional

This procedure is responsible for validating a user's certificate when it is first received. This procedure is optional. If it is not used, the PKI bridge always returns YES. The procedure has one parameter certificate that is in the same format as the procedure in the adapter-pki-bridge-identity-from-certificate-procedure parameter.

The procedure is required to return a JSON object that states the validity of the certificate:
{valid: "YES"}

or
{valid: "NO"}

Options for valid:

YES - The certificate is considered valid by the PKI.

NO - The certificate is not considered valid by the PKI, and the client is required to start the enrollment process over.

adapter-pki-bridge-identity-from-certificate-procedure

Required
This procedure is responsible for creating a user certificate identity from a certificate that is passed by the user. The procedure must have one parameter certificate with the following format:
{"publicKey":
{"base64":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAt9A8WLa0NqAjizn9ccZFUPBLC
CGEBCUQAgNPZKcf3wW2LhQ75MEMfLyahZvqSBFd7IMMstRrpKiobx6PTGiMCkNB7lOzNa88tCHv8
1+wHaTIu2QggqpBMFPhvBdTbS93pafEQ7kXEGBk+uU7vwalUIHQyQT1+9ZaiH4ssf8Ybi
+qYmGrOH4CjvO7h93l0sAyOOWqcGBnOCcb1+YJP9F/
EyHLNfdr1FTDAAp0ERtUqVMDeJIRxscFnqZ1GG0rXCEJqAl3IHvrn6BiLrmQOxA5oE
+Lk4ry6cizw1yxYY1mWZq9eTCQQbMGBS/Aa+4KBOG3NCCL
+e4YKN2RJ0m2bcHRswIDAQAB","algorithm":"RSA"},"signature":
{"base64":"cONA8EKOQBiIKtdhAzG68pm0FMRkNfbVAIyZlttp+J9nXYmjO/
aGOEJk37oGzEPTO5uA/
eDArvQ9WF3BtzOdF9hw4j3ACJjo5oEnD7UTXbPzK2k1w3INX4cuOInLi7EJEKb
+CuO5uMy1mUOjx1aj/WaK
+E2KroFKNPyXdHAL7mwpkZO0aSYxUYYwcu8IAureMWZGps196Swk1YptboIEUSd5r3j07rBZX81B
AX5awqEx3tpbP3qpIJIK+6xoiu2tL67mKqJj9l1/Yb/
qQmUg6ouJtt9fWYUO7p1wJgUm9N0eixXftKttJ32Fp/
s0B7R72ntO9pGPrkYt8IUkzSq22Q==","algorithm":"SHA1withRSA"},"subjectUniqueId":"","version"
:1,"issuer":{"dn":"CN=Worklight Test Beta Signing CA,OU=Security Division,O=IBM
Worklight,L=Austin,ST=TX,C=US","cn":"Worklight Test Beta Signing
CA","uniqueId":""},"dn":"CN=user@us.ibm.com","cn":"user@us.ibm.com","valid":{"notBefore":
1381193593,"notAfter":
1382403193},"serialNumber":"efa7b0e3f0d9cef0","base64":"MIIDIzCCAgsCCQDvp7Dj8NnO8DA
NBgkqhkiG9w0BAQUFADCBizELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAlRYMQ8wDQYDVQQHEwZ
BdXN0aW4xFjAUBgNVBAoTDUlCTSBXb3JrbGlnaHQxGjAYBgNVBAsTEVNlY3VyaXR5IERpdmlzaW9u
MSowKAYDVQQDEyFXb3JrbGlnaHQgR2FycmljayBCZXRhIFNpZ25pbmcgQ0EwHhcNMTMxMDA4M
DA1MzEzWhcNMTMxMDIyMDA1MzEzWjAbMRkwFwYDVQQDFBBsaXpldEB1cy5pYm0uY29tMIIBIjA
NBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAt9A8WLa0NqAjizn9ccZFUPBLCCGEBCUQAgNPZK
cf3wW2LhQ75MEMfLyahZvqSBFd7IMMstRrpKiobx6PTGiMCkNB7lOzNa88tCHv81+wHaTIu2Qggq
pBMFPhvBdTbS93pafEQ7kXEGBk+uU7vwalUIHQyQT1+9ZaiH4ssf8Ybi
+qYmGrOH4CjvO7h93l0sAyOOWqcGBnOCcb1+YJP9F/
EyHLNfdr1FTDAAp0ERtUqVMDeJIRxscFnqZ1GG0rXCEJqAl3IHvrn6BiLrmQOxA5oE
+Lk4ry6cizw1yxYY1mWZq9eTCQQbMGBS/Aa+4KBOG3NCCL
+e4YKN2RJ0m2bcHRswIDAQABMA0GCSqGSIb3DQEBBQUAA4IBAQBw40DwQo5AGIgq12EDMbry
mbQUxGQ19tUAjJmW22n4n2ddiaM79oY4QmTfugbMQ9M7m4D94MCu9D1YXcG3M50X2HDiPcA
ImOjmgScPtRNds/MraTXDcg1fhy44icuLsQkQpv4K47m4zLWZQ6PHVqP9Zor4TYqugUo0/
Jd0cAvubCmRk7RpJjFRhjBy7wgC6t4xZkamzX3pLCTVim1uggRRJ3mvePTusFlfzUEBflrCoTHe2ls/
eqkgkgr7rGiK7a0vruYqomP2XX9hv+pCZSDqi4m2319ZhQ7unXAmBSb03R6LFd+0q20nfYWn
+zQHtHvae072kY+uRi3whSTNKrbZ"}
base64 is the DER formatted certificate. publicKey is also encoded in base64.
The procedure must return a JSON object in the following format:
{ userName:"user@us.ibm.com",displayName:"",attributes:{},appID:"UserCert",deviceId:"C146B473-DA25-46A7-8A79-E8CE5E9270EE" }

The goal of the JSON object that is returned is to form the original user identity of the user provided by the dependent realm during generation.
appId and deviceId are optional in this step. If not used, use an empty string as the value.
Parent topic: PKI bridge configuration