Getting Started with Predix Audit

Creating a UAA Service Instance

You can create multiple instances of the UAA service in your space.

About This Task

As a best practice, first delete any older unused instances before creating a new one.

Procedure

  1. Sign into your Predix account at https://www.predix.io.
  2. Navigate to Catalog > Services, then click the User Account and Authentication tile.
  3. Click Subscribe on the required plan.
  4. Complete the fields on the New Service Instance page.
    FieldDescription
    OrgSelect your organization.
    SpaceSelect the space for your application.
    Service instance nameEnter a unique name for this UAA service instance.
    Service planSelect a plan.
    Admin client secretEnter a client secret (this is the admin password for this UAA instance). The client secret can be any alphanumeric string.
    Note: Record the client secret in a secure place for later use.
    Subdomain(Optional) Enter a subdomain you might need to use in addition to the domain created for UAA. You must not add special characters in the name of the subdomain. The value of sub-domain is case-insensitive.
  5. Click Create Service.

Results

Your UAA instance is created with the following specifications:

  • A client identifier (admin).
    Note: An admin client is required for bootstrap purposes. You can create additional clients to use with your application.
  • A client secret (that you specified while creating the service).

To retrieve additional details of your instance, you can bind an application to your instance.

Using the Command Line to Create a UAA Service Instance

Optional procedure for using the command line instead of the graphical user interface to create a UAA service instance.

About This Task

You can create up to 10 instances of UAA service in your space. If you need additional instances, you must delete an older unused instance and create a new one.

Procedure

  1. Use the Cloud Foundry CLI to log into Cloud Foundry. 
    cf login -a <API_Endpoint>

    Depending on your Predix.io registration, the value of <API_Endpoint> is one of the following:

    • Predix US-West

      https://api.system.aws-usw02-pr.ice.predix.io

    • EU-PoP

      https://api.system.aws-eu-central-1-pr.ice.predix.io

    For example,

    cf login -a https://api.system.aws-usw02-pr.ice.predix.io
  2. List the services in the Cloud Foundry marketplace by entering the following command.
    cf marketplace

    The UAA service, predix-uaa, is listed as one of the available services.

  3. Create a UAA instance by entering the following command. 
    cf create-service predix-uaa <plan> <my_uaa_instance> -c '{"adminClientSecret":"<my_secret>","subdomain":"<my_subdomain>"}'

    where:

    • <plan> is the plan associated with a service. For example, you can use the tiered plan for the predix-uaa service.
    • -c option is used to specify following additional parameters.
      • adminClientSecret specifies the client secret.
      • subdomain specifies a sub-domain you might need to use in addition to the domain created for UAA. This is an optional parameter. You must not add special characters in the name of the sub-domain. The value of sub-domain is case insensitive.
    Note: Cloud Foundry CLI syntax can differ between Windows and Linux operating systems. See the Cloud Foundry help for the appropriate syntax for your operating system. For example, to see help for the create service command, run cf cs.

Results

Your UAA instance is created with the following specification:

  • A client identifier (admin).

    Note: An admin client is created for bootstrap purpose. You can create additional clients to use with your application.

  • A client secret (that you specified while creating the service).

To retrieve additional details of your instance, you can bind an application to your instance.

Create a predix-uaa service instance with client secret as admin and sub-domain as ge-digital:

cf cs predix-uaa tiered test-1 -c '{"adminClientSecret":"admin","subdomain":"ge-digital"}'

This is how it appears in VCAP SERVICES:

