Custom Token Certificates

JFrog Installation & Setup Documentation

ft:sourceType
Paligo

Token certificates are used for signing and validating tokens. The certificates essentially a key pair comprised of a private key and root certificate: the private.key is used to sign access tokens and the root.crt is the matching public key, used to verify the token's signatures.

The JFrog Platform enables users to use token certificates, also called custom certificate keys. This section details how to create custom token certificates, and how to load them via bootstrapping files.

Prerequisites

The custom token certificate must meet the following prerequisites.

  • The certificate must match the provided private key.

  • The certificate must be valid for the next 7 days at least.

Load the key pair to the JFrog Platform Deployment (JPD) through bootstrap files

During certificate initialization, certificates and private keys will be read from the following paths, if present:

  • <VAR>/bootstrap/etc/access/keys/ca.crt- certificate authority PEM

  • <VAR>/bootstrap/etc/access/keys/ca.private.key- certificate authority private key PEM

  • <VAR>/bootstrap/etc/access/keys/root.crt- token issuer PEM

  • <VAR>/bootstrap/etc/access/keys/private.key- token issuer private key PEM

Implications of Creating and Changing the Key Pair

Resetting the token certificate (by loading new ones) will effectively revoke all of the tokens that have been generated. If you want to reset your certificates but maintain the token that were created previously, you will need to copy the old root.cert into the trusted directory: /var/etc/access/keys/trusted. See Resetting Token Certificates.Introduction to Access Tokens

Create a private-public key pair

The following is an example how to create a public-private key pair using OpenSSL.

