CivicSIP.NET 1.0.3

civic-sip-dotnet

.NET implementation for the Civic hosted SIP API.

See https://docs.civic.com for a more details.

Public interface

For public use the code exposes one class CivicSip with only one method ExchangeToken. This method takes a jwt token in string representation as an input parameter and returns a user data structure as an output which describes the user details. For operation CivicSip class needs configuration which is passed to the class constructor.

Configuration

All required configuration resides in CivicConfig class. This class keeps user-specific configuration as well as common unchangable constants. User-specific details include following:

• ApplicationId
• ApplicationSecret
• ClientSigning credentials
• Encryption credentials (currently unused)

Common constants include:

• Base URL
• Authentication path
• Environment (always equal to prod)
• ServerSigning credentials (needed to validate the provided data from the server)

Currently, to create an instance of configuration class it only necessary to povide only three parameters as shown below.

CivicConfig config = new CivicConfig(
                        applicationId: "8uh0jHpDA",
                        applicationSecret: "c395719a...",
                        privateSigningKey: "b86451c3bbeaad4141..."
                    );

User data model

User data is provided in the form of records collection where each record specifies following properties:

• Label - user data property label (e.g. email, phone, ...)
• Value - user data value itself corresponding to the Label
• IsValid - boolean property
• IsOwner - boolean property

Usage

• Register your application on Civic Partner Portal.
• In your code init CivicConfig object with your Application ID, Application Secret, Private Signing Key.
• Create new instance of CivicSip object with provided configuration.
• Exchange JWT token for user data:

CivicSip sip = new CivicSip(config);
UserData data = await sip.ExchangeToken(token);

Operation details

The library uses the provided jwtToken to exchange it for real user data.

An Http request to Civic server is done to make the token exchange. This Http request contains a JSON content with the requested jwtToken, and specifies an authentication header which follows Civic authentication scheme. Authentication header contains a new jwt token with client signature, and Civic extention which signs the http request body.

In the response Civic server returns its own new jwt token with encrypted user data. The library validates the token, decrypts the data and parses into UserData model.

The approach uses ECDSA elliptic curve cryptography for signing JWT tokens, HMACSHA256 for Civic extension in authentication header, and AES for user data encryption.