"VCAP_SERVICES": { 
"predix-uaa": [
   {
    "credentials": {
     "dashboardUrl": "https://uaa-dashboard.run.asv-pr.ice.predix.io/#/login/04187eb1-e0cf-4874-8218-9fb77a8b4ed9",
     "issuerId": "https://04187eb1-e0cf-4874-8218-9fb77a8b4ed9.predix-uaa.run.asv-pr.ice.predix.io/oauth/token",
     "subdomain": "04187eb1-e0cf-4874-8218-9fb77a8b4ed9",
     "uri": "https://04187eb1-e0cf-4874-8218-9fb77a8b4ed9.predix-uaa.run.asv-pr.ice.predix.io",
     "zone": {
      "http-header-name": "X-Identity-Zone-Id",
      "http-header-value": "04187eb1-e0cf-4874-8218-9fb77a8b4ed9"
     }
    },
    "label": "predix-uaa",
    "name": "testuaa",
    "plan": "Tiered",
    "provider": null,
    "syslog_drain_url": null,
    "tags": [],
    "volume_mounts": []
   }
  ],

Creating and Binding a Predix Audit Service Instance

Procedure

  1. Use the Cloud Foundry CLI to create a Predix Audit Service Instance

    On Mac OS and Linux, use the following syntax:
    cf create-service predix-audit <plan> <my_audit_service_instance> -c '{"trustedIssuerIds":["<uaa_instance1_host>/oauth/token", "<uaa_instance2_host>/oauth/token"]}'
    On Windows, use the following syntax:
    cf create-service predix-audit <plan> <my_audit_service_instance> -c "{\"trustedIssuerIds\":[\"<uaa_instance1_host/oauth/token\", \"<uaa_instance2_host/oauth/token\"]}"
    Where:
    • <plan>: The plan associated with a service.
    • <my_audit_service_instance>: the service instance you are creating.
    • "trustedIssuerIds": The issuerID of your trusted issuer (UAA instance), such as https://13fa0384-9e2a-48e2-9d06-2c95a1f4f5ea.predix-uaa.grc-apps.svc.ice.ge.com/oauth/token. You can use a comma-separated list to specify multiple trusted issuers. You can retrieve this URL from the VCAP_SERVICES environment variable after binding your UAA instance to an application.
  2. Create service keys using the following command line:
    cf create-service-key audit-instance  audit-instance-keys
  3. Retrieve the Predix Audit Service keys by entering the following command line:
    cf service-key audit-instance  audit-instance-keys
    The command displays the service credentials, which contain the audit and query endpoint URIs.
    {
 "audit-pub-client-scope": [
  "audit.roles.2f2b8411-7aee-412c-ac31-216eeb02f0c4.write",
  "predix-event-hub.zones.b08a704d-b716-433c-98c0-94424209fd6a.grpc.publish",
  "predix-event-hub.zones.b08a704d-b716-433c-98c0-94424209fd6a.user"
 ],
 "audit-query-api-scope": "audit.zones.2f2b8411-7aee-412c-ac31-216eeb02f0c4.user",
 "audit-query-api-url": "https://audit-service-sysint-blue-dev.run.aws-usw02-dev.ice.predix.io",
 "audit-receiver-url": "https://audit-receiver-sysint-blue-dev.run.aws-usw02-dev.ice.predix.io",
 "event-hub-uri": "event-hub-aws-usw02-cf3-dev.data-services.predix.io:443",
 "event-hub-zone-id": "b08a704d-b716-433c-98c0-94424209fd6a",
 "tracing-interval": 1.2e+06,
 "tracing-token": "cm9vdDp0cmFjaw==",
 "tracing-url": "https://message-tracing-sysint-blue-dev.run.aws-usw02-dev.ice.predix.io/v1/checkpoint",
 "trusted-issuers": [
  "https://2126c5d9-071f-4e13-aefe-9222da22af2b.predix-uaa.run.aws-usw02-dev.ice.predix.io/oauth/token"
 ]
}
    Note: Save the audit-receiver-url and audit-pub-client-scope values for pulishing purposes.

Creating an OAuth2 Client

You can create OAuth2 clients with specific permissions for your application to work with Predix Platform services. Often this is the first step after creating an instance of a service.

About This Task

When you create an instance of UAA, the UAA Dashboard is available for configuring that instance of UAA. You can use the Client Management tab in the UAA Dashboard to create the OAuth2 clients.

Procedure

  1. In the Predix.io Console view, select the Space where your services are located.
  2. In the Services Instances page, select the UAA instance to configure.
  3. Select the Configure Service Instance option.
  4. In the UAA Dashboard login page, specify your admin client secret and click Login.
  5. In UAA Dashboard, select the Client Management tab.
    The Client Management tab has two views, Clients and Services . The Services view displays the service instances that you have created for your services.
    Note: The service instances displayed in the Services view were created while using the UAA that you are trying to configure. Service instances that you created using other UAA instances are not displayed on this page.
  6. Click Create Client to open the Create Client form.
  7. Complete the Create Client form.
    FieldDescription
    Client IDSpecify a name for the OAuth2 client you are creating.
    Authorized Grant TypesChoose one or more of the following grant types:
    • authorization_code

      When you use the authorization code grant type, the client directs the resource owner to UAA, which in turn directs the resource owner back to the client with the authorization code.

    • client_credentials

      When you use the client credentials grant type, the OAuth2 endpoint in UAA accepts the client ID and client secret and provides Access Tokens.

    • password

      When you use the resource owner password credentials grant type, the OAuth2 endpoint in UAA accepts the username and password and provides Access Tokens.

    • refresh_token

      The refresh tokens are credentials used to obtain access tokens. You can choose this option to obtain refresh token from UAA. You can then use the refresh token to obtain a new access token from UAA when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope.

    • implicit

      When you use the implicit grant type, UAA directly issues an Access Token to the client without authenticating the client. This reduces the number of round trips required to obtain an access token.

    For more information on grant types, see RFC 6749.

    Client SecretSpecify the password. It is important that you keep a note of this password. If lost, this password cannot be retrieved.
    Confirm Client SecretReenter the client secret.
    Redirect URISpecify a redirect URI to redirect the client after login (for example, http://example-app.com/welcome). This value is mandatory if you use the Authorization Code or Implicit authorization grant type. If you use the Authorization Code grant type, the redirect URI is your application's endpoint or callback that expects user authorization code. If you use the Implicit grant type, the Redirect URI is the end point where UAA sends the bearer token.

    Use this URI when you start using UAA as the service provider for your external Identify provider.

    ScopesScopes are permissions associated with an OAuth Client to determine user acces to a resource through an application. The user permissions are for authorization grant types authorization_code, password and implicit..

    By default, the admin client is assigned all required scopes. For a new client, an administrator can select the scopes to be added based on client requirements.

    For a list of available scopes, see Scopes Authorized by the UAA.

    To use an OAuth2 client for your Predix Platform service instance, you must update your OAuth2 client to add scopes that are specific to each service after adding the client to the service instance.

    AuthoritiesAuthorities are permissions associated with the OAuth Client when an application or API is acting on its own behalf to access a resource with its own credentials, without user involvement. The permissions are for the client_credentials authorization grant type.

    By default, the admin client is assigned all required authorities. For a new client, an administrator can select the authorities to be added based on client requirements.

    The list of authorities matches the list of scopes. For a list of available UAA scopes, see Scopes Authorized by the UAA.

    To use an OAuth2 client for your Predix Platform service instance, you must update your OAuth2 client to add authorities that are specific to each service after adding the client to the service instance.

    Note:

    An admin client is not assigned the default authority to change the user password. To change the user password, you must add the uaa.admin authority to your admin client.

    Auto Approved ScopesSpecify scopes that can be approved automatically for the client without explicit approval from a resource owner.
    Allowed ProvidersSpecifies the names of the external identity providers, if any. This field is required if you are using external identity providers with UAA as a service provider.
    Access Token ValiditySpecifies the access-token expiration time in ms.
    Refresh Token ValiditySpecifies the refresh-token expiration time in ms.

Using UAAC to Create an OAuth2 Client

You can use the UAA command-line interface (UAAC) instead of UAA Dashboard to create an OAuth2 client.

About This Task

You can use the UAAC, to manage your UAA instance. For more information on installing the command-line interface, see https://github.com/cloudfoundry/cf-uaac.

Procedure

  1. Specify your UAA instance as the intended target.
    uaac target <uaa_instance_url>

    <uaa_instance_url> is the URL to your trusted issuer, for example, https://11fa0273-9e2a-37e2-9d06-2c95a1f4f5ea.predix-uaa.run.aws-usw02-pr.ice.predix.io. You can retrieve this URL from the VCAP_SERVICES environment variable after binding your UAA instance to an application.

  2. Log in using the administrative client.
    uaac token client get admin
  3. Specify the administrative client secret at the prompt.
  4. Use the following command to create the OAuth2 client:
    uaac client add [client_name] 
    --authorities "uaa.resource" 
    --scope "openid" 
    --autoapprove "openid" 
    --authorized_grant_types [authorization_code|implicit|password|client_credentials|refresh_token] 
    --redirect_uri [redirect_uri_1, redirect_uri_2, ...]

    For more information on UAA options such as scopes and authorized_grant_types, see the UAA documentation at https://github.com/GESoftware-CF/uaa/blob/master/docs/UAA-APIs.rst.

Updating the OAuth2 Clients to use the Predix Audit Service

Before You Begin

You must have an OAuth2 client with permission to the Predix Audit Service, and an OAuth2 client with permission to query audit messages. Your auditing application uses the client ID from the auditing OAuth2 client to request a token from UAA for access. Similarly, your audit querying application uses the client ID from the querying OAuth2 client to request a token from UAA for access. The OAuth2 client uses an authorization grant to request an access token. OAuth2 defines four grant types. Based on the type of authorization grant that you have used, you must update your OAuth2 client to generate the required JWT.

Procedure

Update your auditing OAuth2 client with the following authorities:
"audit-pub-client-scope": [
  "audit.roles.2f2b8411-7aee-412c-ac31-216eeb02f0c4.write",
  "predix-event-hub.zones.b08a704d-b716-433c-98c0-94424209fd6a.grpc.publish",
  "predix-event-hub.zones.b08a704d-b716-433c-98c0-94424209fd6a.user"
],
"audit-query-api-scope": "audit.zones.2f2b8411-7aee-412c-ac31-216eeb02f0c4.user",

uaac client update [client_id] --authorities "predix-event-hub.zones.<Event-Hub-Zone-Id>.user, predix-event-hub.zones.<Event-Hub-Zone-Id>.grpc.publish" , “audit.roles.<audit-zone-id>write” ,  "audit.zones.<audit-zone-id>.user"
Note:

To have data integrity, the user is required to sign each audit event message with a digital signature (e.g., RSA PKI) and the Predix Audit Service Query API should verify that the signature is valid. The digital signature should be owned and maintained by the customer and used within the message payload field to uniquely identify the original message.

Creating an AuditClient with the Predix Audit SDK

Note: Download the latest version of the Predix Audit SDK from the following site: https://devcloud.swcoe.ge.com/artifactory/PREDIX/com/ge/predix/audit/audit-sdk/

Version 2.0.0

Add the following dependency to the maven pom XML file:
<dependency>
      <groupId>com.ge.predix.audit</groupId>
      <artifactId>audit-sdk</artifactId>
      <version>2.0.0</version>
</dependency>

Supported Audit Clients

Audit SDK supports two types of clients:
  1. Multi-tenancy backed by a single audit service instance (previous mode of AuditSDK).
    • Synchronized Audit Client
    • Asynchronous Audit Client.
  2. Multi-tenancy backed by an Audit Service instance per TMS tenant.
    • Audit Client with TMS.

Synchronous Audit Client

Before creating the auditClient, you need to create an AuditConfiguration. The AuditConfiguration can be constructed either in an automatic or manual methods:

Automatic AuditConfiguration Creation

Automatic creation requires that your application is bound to the predix-audit service instance. It also requires to set the following environment variables in your application

  • AUDIT_SERVICE_NAME: The name of AuditService in the cf marketplace.
  • AUDIT_UAA_URL: https://<YOUR_UAA_ID>.predix-uaa.run.aws-usw02-dev.ice.predix.io/oauth/token.
  • AUDIT_UAA_CLIENT_ID: The UAA client for Audit Service.
  • AUDIT_UAA_CLIENT_SECRET: The UAA secret of the client.
The following is an example of the manifest.yml file:
  ---
    applications:
    - name: my-auditing-applcation
      instances: 1
      services:
        - my-audit-service
      env:
        AUDIT_SERVICE_NAME: predix-audit
        AUDIT_UAA_URL: https://2e6f8552-acb2-4d96-b470-0d44fe8cd33b.predix-uaa.run.asv-pr.ice.predix.io/oauth/token
        AUDIT_UAA_CLIENT_ID: client
        AUDIT_UAA_CLIENT_SECRET: secret
Additional optional parameters can be supplied via VCAP to control the client configuration:
  • AUDIT_MAX_RETRY_COUNT: The number of attempts made to resend a failed audit message from the client application to the Audit service.
    • Valid values: 0-5. default: 2.
  • AUDIT_RETRY_INTERVAL_MILLIS: The amount of time in milliseconds between each retry attempt.
    • Valid values: 2,000 - 20,000 (2 sec - 20 sec). default - 10,000.
  • AUDIT_MAX_CACHED_EVENTS: The maximum number of events cached im memory, waiting to be sent.
    • Default: 50,000. minimum value is 1000.
  • AUDIT_RECONNECT_POLICY: Controls whether the Audit client attempts a reconnect when disconnected.
    • Valid values: MANUAL, AUTOMATIC. default: AUTOMATIC - no reconnect attempt is made

The AuditConfiguration is automatically initialized from the VCAP, as follows:

private VcapLoaderServiceImpl vcapLoaderService = new VcapLoaderServiceImpl();
private AuditConfiguration auditConfiguration = vcapLoaderService.getConfigFromVcap();

Manual AuditConfiguration Creation

The user can use one of the AuditConfiguration builders to manually create the AuditConfiguration. The following builders are available:
  • AuditConfigurationBuilder (AuditConfiguration.builder()) to create a client with a UAA user / password for authentication.
  • AuditConfigurationWithAuthTokenBuilder (AuditConfiguration.builderWithAuthToken()) to create a client with an OAuth token. 
    AuditConfiguration sdkConfig =  AuditConfiguration.builder()
        .bulkMode(true)
        .uaaUrl(uaaUrl)
        .uaaClientId(uaaClientId)
        .uaaClientSecret(uaaClientSecret)
        .ehubZoneId(ehubZoneId)
        .ehubHost(ehubHost)
        .ehubPort(ehubPort)
        .build();

AuditClient Creation

Auditclients Client requires only AuditConfiguration.
AuditClientSync<AuditEventV2> auditClientSync = new AuditClientSync<>(auditConfiguration);

Audit Events Publishing

To publish an event, you can use the auditClient.audit(AuditEvent) or auditClient.audit(List<AuditEvent>). For example:
AuditEvent eventV2 = AuditEventV2.builder()
      .payload("This is test payload")
      .classifier(AuditEnums.Classifier.FAILURE) 
      .publisherType(AuditEnums.PublisherType.APP_SERVICE)    
      .categoryType(AuditEnums.CategoryType.API_CALLS)       
      .eventType(AuditEnums.EventType.FAILURE_API_REQUEST)
      .tenantUuid(UUID.randomUUID().toString())       
      .correlationId(UUID.randomUUID().toString())
      .build()

auditClient.audit(eventV2);

Audit Results

The results of the audit operation are returned with the AuditingResult object. It contains the following elements: 
List<AuditEventFailReport> failedEvents; 
List<AuditEvent> sentEvents;
Each AuditEventFailReport contains the failed event, a FailReport status code, and a failure description.
If the result is failure, the FailReport object contains one of the following values for both client types:
  • BAD_ACK: NACK was received. The description contains the ACK details..
  • NO_ACK: no ACK was received after maximal retry attempts was made.
  • CACHE_IS_FULL: the Audit cache is full and the event was dropped.

Asynchronous Audit Client

Before creating the auditClient, you need to create an AuditConfiguration. The AuditConfiguration can be constructed either in an automatic or manual methods:

Automatic AuditConfiguration Creation

Automatic creation requires that your application is bound to the predix-audit service instance. It also requires to set the following environment variables in your application

  • AUDIT_SERVICE_NAME: The name of AuditService in the cf marketplace.
  • AUDIT_UAA_URL: https://<YOUR_UAA_ID>.predix-uaa.run.aws-usw02-dev.ice.predix.io/oauth/token.
  • AUDIT_UAA_CLIENT_ID: The UAA client for Audit Service.
  • AUDIT_UAA_CLIENT_SECRET: The UAA secret of the client.
The following is an example of the manifest.yml file:
  ---
    applications:
    - name: my-auditing-applcation
      instances: 1
      services:
        - my-audit-service
      env:
        AUDIT_SERVICE_NAME: predix-audit
        AUDIT_UAA_URL: https://2e6f8552-acb2-4d96-b470-0d44fe8cd33b.predix-uaa.run.asv-pr.ice.predix.io/oauth/token
        AUDIT_UAA_CLIENT_ID: client
        AUDIT_UAA_CLIENT_SECRET: secret
Additional optional parameters can be supplied via VCAP to control the client configuration:
  • AUDIT_MAX_RETRY_COUNT: The number of attempts made to resend a failed audit message from the client application to the Audit service.
    • Valid values: 0-5. default: 2.
  • AUDIT_RETRY_INTERVAL_MILLIS: The amount of time in milliseconds between each retry attempt.
    • Valid values: 2,000 - 20,000 (2 sec - 20 sec). default - 10,000.
  • AUDIT_MAX_CACHED_EVENTS: The maximum number of events cached im memory, waiting to be sent.
    • Default: 50,000. minimum value is 1000.
  • AUDIT_RECONNECT_POLICY: Controls whether the Audit client attempts a reconnect when disconnected.
    • Valid values: MANUAL, AUTOMATIC. default: AUTOMATIC - no reconnect attempt is made

The AuditConfiguration is automatically initialized from the VCAP, as follows:

private VcapLoaderServiceImpl vcapLoaderService = new VcapLoaderServiceImpl();
private AuditConfiguration auditConfiguration = vcapLoaderService.getConfigFromVcap();

AuditClient Creation

Creating an Auditclient requires both AuditConfiguration and AuditCallback.
AuditClient<AuditEventV2> auditClient = new AuditClient<>(configuration , callback)

Audit Results

The results of the audit operation, as well as other client related information, are propagated via AuditCallback. 
public AuditCallback<AuditEventV2> auditCallback(){
    return new AuditCallback<AuditEvent>() {
 
        @Override
        public void onFailure(Result<AuditEventV2> result) {
            log.info("onFailure : \n {} ", result);
        }
 
        @Override
        public void onClientError(ClientErrorCode clientErrorCode, String description) {
            log.info("onClientError {} \n {}", clientErrorCode, description);
        }
 
        @Override
        public void onSuccess(List<AuditEventV2> events)
            log.info("onSuccees {}", auditEvent);
        }
    };
}

onFailure callback - failed events indication

Result - contains a collection of failed events and additional failure related information for each event.
  • AuditEvent
  • FailCode
    • 'BAD_ACK' - NACK was received. The description contains the ack details.
    • 'NO_ACK' - no ACK was received after max retry attempts was made.
    • 'CACHE_IS_FULL' - the Audit cache is full and the event had to be dropped.
    • 'NO_MORE_RETRY' - Only when Routing Audit Client shutdown specific tenant Audit Client but there are remaining events that were not audited.
  • Description.
  • Throwable.

onClientError callback - client general error indication

ClientErrorCode indicates the type of error encountered initializing or operating the audit routing client.

When callback returned (i.e. onClientError(clientErrorCode, description, auditServiceId, tenantUuid)) it can take one of the following values:
  • 'STREAM_IS_CLOSED' - Failed to connect to destination audit repository.
  • 'AUTHENTICATION_FAILURE' - Failed to authenticate with the configured identity provider.
  • 'RECONNECT_FAILURE' - Failed to reconnect according to the configured reconnect strategy.

Reconnect Option

Due to various reasons, the audit client may be disconnected. When it happens, an onFailure callback with FailReport.STREAM_IS_CLOSE is received (only in ASYNC mode). The AuditSDK reconnects by one of two methods:
  • MANUAL - the auditClient.reconnect() API should be manually performed to re-establish communication.
  • AUTOMATIC (default) - no API call is needed. The SDK automatically attempts to reconnect until the connection is restored.
    AuditConfiguration.builder()
    .reconnectMode(ReconnectMode.AUTOMATIC)
    .build()

Authentication Token

The SDK supports two modes of authentication:
  • Using an UAA user and password. Use the AuditConfiguration.builder() to obtain a regular, UAA based configuration.
  • Using an authentication token. Use the AuditConfiguration.builderWithAuthToken() to obtain an OAuth token-based configuration. .

Once a client was created, its authentication mode cannot be changed. When working with an authentication token, you might need to refresh the token due to its validity. This can be achieved by running the auditClient.setAuthToken(token) API. Note that the API throws IllegalStateException if it is executed on a client configured with UAA authentication mode.

Debug Flag

You can enable the audit log level to debug by setting the following environment variable: 
AUDIT_DEBUG_ENABLED: true

Tracing Abilities

The SDK audits a marked message once every few minutes. The message is not sent to your database and is used for debugging purposes. This feature may be disabled in the following configuration:
AuditConfiguration.builder()
    .traceEnabled(false)
    .build()

Audit Client with TMS

Refer to this section, if you are using TMS to store Audit credentials for tenants. This client wraps other asynchronous clients and "route" Audit Events to appropriate Audit instance by tenantUuid.

The client is responsible for:
  1. Verify for each tenant if it was on-boarded with dedicated Audit instance or not.
  2. Fetch Audit Credentials from TMS.
  3. Fetch publisher token from the Token Service.
  4. Publish messages on the behalf of the origin name that should be mapped to application name.

Routing Audit Configuration

The RoutingAuditConfiguration exposes provisioning parameters of the audit client. RoutingAuditConfiguration can be constructed manually or automatically.

Automatic Creation

Use the VcapLoaderServiceImpl to automatically create your configuration

private VcapLoaderServiceImpl vcapLoaderService = new VcapLoaderServiceImpl();
private RoutingAuditConfiguration routingAuditConfiguration = vcapLoaderService.getRoutingConfigFromVcap();
Automatic mode requires that the application is bound to the predix-audit service instance. It also requires to set the following environment variables in the application:
  • AUDIT_SERVICE_NAME: The name of the AuditService in the cf marketplace.
  • AUDIT_UAA_URL: https://.predix-uaa.run.aws-usw02-dev.ice.predix.io/oauth/token.
  • AUDIT_UAA_CLIENT_ID: The UAA client for Audit Service.
  • AUDIT_UAA_CLIENT_SECRET: The UAA secret of above client.
  • AUDIT_SYSTEM_TRUSTED_ISSUER: https://.predix-uaa.run.aws-usw02-dev.ice.predix.io (TMS/STUF UAA instance)
  • AUDIT_APP_NAME_CLIENT_ID: The UAA client that contains stuf.app.<origin>, it is required in order to call TMS
  • AUDIT_SYSTEM_CLIENT_ID: The UAA client of STUF/TMS, this is required to fetch a token from Token Service
  • AUDIT_SYSTEM_CLIENT_SECRET: The UAA secret of above client.
  • AUDIT_TMS_URL: The URL of TMS
  • AUDIT_TOKEN_SERVICE_URL: The URL of tokenService.
The following is an example of the mainfest.yml file:
applications:
    - name: my-auditing-application
      instances: 1
      services:
        - my-audit-service
      env:
        AUDIT_SERVICE_NAME: predix-audit
        AUDIT_UAA_URL: https://.predix-uaa.run.aws-usw02-dev.ice.predix.io/oauth/token
        AUDIT_UAA_CLIENT_ID: client
        AUDIT_UAA_CLIENT_SECRET: secret
        AUDIT_APP_NAME_CLIENT_ID: feature_and_app_client
        AUDIT_APP_NAME_CLIENT_SECRET: secret_feature
        AUDIT_SYSTEM_CLIENT_ID: stuf-client
        AUDIT_SYSTEM_CLIENT_SECRET: stuf-secret
        AUDIT_SYSTEM_TRUSTED_ISSUER: https://.predix-uaa.run.aws-usw02-dev.ice.predix.io/oauth/token
        AUDIT_TMS_URL: https://tenancy-stuf.run.aws-usw02-dev.ice.predix.io
        AUDIT_TOKEN_SERVICE_URL: https://token-service-stuf.run.aws-usw02-dev.ice.predix.io
The following optional parameters can be supplied through VCAP to control the client configuration:
  • AUDIT_ROUTING_NUM_OF_CONNECTIONS: The maximum number of tenant's dedicated audit client that cached in memory.
    • Default: 100. Minimum value is 3. This value must be higher than the actual number of tenants with a dedicated Audit instance in TMS
  • AUDIT_ROUTING_MAX_CONCURRENT_REQUESTS: The maximum audit requests (single audit events or list of audit events) that could be pending in Routing Audit Client queue.
    • Default: 150000. Minimum value is 100.
Manual Creation
RoutingAuditConfiguration config = RoutingAuditConfiguration.builder()
                .appNameConfig(AppNameConfig.builder() //Application token configuration
                        .clientId(appClientId) //Application (feature) token client
                        .clientSecret(appClientId) //Application (feature) token secret
                        .uaaUrl(systemUaaUrl) //TMS UAA URI
                        .build())
                .sharedAuditConfig(SharedAuditConfig.builder() //Shared Audit instance configuration
                        .ehubUrl(sharedEhUrl) //Shared Audit instance eventhub URL
                        .ehubZoneId(sharedEhZoneId) //Shared Audit instance eventhub Zone
                        .auditZoneId(sharedAuditZoneId) //Shared Audit instance Zone
                        .uaaClientId(sharedAuditUaaClientId) //Shared Audit instance UAA client
                        .uaaClientSecret(sharedAuditUaaClientSecret) //Shared Audit instance UAA client secret
                        .uaaUrl(sharedAuditUaaUrl) //Shared Audit instance UAA url including /oauth/token suffix
                        .tracingToken(tracingToken) //Can be found in Audit Binding credentials, if tracing is not enabled then this configuration is not needed
                        .tracingUrl(urlOfTracing) //Can be found in Audit Binding credentials, if tracing is not enabled then this configuration is not needed
                        .build())
                .systemConfig(SystemConfig.builder() //System and STUF configuration
                        .clientId(tokenServiceClientId) //tokenService (STUF/TMS) UAA client id 
                        .clientSecret(tokenServiceClientSecret) //tokenService (STUF/TMS) UAA client secret
                        .tokenServiceUrl(tokenServiceUrl) //URL of tokenService, can be found in STUF binding credentials
                        .tmsUrl(tmsUrl) //URL of TMS
                        .build())
                .tenantAuditConfig(TenantAuditConfig.builder().build())
                .build();

Routing AuditClient

Audit Routing Client requires RoutingAuditConfiguration and RoutingAuditCallback: RoutingAuditClient<AuditEventV2> auditClient = new RoutingAuditClient<>(configuration , callback).

Publishing Audit Events

To publish an event, the usercan use the auditClient.audit(AuditEvent) or auditClient.audit(List<AuditEvent>). The following code sample is an example:
AuditEvent eventV2 = AuditEventV2.builder()
    .payload("This is test payload")
    .classifier(AuditEnums.Classifier.FAILURE)
    .publisherType(AuditEnums.PublisherType.APP_SERVICE)   
    .categoryType(AuditEnums.CategoryType.API_CALLS)      
    .eventType(AuditEnums.EventType.FAILURE_API_REQUEST)
    .tenantUuid(UUID.randomUUID().toString())      
    .correlationId(UUID.randomUUID().toString())
    .build()
 
auditClient.audit(eventV2);
Note: Additional "appName" field is added during the publish process and recieves the origin value, whereis origin is defined as the suffix of the stuf.app.<origin> scope from application token.

Routing Audit Calllback

The results of the audit operation, as well as other client related info are propagated through the RoutingAuditCallback. You should implement the RoutingAuditCallback interface and supply it to the auditClient with the implementation. 
RoutingAuditCallback<AuditEventV2> callback = new RoutingAuditCallback<AuditEventV2>() {
    @Override
    public void onFailure(Result<AuditEventV2> result) {
    //Collection of Audit events was not sent
     log.info("onFailure : \n {} ", result);
    }
  
    @Override
    public void onClientError(ClientErrorCode clientErrorCode, String description, String auditServiceId, @Nullable String tenantUuid) {
     //General error that may point to tenant configuration problem.
     //For shared audit instance the tenant is null since it is out of tenant
        log.info("onClientError {} \n {} auditServiceId {} tenant {}", clientErrorCode, description, auditServiceId, tenantUuid);
    }
  
    @Override
    public void onSuccess(List<AuditEventV2> auditEvents) {
     log.info("onSuccess {}", auditEvents);
    }
};

onFailure callback - failed events indication

Result - contains a collection of failed events and additional failure related information for each event.
  • AuditEvent
  • FailCode
    • 'BAD_ACK' - NACK was received. The description contains the ack details.
    • 'NO_ACK' - no ACK was received after max retry attempts was made.
    • 'CACHE_IS_FULL' - the Audit cache is full and the event had to be dropped.
    • 'CLIENT_INITIALIZATION_ERROR' - Routing Audit Client failed to initialize audit client for specific tenant, it could be related to TMS configuration issues.
    • 'NO_MORE_RETRY' - Only when Routing Audit Client shutdown specific tenant Audit Client but there are remaining events that were not audited.
    • AUTHENTICATION_FAILURE' - Indicate that token that was previously fetched from the token service lake of needed scopes, this could be related to TMS configuration problem, the SDK tries to fetch a new token from TMS token service automatically.
  • Description.
  • Throwable.

onClientError callback - client general error indication

ClientErrorCode indicates the type of error encountered initializing or operating the audit routing client.

When callback returned (i.e. onClientError(clientErrorCode, description, auditServiceId, tenantUuid)) it can take one of the following values:
  • 'STREAM_IS_CLOSED' - Failed to connect to destination audit repository.
  • 'AUTHENTICATION_FAILURE' - Failed to authenticate with the configured identity provider.
  • 'RECONNECT_FAILURE' - Failed to reconnect according to the configured reconnect strategy.

Debug Flag

You can enable the audit log level to debug by setting the following environment variable: 
AUDIT_DEBUG_ENABLED: true

Version 1.3.1

Add the following dependency to the maven pom XML file:
<dependency>
      <groupId>com.ge.predix.audit</groupId>
      <artifactId>audit-sdk</artifactId>
      <version>1.3.1</version>
</dependency>

Supported Audit Clients

Audit SDK supports two types of clients:
  1. Multi-tenancy backed by a single audit service instance (previous mode of AuditSDK).
    • Synchronized Audit Client
    • Asynchronous Audit Client.
  2. Multi-tenancy backed by an Audit Service instance per TMS tenant.
    • Audit Client with TMS.

Synchronous Audit Client

Before creating the auditClient, you need to create an AuditConfiguration. The AuditConfiguration can be constructed either in an automatic or manual methods:

Automatic AuditConfiguration Creation

Automatic creation requires that your application is bound to the predix-audit service instance. It also requires to set the following environment variables in your application

  • AUDIT_SERVICE_NAME: The name of AuditService in the cf marketplace.
  • AUDIT_UAA_URL: https://<YOUR_UAA_ID>.predix-uaa.run.aws-usw02-dev.ice.predix.io/oauth/token.
  • AUDIT_UAA_CLIENT_ID: The UAA client for Audit Service.
  • AUDIT_UAA_CLIENT_SECRET: The UAA secret of the client.
The following is an example of the manifest.yml file:
  ---
    applications:
    - name: my-auditing-applcation
      instances: 1
      services:
        - my-audit-service
      env:
        AUDIT_SERVICE_NAME: predix-audit
        AUDIT_UAA_URL: https://2e6f8552-acb2-4d96-b470-0d44fe8cd33b.predix-uaa.run.asv-pr.ice.predix.io/oauth/token
        AUDIT_UAA_CLIENT_ID: client
        AUDIT_UAA_CLIENT_SECRET: secret
Additional optional parameters can be supplied via VCAP to control the client configuration:
  • AUDIT_MAX_RETRY_COUNT: The number of attempts made to resend a failed audit message from the client application to the Audit service.
    • Valid values: 0-5. default: 2.
  • AUDIT_RETRY_INTERVAL_MILLIS: The amount of time in milliseconds between each retry attempt.
    • Valid values: 2,000 - 20,000 (2 sec - 20 sec). default - 10,000.
  • AUDIT_MAX_CACHED_EVENTS: The maximum number of events cached im memory, waiting to be sent.
    • Default: 50,000. minimum value is 1000.
  • AUDIT_RECONNECT_POLICY: Controls whether the Audit client attempts a reconnect when disconnected.
    • Valid values: MANUAL, AUTOMATIC. default: MANUAL - no reconnect attempt is made

The AuditConfiguration is automatically initialized from the VCAP, as follows:

private VcapLoaderServiceImpl vcapLoaderService = new VcapLoaderServiceImpl();
private AuditConfiguration auditConfiguration = vcapLoaderService.getConfigFromVcap();

Manual AuditConfiguration Creation

The user can use one of the AuditConfiguration builders to manually create the AuditConfiguration. The following builders are available:
  • AuditConfigurationBuilder (AuditConfiguration.builder()) to create a client with a UAA user / password for authentication.
  • AuditConfigurationWithAuthTokenBuilder (AuditConfiguration.builderWithAuthToken()) to create a client with an OAuth token. 
    AuditConfiguration sdkConfig =  AuditConfiguration.builder()
        .bulkMode(true)
        .uaaUrl(uaaUrl)
        .uaaClientId(uaaClientId)
        .uaaClientSecret(uaaClientSecret)
        .ehubZoneId(ehubZoneId)
        .ehubHost(ehubHost)
        .ehubPort(ehubPort)
        .build();

AuditClient Creation

Auditclients Client requires only AuditConfiguration.
AuditClientSync auditClientSync = new AuditClientSync(sdkConfig);

Audit Events Publishing

To publish an event, you can use the auditClient.audit(AuditEvent) or auditClient.audit(List<AuditEvent>). For example:
AuditEvent eventV2 = AuditEventV2.builder()
      .payload("This is test payload")
      .classifier(AuditEnums.Classifier.FAILURE) 
      .publisherType(AuditEnums.PublisherType.APP_SERVICE)    
      .categoryType(AuditEnums.CategoryType.API_CALLS)       
      .eventType(AuditEnums.EventType.FAILURE_API_REQUEST)
      .tenantUuid(UUID.randomUUID().toString())       
      .correlationId(UUID.randomUUID().toString())
      .build()

auditClient.audit(eventV2);

Audit Results

The results of the audit operation are returned with the AuditingResult object. It contains the following elements: 
List<AuditEventFailReport> failedEvents; 
List<AuditEvent> sentEvents;
Each AuditEventFailReport contains the failed event, a FailReport status code, and a failure description.
If the result is failure, the FailReport object contains one of the following values for both client types:
  • BAD_ACK: NACK was received. The description contains the ACK details..
  • NO_ACK: no ACK was received after maximal retry attempts was made.
  • CACHE_IS_FULL: the Audit cache is full and the event was dropped.

Asynchronous Audit Client

Before creating the auditClient, you need to create an AuditConfiguration. The AuditConfiguration can be constructed either in an automatic or manual methods:

Automatic AuditConfiguration Creation

Automatic creation requires that your application is bound to the predix-audit service instance. It also requires to set the following environment variables in your application

  • AUDIT_SERVICE_NAME: The name of AuditService in the cf marketplace.
  • AUDIT_UAA_URL: https://<YOUR_UAA_ID>.predix-uaa.run.aws-usw02-dev.ice.predix.io/oauth/token.
  • AUDIT_UAA_CLIENT_ID: The UAA client for Audit Service.
  • AUDIT_UAA_CLIENT_SECRET: The UAA secret of the client.
The following is an example of the manifest.yml file:
  ---
    applications:
    - name: my-auditing-applcation
      instances: 1
      services:
        - my-audit-service
      env:
        AUDIT_SERVICE_NAME: predix-audit
        AUDIT_UAA_URL: https://2e6f8552-acb2-4d96-b470-0d44fe8cd33b.predix-uaa.run.asv-pr.ice.predix.io/oauth/token
        AUDIT_UAA_CLIENT_ID: client
        AUDIT_UAA_CLIENT_SECRET: secret
Additional optional parameters can be supplied via VCAP to control the client configuration:
  • AUDIT_MAX_RETRY_COUNT: The number of attempts made to resend a failed audit message from the client application to the Audit service.
    • Valid values: 0-5. default: 2.
  • AUDIT_RETRY_INTERVAL_MILLIS: The amount of time in milliseconds between each retry attempt.
    • Valid values: 2,000 - 20,000 (2 sec - 20 sec). default - 10,000.
  • AUDIT_MAX_CACHED_EVENTS: The maximum number of events cached im memory, waiting to be sent.
    • Default: 50,000. minimum value is 1000.
  • AUDIT_RECONNECT_POLICY: Controls whether the Audit client attempts a reconnect when disconnected.
    • Valid values: MANUAL, AUTOMATIC. default: AUTOMATIC - no reconnect attempt is made

The AuditConfiguration is automatically initialized from the VCAP, as follows:

private VcapLoaderServiceImpl vcapLoaderService = new VcapLoaderServiceImpl();
private AuditConfiguration auditConfiguration = vcapLoaderService.getConfigFromVcap();

AuditClient Creation

Creating an Auditclient requires both AuditConfiguration and AuditCallback.
AuditClient auditClient = new AuditClient(configuration , callback)

Audit Results

The results of the audit operation, as well as other client related information, are propagated via AuditCallback. 
public AuditCallback auditCallback(){
    return new AuditCallback() {
        @Override
        public void onValidate(AuditEvent auditEvent, List<ValidatorReport> list) {
            log.info("onValidate {}", list);
        }
 
        @Override
        public void onFailure(AuditEvent auditEvent, FailReport failReport, String description) {
            log.info("onFailure {} \n {} \n {}", failReport, auditEvent, description);
        }
 
        @Override
        public void onFailure(FailReport failReport, String description) {
            log.info("onFailure {} \n {}", failReport, description);
        }
 
        @Override
        public void onSuccees(AuditEvent auditEvent) {
            log.info("onSuccees {}", auditEvent);
        }
    };
}
FailReport indicates the type of error encountered. When returned with an event (i.e. onFailure(event, failReport, description) ) it can take one of the following values.
  • 'BAD_ACK' - NACK was received. The description contains the ack details.
  • 'NO_ACK' - no ACK was received after max retry attempts was made.
  • 'CACHE_IS_FULL' - the Audit cache is full and the event had to be dropped.
  • 'STREAM_IS_CLOSE' - the Audit client is disconnected.AuditEvent.

Reconnect Option

Due to various reasons, the audit client may be disconnected. When it happens, an onFailure callback with FailReport.STREAM_IS_CLOSE is received (only in ASYNC mode). The AuditSDK reconnects by one of two methods:
  • MANUAL (default) - the auditClient.reconnect() API should be manually performed to re-establish communication.
  • AUTOMATIC - no API call is needed. The SDK automatically attempts to reconnect until the connection is restored.
    AuditConfiguration.builder()
    .reconnectMode(ReconnectMode.AUTOMATIC)
    .build()

Authentication Token

The SDK supports two modes of authentication:
  • Using an UAA user and password. Use the AuditConfiguration.builder() to obtain a regular, UAA based configuration.
  • Using an authentication token. Use the AuditConfiguration.builderWithAuthToken() to obtain an OAuth token-based configuration. .

Once a client was created, its authentication mode cannot be changed. When working with an authentication token, you might need to refresh the token due to its validity. This can be achieved by running the auditClient.setAuthToken(token) API. Note that the API throws IllegalStateException if it is executed on a client configured with UAA authentication mode.

Debug Flag

You can enable the audit log level to debug by setting the following environment variable: 
AUDIT_DEBUG_ENABLED: true

Tracing Abilities

The SDK audits a marked message once every few minutes. The message is not sent to your database and is used for debugging purposes. This feature may be disabled in the following configuration:
AuditConfiguration.builder()
    .traceEnabled(false)
    .build()

Audit Client with TMS

Refer to this section, if you are using TMS to store Audit credentials for tenants. This client wraps other asynchronous clients and "route" Audit Events to appropriate Audit instance by tenantUuid.

The client is responsible for:
  1. Verify for each tenant if it was on-boarded with dedicated Audit instance or not.
  2. Fetch Audit Credentials from TMS.
  3. Fetch publisher token from the Token Service.
  4. Publish messages on the behalf of the origin name that should be mapped to application name.

Routing Audit Configuration

The RoutingAuditConfiguration exposes provisioning parameters of the audit client. RoutingAuditConfiguration can be constructed manually or automatically.

Automatic Creation

Use the VcapLoaderServiceImpl to automatically create your configuration

private VcapLoaderServiceImpl vcapLoaderService = new VcapLoaderServiceImpl();
private RoutingAuditConfiguration routingAuditConfiguration = vcapLoaderService.getRoutingConfigFromVcap();
Automatic mode requires that the application is bound to the predix-audit service instance. It also requires to set the following environment variables in the application:
  • AUDIT_SERVICE_NAME: The name of the AuditService in the cf marketplace.
  • AUDIT_UAA_URL: https://.predix-uaa.run.aws-usw02-dev.ice.predix.io/oauth/token.
  • AUDIT_UAA_CLIENT_ID: The UAA client for Audit Service.
  • AUDIT_UAA_CLIENT_SECRET: The UAA secret of above client.
  • AUDIT_SYSTEM_TRUSTED_ISSUER: https://.predix-uaa.run.aws-usw02-dev.ice.predix.io (TMS/STUF UAA instance)
  • AUDIT_APP_NAME_CLIENT_ID: The UAA client that contains stuf.app.<origin>, it is required in order to call TMS
  • AUDIT_SYSTEM_CLIENT_ID: The UAA client of STUF/TMS, this is required to fetch a token from Token Service
  • AUDIT_SYSTEM_CLIENT_SECRET: The UAA secret of above client.
  • AUDIT_TMS_URL: The URL of TMS
  • AUDIT_TOKEN_SERVICE_URL: The URL of tokenService.
The following is an example of the mainfest.yml file:
applications:
    - name: my-auditing-application
      instances: 1
      services:
        - my-audit-service
      env:
        AUDIT_SERVICE_NAME: predix-audit
        AUDIT_UAA_URL: https://.predix-uaa.run.aws-usw02-dev.ice.predix.io/oauth/token
        AUDIT_UAA_CLIENT_ID: client
        AUDIT_UAA_CLIENT_SECRET: secret
        AUDIT_APP_NAME_CLIENT_ID: feature_and_app_client
        AUDIT_APP_NAME_CLIENT_SECRET: secret_feature
        AUDIT_SYSTEM_CLIENT_ID: stuf-client
        AUDIT_SYSTEM_CLIENT_SECRET: stuf-secret
        AUDIT_SYSTEM_TRUSTED_ISSUER: https://.predix-uaa.run.aws-usw02-dev.ice.predix.io/oauth/token
        AUDIT_TMS_URL: https://tenancy-stuf.run.aws-usw02-dev.ice.predix.io
        AUDIT_TOKEN_SERVICE_URL: https://token-service-stuf.run.aws-usw02-dev.ice.predix.io
The following optional parameters can be supplied through VCAP to control the client configuration:
  • AUDIT_ROUTING_NUM_OF_CONNECTIONS: The maximum number of tenant's dedicated audit client that cached in memory.
    • Default: 100. Minimum value is 3. This value must be higher than the actual number of tenants with a dedicated Audit instance in TMS
  • AUDIT_ROUTING_MAX_CONCURRENT_REQUESTS: The maximum audit requests (single audit events or list of audit events) that could be pending in Routing Audit Client queue.
    • Default: 150000. Minimum value is 100.
Manual Creation
RoutingAuditConfiguration config = RoutingAuditConfiguration.builder()
                .appNameConfig(AppNameConfig.builder() //Application token configuration
                        .clientId(appClientId) //Application (feature) token client
                        .clientSecret(appClientId) //Application (feature) token secret
                        .uaaUrl(systemUaaUrl) //TMS UAA URI
                        .build())
                .sharedAuditConfig(SharedAuditConfig.builder() //Shared Audit instance configuration
                        .ehubUrl(sharedEhUrl) //Shared Audit instance eventhub URL
                        .ehubZoneId(sharedEhZoneId) //Shared Audit instance eventhub Zone
                        .auditZoneId(sharedAuditZoneId) //Shared Audit instance Zone
                        .uaaClientId(sharedAuditUaaClientId) //Shared Audit instance UAA client
                        .uaaClientSecret(sharedAuditUaaClientSecret) //Shared Audit instance UAA client secret
                        .uaaUrl(sharedAuditUaaUrl) //Shared Audit instance UAA url including /oauth/token suffix
                        .tracingToken(tracingToken) //Can be found in Audit Binding credentials, if tracing is not enabled then this configuration is not needed
                        .tracingUrl(urlOfTracing) //Can be found in Audit Binding credentials, if tracing is not enabled then this configuration is not needed
                        .build())
                .systemConfig(SystemConfig.builder() //System and STUF configuration
                        .clientId(tokenServiceClientId) //tokenService (STUF/TMS) UAA client id 
                        .clientSecret(tokenServiceClientSecret) //tokenService (STUF/TMS) UAA client secret
                        .tokenServiceUrl(tokenServiceUrl) //URL of tokenService, can be found in STUF binding credentials
                        .tmsUrl(tmsUrl) //URL of TMS
                        .build())
                .tenantAuditConfig(TenantAuditConfig.builder().build())
                .build();

Routing AuditClient

Audit Routing Client requires RoutingAuditConfiguration and RoutingAuditCallback: RoutingAuditClient<AuditEventV2> auditClient = new RoutingAuditClient<>(configuration , callback).

Publishing Audit Events

To publish an event, the usercan use the auditClient.audit(AuditEvent) or auditClient.audit(List<AuditEvent>). The following code sample is an example:
AuditEvent eventV2 = AuditEventV2.builder()
    .payload("This is test payload")
    .classifier(AuditEnums.Classifier.FAILURE)
    .publisherType(AuditEnums.PublisherType.APP_SERVICE)   
    .categoryType(AuditEnums.CategoryType.API_CALLS)      
    .eventType(AuditEnums.EventType.FAILURE_API_REQUEST)
    .tenantUuid(UUID.randomUUID().toString())      
    .correlationId(UUID.randomUUID().toString())
    .build()
 
auditClient.audit(eventV2);
Note: Additional "appName" field is added during the publish process and recieves the origin value, whereis origin is defined as the suffix of the stuf.app.<origin> scope from application token.

Routing Audit Calllback

The results of the audit operation, as well as other client related info are propagated through the RoutingAuditCallback. You should implement the RoutingAuditCallback interface and supply it to the auditClient with the implementation. 
RoutingAuditCallback<AuditEventV2> callback = new RoutingAuditCallback<AuditEventV2>() {
    @Override
    public void onFailure(AuditEventV2 event, FailReport failReport, String description) {
    //Specific Audit Event was not sent
     log.info("onFailure {} \n {} \n {}", failReport, event, description);
    }
  
    @Override
    public void onFailure(FailReport failReport, String description, String auditServiceId, @Nullable String tenant) {
     //General error that may point to tenant configuration problem.
     //For shared audit instance the tenant is null since it is out of tenant
        log.info("onFailure {} \n {} \n auditServiceId {} tenant {}", failReport, description, auditServiceId, tenant);
    }
  
    @Override
    public void onSuccess(AuditEventV2 auditEvent) {
     log.info("onSuccess {}", auditEvent);
    }
};

FailReport indicates the type of error encountered.

When returned with an event (i.e. onFailure(event, failReport, description) ) it can take one of the following values

  • 'BAD_ACK' - NACK was received. The description contains the ack details.
  • 'NO_ACK' - no ACK was received after max retry attempts was made.
  • 'CACHE_IS_FULL' - the Audit cache is full and the event had to be dropped.
  • 'CLIENT_INITIALIZATION_ERROR' - Routing Audit Client failed to initialize audit client for specific tenant, it could be related to TMS configuration issues.
  • 'NO_MORE_RETRY' - Only when Routing Audit Client shutdown specific tenant Audit Client but there are remaining events that were not audited.
  • 'AUTHENTICATION_FAILURE' - Indicate that token that was previously fetched from the token service lake of needed scopes, this could be related to TMS configuration problem, the SDK tries to fetch a new token from TMS token service automatically.

Debug Flag

You can enable the audit log level to debug by setting the following environment variable: 
AUDIT_DEBUG_ENABLED: true

Version 1.0.3

Add the following dependency to the maven pom XML file:
<dependency>
      <groupId>com.ge.predix.audit</groupId>
      <artifactId>audit-sdk</artifactId>
      <version>1.0.3</version>
</dependency>
An AuditConfiguration can be constructed either in an automatic or manual methods:

Automatic AuditConfiguration Creation

Automatic creation requires that your application is bound to the predix-audit service instance. It also requires to set the following environment variables in your application

  • AUDIT_SERVICE_NAME: The name of AuditService in the cf marketplace.
  • AUDIT_UAA_URL: https://<YOUR_UAA_ID>.predix-uaa.run.aws-usw02-dev.ice.predix.io/oauth/token.
  • AUDIT_UAA_CLIENT_ID: The UAA client for Audit Service.
  • AUDIT_UAA_CLIENT_SECRET: The UAA secret of the client.
The following is an example of the manifest.yml file:
  ---
    applications:
    - name: my-auditing-applcation
      instances: 1
      services:
        - my-audit-service
      env:
        AUDIT_SERVICE_NAME: predix-audit
        AUDIT_UAA_URL: https://2e6f8552-acb2-4d96-b470-0d44fe8cd33b.predix-uaa.run.asv-pr.ice.predix.io/oauth/token
        AUDIT_UAA_CLIENT_ID: client
        AUDIT_UAA_CLIENT_SECRET: secret
Additional optional parameters can be supplied via VCAP to control the client configuration:
  • AUDIT_MAX_RETRY_COUNT: The number of attempts made to resend a failed audit message from the client application to the Audit service.
    • Valid values: 0-5. default: 2.
  • AUDIT_RETRY_INTERVAL_MILLIS: The amount of time in milliseconds between each retry attempt.
    • Valid values: 2,000 - 20,000 (2 sec - 20 sec). default - 10,000.
  • AUDIT_MAX_CACHED_EVENTS: The maximum number of events cached im memory, waiting to be sent.
    • Default: 50,000. minimum value is 1000.
  • AUDIT_RECONNECT_POLICY: Controls whether the Audit client attempts a reconnect when disconnected.
    • Valid values: MANUAL, AUTOMATIC. default: MANUAL - no reconnect attempt is made

The AuditConfiguration is automatically initialized from the VCAP, as follows:

private VcapLoaderServiceImpl vcapLoaderService = new VcapLoaderServiceImpl();
private AuditConfiguration auditConfiguration = vcapLoaderService.getConfigFromVcap();

Manual AuditConfiguration Creation

The user can use one of the AuditConfiguration builders to manually create the AuditConfiguration. The following builders are available:
  • AuditConfigurationBuilder (AuditConfiguration.builder()) to create a client with a UAA user / password for authentication.
  • AuditConfigurationWithAuthTokenBuilder (AuditConfiguration.builderWithAuthToken()) to create a client with an OAuth token.

AuditClient Creation

You can create two types of Auditclients:
  • Synchronous (Sync) Client - requires AuditConfiguration only.
  • Asynchronous (Async) Client - requires both AuditConfiguration and AuditCallback.
Create the client according to the required mode
  • Sync Client:
    AuditClientSync auditClientSync = new AuditClientSync(sdkConfig);
  • Async Client:
    AuditClient auditClient = new AuditClient(configuration , callback)
Note: Be aware that AuditClientType is now deprecated and should not be used to indicate the client mode.
Audit Results
  • Async Client
The results of the audit operation, as well as other client related information, are propagated via AuditCallback. 
public AuditCallback auditCallback(){
          return new AuditCallback() {
              @Override
              public void onValidate(AuditEvent auditEvent, List<ValidatorReport> list) {
                  log.info("onValidate {}", list);
              }

              @Override
              public void onFailure(AuditEvent auditEvent, FailReport failReport, String description) {
                  log.info("onFailure {} \n {} \n {}", failReport, auditEvent, description);
              }

              @Override
              public void onFailure(FailReport failReport, String description) {
                  log.info("onFailure {} \n {}", failReport, description);
              }

              @Override
              public void onSuccees(AuditEvent auditEvent) {
                  log.info("onSuccees {}", auditEvent);
              }
          };
      }
  • Sync Client:
The results of the audit operation are returned with the AuditingResult object. It contains the following elements: 
List<AuditEventFailReport> failedEvents; 
List<AuditEvent> sentEvents;
Each AuditEventFailReport contains the failed event, a FailReport status code, and a failure description.
If the result is failure, the FailReport object contains one of the following values for both client types:
  • BAD_ACK: NACK was received. The description contains the ACK details..
  • NO_ACK: no ACK was received after maximal retry attempts was made.
  • CACHE_IS_FULL: the Audit cache is full and the event was dropped.

Reconnect Option

Due to various reasons, the audit client may be disconnected. When it happens, an onFailure callback with FailReport.STREAM_IS_CLOSE is received (only in ASYNC mode). The AuditSDK reconnects by one of two methods:
  • MANUAL (default) - the auditClient.reconnect() API should be manually performed to re-establish communication.
  • AUTOMATIC- no API call is needed. The SDK automatically attempts to reconnect until the connection is restored.
    AuditConfiguration.builder()
    .reconnectMode(ReconnectMode.AUTOMATIC)
    .build()

Authentication Token

The SDK supports two modes of authentication:
  • Using an UAA user and password. Use the AuditConfiguration.builder() to obtain a regular, UAA based configuration.
  • Using an authentication token. Use the AuditConfiguration.builderWithAuthToken() to obtain an OAuth token-based configuration. .

Once a client was created, its authentication mode cannot be changed. When working with an authentication token, you might need to refresh the token due to its validity. This can be achieved by running the auditClient.setAuthToken(token) API. Note that the API throws IllegalStateException if it is executed on a client configured with UAA authentication mode.

Auditing Application Name

When building an auditEvent (V2 and higher), you can add an Auditing Application Name. This is a friendly name that can take a String up to 100 characters.
AuditConfiguration.builder()
 .appName("application name")
 .build()

If the APPLICATION_NAME variable was set in the environment, it is added to each message and there is no need to explicitly provide it when building the message.

Debug Flag

You can enable the audit log level to debug by setting the following environment variable: 
AUDIT_DEBUG_ENABLED: true

Tracing Abilities

The SDK audits a marked message once every few minutes. The message is not sent to your database and is used for debugging purposes. This feature may be disabled in the following configuration:
AuditConfiguration.builder()
    .traceEnabled(false)
    .build()
Note: To retain data integrity, the user is required to sign each audit event message with a digital signature (e.g., RSA PKI) and the Predix Audit Service Query API should verify that the signature is valid. The digital signature should be owned and maintained by the customer and used within the message payload field to uniquely identify the original message.