The CA certificate must contain the extensions:CA:TRUEbasic constraints, digital signature and key certificate sign key usages.

  1. Create a configuration file with the required CA extensions. This can usually be derived from`/etc/ssl/openssl.cnf`.

    cp /etc/ssl/openssl.cnf ca.cnf
    
    echo "\n[ v3_ca ]\nbasicConstraints = critical, CA:TRUE\nkeyUsage  = critical, digitalSignature, keyCertSign" >> ca.cnf

    Here is an example`ca.cnf`:

    [ req ]
    distinguished_name  = req_distinguished_name
    
    [ req_distinguished_name ]
    countryName        = Country Name (2 letter code)
    stateOrProvinceName     = State or Province Name (full name)
    localityName            = Locality Name (eg, city)
    0.organizationName      = Organization Name (eg, company)
    organizationalUnitName  = Organizational Unit Name (eg, section)
    commonName         = Common Name (eg, fully qualified host name)
    emailAddress            = Email Address
    
    [ v3_ca ]
    basicConstraints = critical, CA:TRUE
    keyUsage         = critical, digitalSignature, keyCertSign
  2. Create a private key for the CA (Certificate Authority).

    openssl genrsa -out ca.key 2048
  3. Generate a self-signed CA certificate.

    The following command will prompt for the Distinguished Name (DN) parameters.

    openssl req \
      -new \
      -x509 \
      -sha256 \
      -days 365 \
      -key ca.key \
      -out ca.crt \
      -config ca.cnf \
      -extensions v3_ca

    Example prompt parameters:

    You are about to be asked to enter information that will be incorporated
    into your certificate request.
    What you are about to enter is what is called a Distinguished Name or a DN.
    There are quite a few fields but you can leave some blank
    For some fields there will be a default value,
    If you enter '.', the field will be left blank.
    -----
    Country Name (2 letter code) []:US
    State or Province Name (full name) []:CA
    Locality Name (eg, city) []:Sunnyvale
    Organization Name (eg, company) []:JFrog Ltd
    Organizational Unit Name (eg, section) []:JFrog Infra
    Common Name (eg, fully qualified host name) []:JFrog Root CA
    Email Address []:info@jfrog.com
  4. Verify the generated CA certificate.

    Example prompt parameters:

    openssl x509 -in ca.crt -text -noout

    Example result:

    Certificate:
              Data:
                  Version: 3 (0x2)
                  Serial Number: 15701892499106404289 (0xd9e85409269b97c1)
              Signature Algorithm: sha256WithRSAEncryption
                  Issuer: C=US, ST=CA, L=Sunnyvale, O=JFrog Ltd, OU=JFrog Infra, CN=JFrog Root CA/emailAddress=info@jfrog.com
                  Validity
                      Not Before: Aug 28 15:57:05 2019 GMT
                      Not After : Aug 27 15:57:05 2020 GMT
                  Subject: C=US, ST=CA, L=Sunnyvale, O=JFrog Ltd, OU=JFrog Infra, CN=JFrog Root CA/emailAddress=info@jfrog.com
                  Subject Public Key Info:
                      Public Key Algorithm: rsaEncryption
                          Public-Key: (2048 bit)
                          Modulus:
                              00:a3:1e:36:48:ac:c1:e2:13:78:f6:24:46:a5:70:
                              6b:2a:a9:a0:33:dc:77:e9:b5:e8:52:bb:46:79:32:
                              7f:e6:64:d1:be:f4:ae:c0:95:ea:7b:cd:63:88:7f:
                              60:8f:2e:53:e6:7d:9c:cc:22:f6:41:91:04:4f:b1:
                              f4:1c:dc:74:89:a2:81:46:9c:66:72:83:40:a7:26:
                              3b:4b:f1:0d:6d:bc:b9:bd:1a:ae:81:0a:ab:37:96:
                              b0:f1:2b:9c:f4:18:a4:ae:45:d2:38:e6:9a:8f:7b:
                              2f:45:0b:70:ae:d9:25:d6:5c:b2:67:15:11:ab:7c:
                              e2:02:4c:b7:0c:15:2d:32:22:b3:f9:be:99:4d:28:
                              93:6d:37:a8:2e:8d:57:54:63:ec:0d:c3:96:f1:2a:
                              9c:6f:e0:d4:3c:23:98:31:6a:a4:76:52:64:2c:9b:
                              23:5d:e1:56:f4:43:13:12:c0:27:73:78:99:68:c3:
                              dc:b2:79:af:a3:98:09:d3:69:69:ca:64:18:8d:15:
                              8f:97:f8:27:14:e3:53:a7:af:ca:9b:2e:3d:6e:df:
                              3e:f6:d6:e3:ab:43:de:8c:25:32:61:e1:fe:6d:73:
                              e5:52:12:35:af:8a:dc:b3:d8:e1:88:ec:56:c3:3c:
                              a2:35:31:90:e4:6d:e2:9c:78:c6:6c:26:60:72:25:
                              08:9f
                          Exponent: 65537 (0x10001)
                  X509v3 extensions:
                      X509v3 Basic Constraints: critical
                          CA:TRUE
                      X509v3 Key Usage: critical
                          Digital Signature, Certificate Sign
              Signature Algorithm: sha256WithRSAEncryption
                  26:6a:e9:2e:d0:00:8a:d6:f2:94:e8:50:c6:e0:1c:fc:76:70:
                  0c:fe:1f:87:5a:01:d2:5c:77:29:fa:22:19:7f:8c:77:3b:c2:
                  2d:f1:58:22:0c:c5:db:41:d5:c9:71:1b:33:b3:8b:a9:a8:79:
                  df:35:92:6c:e2:3c:38:0c:af:8f:78:82:63:94:64:36:cd:4f:
                  3a:8d:17:04:59:d1:c5:49:d0:3b:df:26:c4:b6:e0:7f:0a:ab:
                  7a:e1:a5:8a:6b:36:8b:2a:6b:57:ea:57:fe:91:33:36:89:13:
                  a1:a6:55:d6:fe:93:ab:8f:5f:88:1b:be:98:86:4f:52:9f:1b:
                  ee:23:51:61:ce:17:b4:ed:cb:2f:7c:38:6f:9f:ac:e9:a6:43:
                  74:1b:0c:94:e6:b3:3d:ee:d2:49:bb:84:19:e3:6b:d2:17:8c:
                  17:c0:bd:59:ad:03:df:05:49:9b:4d:ea:d5:8d:6a:c0:1c:81:
                  f2:ae:fa:20:b3:0b:a1:6f:87:6d:c2:a7:47:37:4d:76:57:d0:
                  74:dc:8d:cb:57:f3:41:32:87:2e:52:3f:3d:e5:f3:66:83:f4:
                  71:82:8b:54:1e:00:8d:7c:54:43:7e:93:7b:55:3a:36:d4:5e:
                  ec:4f:87:9c:54:45:19:d8:7a:cd:71:df:6c:a4:7e:71:ed:fb:
                  09:60:d0:eb