Certificate management

The purpose of this tutorial is to walk through the process of configuring certificates within Access Gateway.

Before you begin

Background

Certificates are made available for use to the Access Gateway and it’s applications in two ways:

  • Certificates are generated when an application is created. Generated certificates are self-signed and mainly used for initial configuration of the application in non-production environments.
    Info

    Note

    Generated certificates should not be used in production environments.

  • Certificates are loaded using the Command Line Management Console reference. When new certificates are loaded for the same domain they overwrite any existing certificate. If no certificate exists, then the certificate is stored.

When creating an application, the following logic is used to initially associate certificates with the new application.

  1. If a certificate already exist for the application domain, then the application uses the existing certificate.
    The certificate could have been created automatically, or loaded through the management console.

  2. If the certificate doesn’t exist, then a self-signed wildcard or hostname certificate is created and associated with the application.

Auto generated self-signed certificates

When an application is created and no certificate has been loaded that corresponds to the application’s domain a certificate is generated.

The following sections show how to create applications using wildcard and hostname certificates.

To use an auto-generated wildcard certificate in the Access Gateway:

  1. Navigate to the Access Gateway Admin UI console.
  2. Select the Applications tab.
  3. Click Edit in the row containing the application, which should be associated with the certificate.
    In this tutorial we use the Sample Header App.
    Click edit app icon for the selected row.
  4. In the Settings tab, expand Advanced
  5. Ensure that the Certificate Type toggle is deactivated.
    Enable certificate toggle.
  6. Click Done.
  7. In the same row, click the Goto Application icon.
    Goto application icon.
    Note: Your Okta tenant administrator needs to assign the sample application to you. Generated certificates should not be used in production environments
  8. When the application is reached click Not Secure next to the application URL.
    Secure Application.
    Info

    Note

    This tutorial uses Google Chrome. Other browsers have similar functionality but may use different steps.

  9. Click Certificate.
    Secure Appication.

    The certificate associated with the application is then displayed.
    Self signed generated certificate.

    Info

    Note

    With wildcard certificates, the domain shown in the Issued to: field is prefixed by an * (asterisk) to show that this certificate can be used for any hostname that is in the applications domain.
    Note the Issued by: field, indicating this is a self signed certificate.

Configuring apps with hostname certificates

To use an auto-generated hostname certificate in the Access Gateway:

  1. Navigate to the Access Gateway Admin UI console.
  2. Select the Applications tab.
  3. In the Settings tab, expand Advanced.
  4. Ensure that the Certificate Type toggle is activated.
    Enable certificate toggle.
  5. Click Goto Application.
    Goto application icon.
    Info

    Note

    Your Okta tenant administrator needs to assign the sample application to you.

  6. Click Done.
  7. Click Goto Application.
  8. When the application is reached, click Not Secure next to the application URL.
  9. Click Certificate.
    Self signed hostname generated certificate.
Note

Note

For hostname certificates, the domain shown in the Issued to: field shows the fully qualified domain name (FQDN) of the host server.

Adding Certificates and Replacing an Auto-Generated Certificate with a Valid Certificate

The following steps show how you can use the command line console to replace an automatically generated certificate with a user supplied certificate.

Info

Note

User supplied certificates are normally issued and signed by a trusted CA, but can also be self-signed. See Obtain certificates.

  1. SSH connect to the Access Gateway Management console.
  2. Enter 2 to go to the Services sub-menu.

  3. Enter 1 to go to the NGINX sub-menu.

  4. Enter 6 to update an SSL certificate.
    All existing certificates are displayed and resemble:

    Available Certificates:
    -----------------------
    [1] admin.crt
    [2] gateway_info.crt
    [3] localhost.crt
    . . . 
    [a] Add new certificate
    [x] Exit
    [#, a, x]: 
    

  5. .Select a command to perform:

    1. x - Exit the add/modify certificates sub-menu.
    2. a - Add a new certificate.
    3. # - Modify an existing certificate.

Add a new certificate

Certificates are added using cut and paste operations.

Info

Note

Both the certificate and the key must be in PEM format.

Info

Note

Depending on your OS the command sequence for copy/paste may be different.
This applies only to copy/paste operations and not completing the entry of certificate contents.

  1. In a text editor, open the new certificate file.
  2. Select and copy the contents of the certificate file.
  3. Return to the command line console and paste the certificate file contents.
  4. Enter [ctrl]+[d] to save the certificate contents.
    Info

    Note

    The command line console opens a new editor for the certificates' associated key contents.

  5. In a text editor, open the key file.
  6. Select and copy the contents of the key.
  7. Return to the command line console and paste the key file contents.
  8. When complete, enter [ctrl]+[d] to save the key contents.
Info

Note

The hostname and certificate type are pulled automatically for the certificate.

If an existing certificate is being updated, a prompt showing A certificate for this domain already exists, do you wish to replace it? [Y,N] appears. To proceed with the certificate update, enter the y followed by the Enter key.

Info

Note

You can verify replacement certificates by launching the associated application in the Admin Console and following the steps to view the web page's certificate as described earlier.

Modify an existing certificate

When modifying an existing certificate, you will be presented with three options:

  • [d] - Delete certificate
  • [u] - Update certificate
  • [x] - Return without change

To exit without change, enter x.

To update a certificate, enter u.
Follow the prompts to copy and paste the replacement certificates key and certificate file, both of which must be in PEM format.

To delete a certificate, enter d.
Follow the prompt to confirm the delete or cancel.

Reference and Notes

Info

Caution

Password Protected Certificates: 
Access Gateway does not support password protected certificates. If you upload a password protected certificate, you must re-enter the certificate’s password every time Access Gateway restarts, otherwise the gateway will not function property.

  • Wildcard certificate validity: Wildcard certificates created by a Trusted CA are only valid for hostnames in a secondary domain and are not available for hostnames in tertiary or higher domains.
    For example: For a given wildcard certificate with CN=*.gateway.info , accessing https://test.gateway.info will result in the certificate being validated successfully.

     

  • Generating self-signed certificates for testing:
  • Self-signed certificates can be generated using tools, such as openssl.

    For example:

    $ openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem
    Generating a RSA private key
    ...................................
    writing new private key to 'key.pem'
    -----
    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.
    . . .
    -----
    Country Name (2 letter code) [XX]:Your country code
    State or Province Name (full name) []:Your state
    Locality Name (eg, city) [Default City]:Your City
    Organization Name (eg, company) [Default Company Ltd]:Your Company, Inc
    Organizational Unit Name (eg, section) []:Your organinzational unit. 
    Common Name (eg, your name or your server's hostname) []:*.gateway.info
    Email Address []:noreply@gateway.infp
    $ ls *.pem
    key.pem certificate.pem
    

    See https://www.openssl.org/ for more information on Open SSL.

Next Steps

  • Create self-signed certificates using openssl and similar tools.
  • Obtain certificates from valid certificate authorities such as Verisign, Let's Encrypt, your DNS Provider, and others.