Introduction

This documentation serves as a guide to integrate with Civic’s Secure Identity Platform (SIP). The platform provides partners with functionality such as

secure 2FA user login
secure private 2FA user login
onboarding of verified users wtih customized flows
secure data exchange between partner and users

Integration

There are two integration flows:

Civic Hosted option (for partners)- this provides a flow similar to the traditional oAuth2 authorization code flow, with Civic performing the role of the Authorization server. This option
- minimises server side development required by the partner.
- delivers a secure solution.
- is the simplest route to integration.
Direct option (currently not available to partners)- communication is directly between the requester and the user’s mobile device. This option
- requires more server side development .
- requires a callback endpoint on the server.

Civic Hosted option

The general flow is explained with user signup as an example. Implicit Flow

1. Signup. The user clicks “Signup with Civic” button on your website page. The eventhandler calls a method in the CivicJS library to initiate signup.

2. Launch Popup. A modal is displayed which contains an iframe to house the QR code. A request is made to the Civic server to generate a QR code for your scope request.

3. QR Code. The server checks that the parent document for the iframe corresponds to the domain white list set in the partner account before serving the code. The QR code bridges the air gap between the browser and the user’s smart phone.

4. Scan. The user scans the QR code using the Civic mobile app and is prompted to authorize or deny the scope request. The prompt highlights the data that is being requested.

5. Grant Request. Upon granting the request, the data is encrypted and sent to the Civic server.

6. Verify offline. The Civic SIP server verifies the authenticity and integrity of the attestations received from the user’s mobile app. This process proves that the user data was attested to by Civic and that the user is currently in control of the private keys relevant to the data.

7. Verify blockchain. The Civic server then verifies that the attestations are still valid on the blockchain and have not been revoked.

8. Encrypt and cache. The data is encrypted using the public key for the partner, and cached on the server. When the data becomes available on the Civic server, a polling request from the iframe will receive a response in the form of a JWT token. The CivicJS library passes the token to the parent document. Your site is then responsible for passing the JWT token to your server.

9. Authorization Code exchange. The JWT token is decoded and verified on your server by the Civic SIP sdk. The authorization code (AC) is retrieved from the JWT token and sent to the Civic SIP server where it is validated and the cached data returned.

10. Decrypt. Your server receives the encrypted data where it is decrypted using your application secret key. The result will contain a userId and any data requested (such as email).

11. Complete user signup. At this point you can store the necessary data and redirect the user to your app’s logged in experience.

For subsequent logins the userId can be used to associate the user with your accounts system.

Getting Started

Follow the steps below to integrate using the Civic Hosted option.

Include

<script src="https://hosted-sip.civic.com/js/civic.sip-v0.1.js"></script>

Step 1: Include

Include the civic.sip.js script on your page. This exposes a single global object, civic.

Initialize

  // Step 2: Instantiate instance of civic.sip
  var civic = new civic.sip({ appId: 'CO-ABCDEFG1230934545');

Step 2: Initialize

Create an instance of civic.sip, passing your application ID. This identifies your site to Civic servers. You can find your application ID in the Partner Details section of your Civic Partner dashboard.

Event Handlers:

  // Step 3: Start scope request.
  $('button.js-signup').click(function(event) {
    civic.signup({ style: 'popup', scopeRequest: civic.ScopeRequests.BASIC_SIGNUP });
  })

    // Listen for data
    civic.on('data-received', function (event) {
        console.log('   event : ', event.data);
        // pass data to server
        sendAuthCode(authCode);
    });

Step 3: Events

Provide a suitable event handler to initiate the Civic scope request. For example, for a signup scenario, place a “Signup with Civic” button on your page (see our style guidelines for the Civic color palette and related iconography). The event handler calls civic.signup, passing in the required scope request.
Provide an event handler to listen for data events. SIP server data returned to the browser in response to a scope request is wrapped in a JWT token for security. The authorization code will be passed to the handler (in the JWT format) after a successful login or signup. Pass the JWT token to your server to make a server to server call to the SIP server to retrieve the user data.

The event contains the following fields:

Server Integration

Use the Civic SIP server sdk relevant to your server side environment to complete the server integration of your signup. login or general scope request flow.

Installation:

npm install civic-hosted-sip

  // Step 4: Initialize instance passing your app secret.
  var civic = new civic.sip({ appSecret: APP_SECRET);

Step 4: Initialize

Create an instance of civic.sip, passing in your application secret. The secret should only be used on the server and never exposed client side. The secret is a sensitive access token and must be stored securely.

  // Step 5: Exchange authorization code for user data.

  civic.exchangeCode(jwtToken, (error, userData) => {

  });

Step 5: Exchange Authorization Code

Call civic.exchangeCode with the JWT token you received from the browser session. The Civic sdk decodes the JWT token, verifies it is authentic and calls the Civic SIP server to exchange the code for the previously requested user data. Your server receives the data encrypted. The Civic sdk decrypts the data using your application secret key and returns a data object. The userId must be associated with the user account for tracking in future logins.

Direct Option

This option is not currently available for partner integration.

Browser Support

To ensure the best possible results, the Civic browser experience is designed for modern desktop browsers that automatically update. Browsers without reliable automatic update systems are supported as current version -1.

Chrome: latest version
Firefox: latest version
Edge: latest version
Safari (OS X): 10+
Internet Explorer: 11+

Environments

Partners have access to our test and live environments via environment specific clientID’s and key pairs. ClientID’s and key pairs can be managed in the partner’s dashboard. It is possible to generate multiple ClientID’s. This allows a partner to assign different clientID’s to different subsystems and applications within the organization. This limits the contagion in the event that a private key is compromised, and only that clientID and key pair need to be regenerated.

Our API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported. API requests without authentication will also fail.

Errors

Civic uses conventional HTTP response codes to indicate the success or failure of an API request. In general, a response code of 2xx indicates the operation was successful. Other error codes indicate either a client error (4xx) or a server error (5xx).

The Civic API uses the following error codes:

Error Code	Meaning
400	Bad Request – Check the response ‘message’ field for details.
401	Unauthorized – Authentication failed.
405	Method Not Allowed – You tried to access an invalid method.
429	Too Many Requests – Your request was throttled by our gateway.
500	Internal Server Error – We had a problem with our server. Try again later.
504	Endpoint Request Timed-out Exception.