Login
    Contents x
    Authentication
      • Dark
        Light
      Contents

      Authentication

        • Dark
          Light
        Article summary

        OAuth Token

        Any external application needs to connect with web socket sever to fetch the Performance Metrics data. To achieve this connection, follow the steps below:

        1. External application should authenticate with Acqueon IDP using the user credential and get the access token.

        2. Initiate the web socket connection request with below format,

          1. Web Socket Server Url –

            1. wss://PerformanceMetrics_<UserName>:<AccessToken>@<FQDN>:<PORT>/AEConsole?name=PerformanceMetrics_<UserName>

              1. UserName - Your application name.

              2. AccessToken - Retrieved from Acqueon IDP.

              3. FQDN – Fully qualified domain name of the user accessing the service.

              4. PORT – Web socket server port.

          2. Required headers – Authorization with the value of Basic Base64Encoded(PerformanceMetrics_<UserName>:<AcqueonIDPToken>)

        3. On expiry of the token, refresh from Acqueon IDP.

        Acquiring Token from Acqueon IDP

        To acquire the Acqueon IDP access token, provide the following information:

        1. Acqueon IDP Domain

        2. Acqueon IDP app Client ID

        3. Acqueon IDP external User Name and Password

        Follow an approach Proof Key for Code Exchange (PKCE) to acquire the Acqueon IDP token using Authorization Code Flow.

        Socket Connect

        You can send a request to access the Websocket with authentication as below:

        wss://PerformanceMetrics_<user>_<unixtimestamp>:base64(AccessToken)@<FQDN>:PortNumber/AEDataTransmitter?name=PerformanceMetrics_<user>_<unixtimestamp>

        Sample Request

        A sample request is reproduced below:

        wss://PerformanceMetrics_ACQ_1654268360:MTIzNDUtMTIxMjEyLTEyMTIxMi0xMjEyOjEyMzQ1LTEyMTIxLTIxMjEyLTEyMTItMTIy@dev.aecdevops.com:4747/AEDataTransmitter?name=PerformanceMetrics_ACQ_1654268360

        Sample Request Fields

        Field

        Description

        AccessToken

        An unique code that is used for authentication purpose. Encode the access token acquired from Acqueon IDP using a Base64 encode utility and use the encoded result in the request.

        WebsocketURL

        This is the Websocket URL and the Port.

        User

        The name of the user requesting access to the Websocket server.

        Unixtimestamp

        This is the unique date time field that prevents duplicate logins to the Websocket server.

        Note:

        Across multiple connections, unixtimestamp should be unique. Unixtimestamp is the number of seconds that have elapsed since the Unix epoch UTC 00:00:00 on January 1, 1970), excluding leap seconds. The uniqueness is maintained by adding a timestamp to the logged-in user. For example,

        'PerformanceMetrics_' + userName + '_' + unixtimestamp;

        Sample Response

        On successful connection, the client receives a connection event. See the response below:

        {
"Sender": "Server",
"Receiver": " PerformanceMetrics_ACQ_1654268360",
"MessageType": "OpenID",
"Data": "ec3df1f8b20b4d239354925276a7c989"
}

        Sample Response Fields

        Field

        Description

        Sender

        The service / component / server sending the response.

        Receiver

        The user receiving the response.

        Message Type

        This is the unique ID generated.  

        Data

        This is the Unique ID generated by the Websocket server.

        Initialization Request

        When the connection event is received, the client must send an initialization request as below:

        [WSEvent] Message: 
{
    "Sender": " PerformanceMetrics_ACQ_1654268360",
    "Receiver": "ATIRealTimeService",
    "MessageType": "AEPerformanceMetricInitialization",
    "Data": "{\"TimeZoneOffset\":-330,\"Sender\":\"PerformanceMetrics_ACQ_1654268360}"
}

        Initialization Request Fields

        Field

        Description

        Sender

        The client sending the packet.

        Receiver

        The receiver of the packet.

        Message Type

        The message type is AEPerformanceMetricInitialization.

        Data

        TimeZoneOffset

        This is the Time zone offset (from UTC) that the client is in.

        Sender

        The sender of the packet requesting for initialization. Use the same name you used previously when requesting the Websocket connection.

        Note:

        Send this initialization request only once after the client connects to the Websocket server.

        Socket Failure

        The connection to the Websocket server is established instantly upon a user’s request, and the authentication is carried out simultaneously. If the authentication fails, the connection established is closed. The failure could be due to a failed Acqueon IDP authentication. Regenerating the Acqueon IDP token should fix the authentication issue.

        Some other reasons for failure could be:

        1. A wrong Websocket URL sent by the client.

        2. The Websocket server may be down, preventing connection with the user.

        3. A firewall could have blocked access.

        Socket Disconnect

        The application checks for the connection to the Websocket at 5-second intervals. If there is a disconnect event on the client side, establish the reconnection immediately. On successful reconnection, the client has to send the initialization packet again.

        API Key and Secret Key

        The client uses any Websocket client credential(s) to connect to the Websocket URL. To connect and access, the client requires Websocket IP address, port, API key and the Secret key.

        You can generate the API Key and the Secret Key using the Campaign Manager application. Go to System Menu > API Keys to create new API keys.

        Note:

        Do store the API Key and the Secret Key when you generate them. You can also generate a fresh set of keys anytime.

        Socket Connect

        You can send a request to access the Websocket with authentication as below:

        wss://PerformanceMetrics_<user>_<unixtimestamp>:base64(apikey:secretkey)@<FQDN>:PortNumber/AEDataTransmitter?name=PerformanceMetrics_<user>_<unixtimestamp>

        Sample Request

        A sample request is reproduced below:

        wss://PerformanceMetrics_ACQ_1654268360:MTIzNDUtMTIxMjEyLTEyMTIxMi0xMjEyOjEyMzQ1LTEyMTIxLTIxMjEyLTEyMTItMTIy@dev.aecdevops.com:4747/AEDataTransmitter?name=PerformanceMetrics_ACQ_1654268360

        Sample Request Fields

        Field

        Description

        APIKey

        A unique code that identifies and authenticates an application to access an API.

        SecretKey

        An unique code that is used for authentication purpose. Encode the API Key:SecretKey pair using a Base64 encode utility and use the encoded result in the request.

        WebsocketURL

        This is the Websocket URL and the Port. This information varies for each Tenant.

        User

        The name of the user requesting access to the Websocket server.

        Unixtimestamp

        This is the unique date time field that prevents duplicate logins to the Websocket server.

        Note:

        Across multiple connections, unixtimestamp should be unique. Unixtimestamp is the number of seconds that have elapsed since the Unix epoch UTC 00:00:00 on January 1, 1970), excluding leap seconds. The uniqueness is maintained by adding a timestamp to the logged-in user. For example,

        'PerformanceMetrics_' + userName + '_' + unixtimestamp;

        Sample Response

        On successful connection, the client receives a connection event. See the response below:

        {
"Sender": "Server",
"Receiver": " PerformanceMetrics_ACQ_1654268360",
"MessageType": "OpenID",
"Data": "ec3df1f8b20b4d239354925276a7c989"
}

        Sample Response Fields

        Field

        Description

        Sender

        The service / component / server sending the response.

        Receiver

        The user receiving the response.

        Message Type

        This is the unique ID generated.  

        Data

        This is the Unique ID generated by the Websocket server.

        Initialization Request

        When the connection event is received, the client must send an initialization request as below:

        [WSEvent] Message: 
{
    "Sender": " PerformanceMetrics_ACQ_1654268360",
    "Receiver": "ATIRealTimeService",
    "MessageType": "AEPerformanceMetricInitialization",
    "Data": "{\"TimeZoneOffset\":-330,\"Sender\":\"PerformanceMetrics_ACQ_1654268360}"
}

        Initialization Request Fields

        Field

        Description

        Sender

        The client sending the packet.

        Receiver

        The receiver of the packet.

        Message Type

        The message type is AEPerformanceMetricInitialization.

        Data

        TimeZoneOffset

        This is the Time zone offset (from UTC) that the client is in.

        Sender

        The sender of the packet requesting for initialization. Use the same name you used previously when requesting the Websocket connection.

        Note:

        Send this initialization request only once after the client connects to the Websocket server.

        Socket Failure

        The connection to the Websocket server is established instantly upon a user’s request, and the authentication is carried out simultaneously. If the authentication fails, the connection established is closed. The failure could be due to an invalid API Key and/or Secret Key. Regenerating the keys should fix the authentication issue.

        Other reasons for failure could be:

        1. A wrong Websocket URL sent by the client.

        2. The Websocket server may be down, preventing connection with the user.

        3. A firewall may have blocked access.

        Socket Disconnect

        The application checks for the connection to the Websocket at 5-second intervals. If there is a disconnect event on the client side, establish the reconnection immediately. On successful reconnection, the client has to send the initialization packet again.

        Was this article helpful?
        What's Next
        Change password!
        Changing your password will log you out immediately. Use the new password to log back in.
        Change profile
        Success!
        First name must have atleast 2 characters. Numbers and special characters are not allowed.
        Last name must have atleast 1 characters. Numbers and special characters are not allowed.
        Enter a valid email
        Enter a valid password
        Your profile has been successfully updated.
        Logout