Managing Applications

Contents

Creating An Application

You can use Self Service Portal to create (register) your application. This can be done before the application is actually developed and/or released.

  1. To register your application, visit the Applications page and click the New Application button.+ You will see a screen as below:

Add application page

  1. Start filling the form with required information:

    • ID: This represents the Application ID of your application. This is a string that uniquely identifies your application. We recommend to use a fully qualified package/class name as it is sufficiently unique within the organization, e.g. com.company.division.AlertingApp. The maximum length is 255 and the value should be alphanumeric with no spaces.

    • Name: The name of the application. It should not be more than 50 characters. Spaces are allowed.

    • Short Name: A unique human-readable short name of the application. This name is used as a label in Self Service. Only alphanumeric characters and underscore are allowed. Max length should not exceed 60 characters.

    • Owner: Choose the group which would be the owner of this application. Choose your DevOps team’s group. Is it not available yet? Please refer to Creating a group.

    • Type: Choose the type of application, purely acting as metadata.

    • Visibility: see Application visibility below

    • Description: A short summary describing the purpose of this application, e.g. "Enriching transaction events with transaction categories.". Must not exceed 200 characters.

  1. At this point you have created your Application in Self Service. Once the application is successfully created, you will be directed to the application detail page.

the Application ID is used by consuming applications to keep track of where it left off consuming messages from a stream. Consumers sharing the same ID share the events on a stream. So one event can be only read by one consumer with the same Application ID (read more about consumer groups).

Configuring Application Principals

The application principal is used to authorize the application to use the stream (either producing or consuming). The principal is formed by the Distinguished Name (DN) of the certificate used by the application.

For every distinct environment, a principal needs to be defined. Without a principal, an application can not have consumer or produce access to a stream.

To configure the application principal on the selected environment:

  1. Visit the detail page of the application.

  2. Select the environment for which you want to configure the principal.

  3. Click on the Configure button in the application box. You will see a modal as below:

Configure application principals modal

  1. Upload the PEM file of your application certificate, see "Generating A Certificate PEM File"

  2. The certificate chain will be shown. Confirm that the uploaded certificate matches the certificate you will use for your application in the corresponding environment.

  3. Click on Save.
    The application box name will turn green indicating that the application is configured properly on that environment. Above steps can be repeated for different environments where application is required to access the stream.

If you are replacing an application certificate, you can register 2 principals at the same time, and choose to delete the old one once the application is not using it anymore.

Generating A Certificate PEM File

To reduce errors with human input and to better validate the uploaded certificates, we have opted to let the user upload a PEM file for his certificate. Most of the time, you are using a .jks file for your application. Use the instructions below to convert a .jks to a .pem file, ready to be used in Self Service.

Assuming you already have a .jks file for your app, here is how you generate a .pem file for it:

The following is taking into account that you are using a bash terminal and not ZSH or another custom terminal to run the following commands.

  1. First, export the .jks keystore into the PKCS12 format using keytool. Replace yourAlias with the alias of your application certificate, sourceKeyStore with the path of your .jks file

keytool -importkeystore \
  -alias yourAlias \
  -srckeystore sourceKeyStore.jks \
  -srcstoretype jks \
  -srcstorepass notsecret \
  -destkeystore destFile.p12 \
  -deststoretype PKCS12 \
  -deststorepass notsecret

  1. Secondly, export the application certificate to the target .pem file, using the openssl command

openssl pkcs12 \
  in destFile.p12 \
  nokeys \
  -passin pass:notsecret \
  -passout pass:notsecret \
  | grep -v -e '^\s' | grep -v '^\(Bag\|subject\|issuer\)' > destKeyStore.pem

This results in a .pem file which can be uploaded as an application principal,.

You can find a dummy certificate here which can be used to verify the formatting of your outputted pem file.

Requesting Stream Access

Before your application can produce to a stream or consume from it, a Stream Access Request has to be done. If you are making a request for an environment for testing purposes (private), an approval will not be necessary. For all other (public) environments, approval is necessary. The request is then received by the data owner of the stream.

Requesting access to a stream is easy. Follow the steps below:

Before you request stream access, make sure you have configured the Application Principal for the specific environment in which you request access (see above)

  1. Visit the detail page of your application.

  2. Scroll to the bottom of the page where + Add request button is visible.

  3. Click on the button to open the Request approval modal:

Request approval modal

  1. Select the Application type by clicking on Consumer or Producer button.

  2. Select the Stream from the Stream dropdown. If there are already pending and/or approved requests for this stream a list of them will appear after selection.

  3. Select the Environment from the dropdown.

  4. Submit the request by clicking the Request approval button.

The data owner will receive your request and has to approve your ‘Stream Access Request’.

Deleting An Application

You can use Self Service Portal to delete your application. This can be done if there are no active producer/consumer stream connections in all environments.

  1. Visit the Application Detail page

  2. Click Edit Application.

  3. There is a Delete Application button on the bottom left of the page. Clicking on that button, if all constraints are met and deletion is possible, a confirmation modal opens, as below:

Delete application confirmation

  1. Clicking on Confirm will delete the application. Otherwise, a modal opens with information on how many active stream connections there are in all environments, as below:

Inform application modal

Application visibility

By setting the application visibility, you control whether applications will end up in the Applications page for everyone, or is just visible to the owner.

  • Public: choose this option if you are working on a normal application that will be eventually deployed in production, and is not confidential in any way

  • Private: choose for private if this is a test application that will never be deployed in production or an application that should not end up in the Applications page.