Embedded PKI bridge

The embedded PKI bridge is an included PKI bridge that can be used with user certificate authentication. The embedded PKI bridge is available with the com.worklight.core.auth.ext.UserCertificateEmbeddedPKI class name and is configured by adding parameters to the realm definition.

The embedded PKI bridge is useful for developers without direct access to the business' PKI during testing. Administrators that are interested in testing the user certificate authentication feature without implementing their own PKI bridge can also use the embedded PKI bridge. The embedded PKI bridge is not recommended or supported for production environments.

Requirements for use

For the embedded PKI bridge, a certificate authority (CA) certificate and private key must be available. The certificate and private key must be added to a keystore manually. The keystore must be in the PKCS #12 file format, such as a .p12 file. A password to access the keystore can be supplied optionally in plaintext form. If the .p12 file does not exist, cannot be read, or is supplied an invalid password, an error is thrown in the server trace. The following example shows a realm definition for wl_userCertificateAuthRealm with the embedded PKI:

<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.UserCertificateEmbeddedPKI" />
  <parameter name="embedded-pki-bridge-ca-p12-password"
             value="capassword" />
  <parameter name="embedded-pki-bridge-ca-p12-file-path"
             value="/opt/ssl_ca/ca.p12" />
  <parameter name="embedded-pki-bridge-organization"
             value="IBM Worklight" />
  <parameter name="embedded-pki-bridge-add-cert-extensions"
             value="true" />
</realm>

Configuration parameters

The following embedded PKI bridge parameters are available.

embedded-pki-bridge-ca-p12-file-path

Required

Full file path of the .p12 file for the CA that signs user certificate requests.

embedded-pki-bridge-ca-p12-password

Optional

Password in plaintext used to decode the CA .p12 file specified. No password is used if not specified.

embedded-pki-bridge-organization

Optional

Organization name that is added to the distinguished name (DN) inside a signed certificate (O=<organization name specified>). If not specified, no organization is added to the DN.

embedded-pki-bridge-add-cert-extensions

Optional

Add non-critical MobileFirst custom certificate extensions to the user certificate before it is signed. This parameter provides more details to user identity attributes on subsequent runs. These details include device ID, group ID, and application name stored in the certificate. By default, this parameter is false. We can enable the parameter using the true value. This parameter is not always supported and may not work for the configured server configuration. We must test this option first on the infrastructure to ensure that a certificate is not marked invalid if extensions are enabled. When this parameter is enabled, the device ID is added with the OID 1.3.6.1.4.1.2.6.256.1 and the app name is added with the OID 1.3.6.1.4.1.2.6.256.2. These OIDs are not formally registered and may change.

embedded-pki-bridge-days-before-expire

Optional

Configure the length of time the generated certificate is valid. This setting defaults to one year (365 days).

embedded-pki-bridge-crl-uri

Optional

Configure an optional CRL for the certificate authority. If the certificate generated exists on a client's device and is revoked in the CRL, the client is required to generate a certificate.

Parent topic: PKI bridge configuration