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
Results
Your UAA instance is created with the following specifications:
- A client identifier (
admin
).Note: Anadmin
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
Results
Your UAA instance is created with the following specification:
-
A client identifier (
admin
).Note: Anadmin
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
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
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
Updating the OAuth2 Clients to use the Predix Audit Service
Before You Begin
Procedure
"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"
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
Version 2.0.0
<dependency>
<groupId>com.ge.predix.audit</groupId>
<artifactId>audit-sdk</artifactId>
<version>2.0.0</version>
</dependency>
Supported Audit Clients
- Multi-tenancy backed by a single audit service instance (previous mode of AuditSDK).
- Synchronized Audit Client
- Asynchronous Audit Client.
- 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.
---
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
- 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
- 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
AuditClientSync<AuditEventV2> auditClientSync = new AuditClientSync<>(auditConfiguration);
Audit Events Publishing
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
List<AuditEventFailReport> failedEvents;
List<AuditEvent> sentEvents;
Each AuditEventFailReport contains the failed event, a FailReport status code, and a failure description. - 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.
---
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
- 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
AuditClient<AuditEventV2> auditClient = new AuditClient<>(configuration , callback)
Audit Results
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
- 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.
- '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
- 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
- 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
AUDIT_DEBUG_ENABLED: true
Tracing Abilities
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.
- Verify for each tenant if it was on-boarded with dedicated Audit instance or not.
- Fetch Audit Credentials from TMS.
- Fetch publisher token from the Token Service.
- 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();
- 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.
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
- 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.
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
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);
Routing Audit Calllback
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
- 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.
- '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
AUDIT_DEBUG_ENABLED: true
Version 1.3.1
<dependency>
<groupId>com.ge.predix.audit</groupId>
<artifactId>audit-sdk</artifactId>
<version>1.3.1</version>
</dependency>
Supported Audit Clients
- Multi-tenancy backed by a single audit service instance (previous mode of AuditSDK).
- Synchronized Audit Client
- Asynchronous Audit Client.
- 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.
---
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
- 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
- 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
AuditClientSync auditClientSync = new AuditClientSync(sdkConfig);
Audit Events Publishing
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
List<AuditEventFailReport> failedEvents;
List<AuditEvent> sentEvents;
Each AuditEventFailReport contains the failed event, a FailReport status code, and a failure description. - 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.
---
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
- 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
AuditClient auditClient = new AuditClient(configuration , callback)
Audit Results
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);
}
};
}
- '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
- 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
- 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
AUDIT_DEBUG_ENABLED: true
Tracing Abilities
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.
- Verify for each tenant if it was on-boarded with dedicated Audit instance or not.
- Fetch Audit Credentials from TMS.
- Fetch publisher token from the Token Service.
- 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();
- 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.
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
- 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.
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
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);
Routing Audit Calllback
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
AUDIT_DEBUG_ENABLED: true
Version 1.0.3
<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.
---
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
- 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
- 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
- Synchronous (Sync) Client - requires AuditConfiguration only.
- Asynchronous (Async) Client - requires both AuditConfiguration and AuditCallback.
- Sync Client:
AuditClientSync auditClientSync = new AuditClientSync(sdkConfig);
- Async Client:
AuditClient auditClient = new AuditClient(configuration , callback)
- Async Client
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:
List<AuditEventFailReport> failedEvents;
List<AuditEvent> sentEvents;
Each AuditEventFailReport contains the failed event, a FailReport status code, and a failure description. - 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
- 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
- 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
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
AUDIT_DEBUG_ENABLED: true
Tracing Abilities
AuditConfiguration.builder()
.traceEnabled(false)
.build()