NAV Navbar
  • Introduction
  • Trusted Key Digital Identity Wallet
  • API Credentials
  • OAuth / OpenID Connect
  • Issuing Party
  • Auth0
  • Drupal Websites
  • WordPress Websites
  • Salesforce
  • Transaction Authorization
  • Document Signing
  • .js Library Reference
  • Understanding Recovery
  • HTTP Errors
  • Introduction

    Welcome to the Trusted Key Relying Party Documentation

    This resource provides all the documentation you'll need to get started developing an application with Trusted Key Relying Party Support.

    Trusted Key Digital Identity Wallet

    Get the App for your Mobile Device

    You can download the iOS Trusted Key Digital Identity Wallet here and the Android Wallet here

    Trusted Key Digital Identity Wallet User Guide

    The Trusted Key User Guide can be found here

    API Credentials

    Developers need to have API credentials to access the Trusted Key Platform. The Client ID and Client Secret credentials can be obtained by following the below steps:

    1.Go to the Trusted Key Developer Portal

    2.Click on "Get the Trusted Key App" button in the top right corner to download the Trusted Key App to your mobile device if you haven’t already downloaded it. Setup your Trusted Key App with an email address.

    Dev Portal

    3.Click on "Sign up with Trusted Key App" in the upper navigation bar. You will be asked to enter the email address you registered on the Trusted Key App. You will get a notification on your mobile device asking for authorization to access the Developer Portal.

    4.Once you have logged into the Trusted Key Developer Portal click on "Register New App" where you will be asked to enter your app name and callback URL. The callback URL must be https. The callback URL is often specific to your OAuth implementation and is typically more than just your website's base URL. It would be your website's base URL + a callback route. The Portal will then provision you with a Client ID and Client Secret to use in your API calls to the Trusted Key Platform.

    My Apps

    5.If you forget your App's API credentials you can always log back into the Trusted Key Developer portal and click on "My Apps".

    New Connection

    OAuth / OpenID Connect

    The process of integrating Trusted Key Relying Party support is made simple using OAuth and OpenID Connect. OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol. In technical terms, OpenID Connect specifies a RESTful HTTP API, using JSON as a data format. The standard allows services to easily setup Trusted Key Relying Party support to verify the identity of an end-user, as well as to obtain basic profile information.

    For more information, developers are encouraged to refer to the http://openid.net/specs/openid-connect-core-1_0.html.

    There are many OpenID Connect plugins in the ecosystem. Please note that not all plugins are created alike and some plugins might not work with Trusted Key services due to different implementations of the specification.

    Setup

    The first step is to determine the return url. Often the plugin readme file will provide guidance on what it should be. i.e. https://mywebsite/openid-connect-authorize

    Getting Client ID & Client Secret (API credentials)

    Please see the guide here on getting a Trusted Key Client ID and Client Secret.

    Scopes

    Scope determines which pieces of data will be returned when calling the UserInfo Endpoint. It's a list of space-delimited scope identifiers. Example: scope=email will let you obtain the user's email address.

    Standard scopes:

    Trusted Key specific scopes:

    Additional custom claims can be requested using the Open ID Connect claims parameter.

    State

    Opaque value used to maintain state between the Authentication request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie.

    Nonce

    String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token, which is signed by the private key. You must verify that the nonce Claim Value in the ID Token is equal to the value of the nonce parameter sent in the Authentication Request.

    Claims

    The optional claims Authentication Request parameter requests that specific Claims be returned from the UserInfo Endpoint and/or in the ID Token. It is represented as a JSON object containing lists of Claims being requested from these locations.

    Return URL

    Use the Return URL that was registered with the developer portal. The user agent will be redirected to this URL with the authorization code and/or OpenID-Connect id_token.

    Endpoints

    Login Endpoint URL: Identifies the provider authorization endpoint. Use: https://wallet.trustedkey.com/oauth/authorize

    Token Endpoint URL: Identifies provider token endpoint which returns the access_token and the ID token id_token. Use: https://wallet.trustedkey.com/oauth/token

    Invalidate access token: GET https://wallet.trustedkey.com/oauth/logout with query parameter:

    access_token=<access token>

    UserInfo Endpoint: GET https://wallet.trustedkey.com/oauth/user with header:

    'Authorization' : 'Bearer ' + access_token

    Example OAuth Setup tutorial (Node js):

    Start by installing an OAuth client (any OAuth2 client will do). For the sake of this tutorial we have chosen client-oauth2.

    $ cd ~/my-project
    $ npm install client-oauth2 --save
    


    Other dependencies include:
    - express
    - body-parser
    - request-promise

    Configure the OAuth client. Example (javascript):

    const client = new ClientOAuth2({
      clientId: ClientId,
      clientSecret: ClientSecret,
      accessTokenUri: 'https://wallet.trustedkey.com/oauth/token',
      authorizationUri: 'https://wallet.trustedkey.com/oauth/authorize',
      redirectUri: 'https://<where your application is hosted>/oauth/callback',
      scopes: ['openid', 'profile', 'email'],
      state: state,
      nonce: nonce,
    })
    


    We can now grab the access_token from the request (req) (javascript):

    client.code.getToken(req.originalUrl).then(response => {
       console.log('>>> got access token', response.accessToken)
       // Typically this is where you'd validate the `id_token` signature using
       // a previously registered public key of the user and that the `nonce`
       // Claim Value is equal to the value of the `nonce` parameter sent in
       // the Authentication Request.
    })
    


    Login

    Redirect to client.code.getUri()

    Login Flow

    Once you have configured your OpenID Connect configuration you can try it out. When you attempt to connect you should be directed to the Trusted Key login page where the user will be prompted to enter their email address. If a valid email address is entered the user will get a notification in the Trusted Key App for which they will need to authorize access. Once the user has provided authorization the login page will return to the service with the required login credentials.

    Custom Login

    1. Append &login_hint= <user's email> to the login redirect uri. (/oauth/authorize endpoint). The user's email address must be url encode.
    2. Where the ‘login_hint’ is the user’s registered email and can be passed from a custom form rather than being entered on the Trusted Key OAuth redirect page.


    User info

    After OAuth, we receive an access token at the redirectUri. Note: We will need this access token for future use in Logout. You may securely store this token where ever you like. We recommend using JWT tokens to store the jwt-token in browser cookies so as to not expose the access token. However, to keep this tutorial simple we have stored the access token as is in the browser's cookies.

    To obtain user information specified in the scope, we use this token to make a GET request to: https://wallet.trustedkey.com/oauth/user with header:

    'Authorization' : 'Bearer ' + access_token

    Token.sign returns request-options and takes care of setting that header for you.

    Example (javascript):

    var options = token.sign({
      method: 'GET', url: Url.resolve('https://wallet.trustedkey.com', '/oauth/user')
    });
    
    return rp({
      uri: options.url,
      method: options.method,
      headers: options.headers,
      json: true
    })
    


    Logout

    Redirect to https://wallet.trustedkey.com/oauth/logout with query parameters:

    access_token=<access token>

    return_url=<where you want to take the user to after logout>

    Issuing Party

    For the below example, you would need to set the clientId, clientSecret and pubkey of TrustedKey wallet end user.

    Note: Currently, issuing certificates are not developer created. You will need to ask TrustedKey dev team to set an issuer for you.

    Example (Node js):

    const TokenIssuerService = require("trustedkey-js/services/trustedkeyissuerservice")
    const OIDs = require('trustedkey-js/oid')
    const issuerServiceUrl = "https://issuer.trustedkey.com";
    
    const clientId = '' // SET ME: clientId 
    const clientSecret = '' // SET ME: clientSecret
    var pubKey = '' // SET ME: public key of end user TK wallet
    
    const tokenIssuerService = new TokenIssuerService(issuerServiceUrl, clientId, clientSecret);
    
    let expiryDate = new Date()
    expiryDate.setDate(expiryDate.getDate() + 100); // expires in 100 days from issuance
    let buffer = {}; // this should be Buffer object representing image
    
    const attributes = {}
    attributes[OIDs.commonName] = 'Full Name' // individual claim to be issued
    attributes[OIDs.country] = 'USA' // individual claim to be issued
    
    tokenIssuerService.requestImageClaims({
         'images': [{
           name: "Image Name",
           data: buffer.toString("base64"),
           oid: OIDs.documentImageHead  // issuing an image claim
         }],
         'attributes': attributes,
         'expiry': expiryDate, // claims expiration date
         'pubkey': pubKey, // public key of end user TK wallet
       })
    


    Auth0

    Auth0 Configuration

    In your Auth0 dashboard, go to "Extensions" in the left sidebar close to the bottom. Choose "Custom Social Connections". If you have not previously used this extension you will be asked to install it. Once installed in "Installed Extensions" click on "Custom Social Connections". Within the Custom Social Connections page click "+ New Connection". In the settings page fill out the below fields as follows: New Connection

    Name: The name you choose for your connection

    Client ID and Client Secret: You will need to register your App with Trusted Key to obtain a Client ID and Client Secret to copy into your Auth0 app settings.Please see the guide here on getting a Trusted Key Client ID and Client Secret.

    Fetch User Profile Script: Replace with the script on the right:

    function(access_token, context, callback) {
      request.get('https://wallet.trustedkey.com/oauth/user', {
        'headers': {
          'Authorization': 'Bearer ' + access_token,
          'User-Agent': 'Auth0'
        }
      }, (error, response, body) => {
      if (error) {
        return callback(error)
      }
      if (response.statusCode !== 200) {
        return callback(new Error('StatusCode:' + response.statusCode))
      }
    
      callback(null, JSON.parse(body))
      })
    }
    


    Authorization URL: https://wallet.trustedkey.com/oauth/authorize

    Token URL: https://wallet.trustedkey.com/oauth/token

    Scope: Trusted Key has the following scopes available. Enter them as space separated values. Example: openid email

    Custom Headers: Please leave blank

    Click "Save" once completed and click "Try" to test it out.

    You're done!

    Next Steps

    Now that you have a working connection, the next step is to configure your application to use it. First make sure the custom connection is enable. Go to the Apps tab for the connection and enable it for the Auth0 web app of your choosing. You can initiate login using Lock, Auth0.js, or the Authentication API endpoint.

    For detailed instructions and samples for a variety of technologies, refer to the following quick-starts:

    For more background information on Auth0 Client Authentication please see the documentation here

    Auth0 WordPress Plugin

    In the Wordpress Admin Portal add the "Login by Auth0" plugin. After entering your Auth0 credentials the plugin will automatically register a new client in the Auth0 dashboard for the Wordpress Site. Configure the Auth0 Plugin Settings in the WordPress Admin portal as needed.

    Drupal Websites

    This section documents how to configure existing Drupal OpenID Connect plugins to support Trusted Key Relying Party services.

    Install Plugin

    Enable the Drupal OpenID Connect & OpenID Connect SSO modules

    https://www.drupal.org/project/openid_connect_sso

    https://www.drupal.org/project/openid_connect

    Configure Plugin

    2.(Optional) Open the openid_connect_sso plugin and change the plugin name to your liking. If you skip this step the name appearing will be "generic".

    Obtain Client ID and Client Secret

    Configure Settings

    In you drupal setup goto openID connect configuration page (admin/config/services/openid-connect)

    OIDC

    (Optional) Enable SSO in Drupal by going to 'admin/config/services/openid-connect-sso'

    OIDC

    Once you are done with these example.com/user/login will take you to Trusted Key Relying Party login for authentication and then direct you back to your portal.

    WordPress Websites

    This section documents how to configure a WordPress OpenID Connect plugins to support Trusted Key Relying Party services.

    Install Plugin

    Trusted Key has created a slightly modified version of the OpenID-Connect-Generic plugin. You can download the plugin from GitHub here: https://github.com/trustedkey/openid-connect-generic. After downloading the plugin:

    Obtain Client ID and Client Secret

    To get your credentials please go to the Trusted Key Developer Portal, login, and register an App for Salesforce. Use the callback URL you copied from the Salesforce page. Please see the guide here on getting a Trusted Key Client ID and Client Secret.

    The Callback URL can be found at the bottom of the settings page (same as Redirect URL).

    Redirect URL (Callback URL)

    OIDC

    Configure Settings

    Settings location

    OIDC

    Login Page

    OIDC

    Settings

    OIDC

    OIDC

    OIDC

    Salesforce

    This section documents how to configure Salesforce to support Trusted Key Relying Party services.

    Requirements

    You will need a salesforce account that allows 3rd party authorization. Currently this includes the Lightning Experience, Salesforce Classic, Enterprise, Performance, Unlimited, and Developer Editions

    Setup

    Log into your salesforce account and click on setup in the top right corner. In the setup home page in the left hand toolbar under Settings click on "Identity" followed by "Auth. Providers". In the Auth. Providers page click on "New"

    Setup Button OIDC

    Identity - Auth. Providers OIDC

    For provider type choose "Open ID Connect"

    OIDC

    Choose a name for your login. This name will be reflected in the URL Suffix. We now face a chicken and egg. We need a callback URL for the Trusted Key Developer portal to get the Consumer Key and Consumer Secret, but we need to provide these inputs for Salesforce to get the callback URL. So to get around this we will just place some random digits in the Consumer Key and Consumer Secret fields temporarily.

    For Authorize Endpoint URL use https://wallet.trustedkey.com/oauth/authorize

    For Token Endpoint URL use https://wallet.trustedkey.com/oauth/token

    For User Info Endpoint URL use https://wallet.trustedkey.com/oauth/user

    You can enter any values in default scopes field depending on your login requirements. Common scopes include openid and email. Enter these values with only a space in between. Place a check to enable "Send access token in header". Leave "Send client credentials in header" unchecked.

    Under Registration Header select a Auto-created RegHandler. You will need to modify this Apex Class in the future. Under "Execute Registration As" select a user who has admin privileges and the ability to create new users.

    Press "Save". A new window should appear that shows the configured Auth. Provider. At the bottom of the screen you will see the Salesforce Configuration fields. Copy the link for the Callback URL.

    Auth. Provider setup with placeholder Consumer Key/Secret OIDC

    Saved profile Salesforce Configuration with Callback URL OIDC

    Go to the Trusted Key Developer Portal, login, and register an App for Salesforce. Use the callback URL you copied from the Salesforce page. Please see the guide here on getting a Trusted Key Client ID and Client Secret. Please note that Client ID = Consumer Key, and Client Secret = Consumer Secret.

    After you have registered your App on the Trusted Key Developer Portal return to your Salesforce page and choose to Edit the Auth. Provider you constructed. Now paste your Client ID into the Consumer Key field, and paste your Client Secret into the Consumer Secret field. Now re-save your Auth Provider.

    Final Auth. Provider Setup OIDC

    Testing

    You are now ready to test your Salesforce login with the Trusted Key App. Go back to you Auth. Provider Salesforce Configuration URLs. You can test the basic functionality of your login with the "Test-Only Initialization URL" which will generate an XML page on success. You can use the "OAuth-Only Initialization URL" to log you straight into your Salesforce account using your Trusted Key Wallet. Finally you can use the "Existing User Linking URL" to tie together the Trusted Key App login with an existing Salesforce user account.

    Salesforce Configuration URLs OIDC

    XML document indicating login success for Test-Only Initialization URL OIDC

    Salesforce page allowing you to link Trusted Key Login to existing account OIDC

    Next Steps

    Once you have validated the operation of your Trusted Key login you can begin integrating the support into your Login Portal. This might include integrating a Trusted Key Button on your Domain login page. To set this up under "My Domain" go to Authentication Configuration and select Trusted Key as an authentication service.

    My Domain Setup

    OIDC

    My Domain Login Portal

    OIDC

    You will also need to edit your Registration Handler to customize how a customer will log in using the Trusted Key Service.

    More resources on the Salesforce configuration can be found below:

    https://help.salesforce.com/articleView?id=sso_provider_openid_connect.htm&type=0

    https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_auth_plugin.htm

    https://www.youtube.com/watch?v=T1fpulzHYcs

    Transaction Authorization

    Trusted Key Transaction Authorization allows Relying Parties to send messages to the Trusted Key Digital Identity Wallet. Users can then choose to Confirm or Deny the request in the message.

    Sending Message to the Trusted Key Digital Identity Wallet

    1. It involves adding a url encoded “message” to the OAuth redirect to ‘/oauth/authorize’ endpoint
    2. Example: Append '&login_hint=' + <email> + '&message=' + <message> where, email is the registered users email to whom the transaction is to be directed to and message is the custom text you would like the user to read and accordingly choose to confirm or deny. Both email and message must be url encoded.

    Complete url encoded example: https://wallet.trustedkey.com/login.html?response_type=code&redirect_uri=https%3A%2F%2Fkeith258.au.auth0.com%2Flogin%2Fcallback&message=Please%20authorize%20payment%20of%20$200%20to%20Ebay%20from%20Visa%20credit%20card%20ending%20in%205620&scope=openid%20email%20profile%20documentID&state=TjB3zNbtBM-r_ATg3_aLtJz30pJRhNR1&client_id=f7288f1f6f95eae7ae2c2135a4a13903220c6d47%7Cb218e9c2-2916-465f-bc8e-8f09c8c2212c#

    Note that this “message” is outside the standard OpenID Connect specification. This message will be sent as a request to the Trusted Key Digital Identity Wallet which the user can choose to accept or deny.

    Document Signing

    Introduction

    Trusted Key Document Signing Services allows Relying Parties to request PDF document signatures from the Trusted Key App.

    Architecture & Flow

    Architecture

    Document Signing Flow:

    1. User requesting the signature enters email address registered in Trusted Key App
    2. User chooses a PDF file from the local file system
    3. User submits the form to the Client Trusted Key Relying party
    4. Document to be signed is stored in client’s storage
    5. The Client Relying Party backend calls Trusted Key Web Services and requests endpoint with query parameters
      • objectIds – 2.5.4.3 (CommonName)
      • nonce – string; unique session identifier
      • emails – address(es) of the user(s)
      • documentUrl – https://example.com/storage/1234.pdf
      • callbackUrl – https://docsig.trustedkey.com/sign?client=JWT
    6. The user is redirected to client’s status page
    7. Trusted Key Web Service checks its database for the (hashed) email addresses. If the hash is found and a device-token is known, a push notification is sent to the users Trusted Key App. Otherwise, an email is sent.
    8. The signatory opens the request in the Trusted Key App and agrees to sign
    9. The Trusted Key App invokes the callbackUrl with the full name token
    10. DocSig inspects the JWT, assures the HS256 signature is valid for this client
    11. The DocSig backend checks its client database for the clientId
    12. DocSig backend retrieves the document from the documentUrl
    13. The digest of the document is computed
    14. The digest is returned to the Trusted Key App
    15. The Trusted Key App computes the final signature of the document and replies to DocSig
    16. DocSig embeds the final signature
    17. DocSig invokes the registered document callback with the final document content
    18. The client backend notifies the user that the document was signed

    Prerequisites

    For the duration of this tutorial we will use NodeJS 6.0 or later with the trustedkey.js framework installed. Find more information on the trustedkey.js framework here.

    Authentication

    Please see the guide here on getting a Trusted Key Client ID and Client Secret for Document Signing

    Getting Started

    Install NodeJS 6.0 or later from nodejs.org or Nodesource

    Install the trustedkey.js library

    $ npm install trustedkey-js
    


    Creating a document signature request (no SDK)

    const secret = "your docsig secret"
    const header = {"alg": "HS256", "typ": "JWT"}
    const message = {
        "iss": "your_appid",
        // User email address
        "signatory": "test@example.com",
        // Unique callback URL per request
        "callbackUrl": "https://callback.example.com/requestid=589f5a62-e3af-43fa-a14f-b93afb723838",
        // PDF URL
        "documentUrl": "https://pdf.example.com/docsigtest.pdf",
        // Object IDs to request from device
        "objectIds": ["2.5.4.3", "1.3.6.1.4.1.53318295.2"]
    }
    const jose = JSON.stringify(header)
    const jws = utils.base64url(jose) + '.' + utils.base64url(message)
    const hmac = Crypto.createHmac('sha256', secret)
    const jwt = jws + '.' + utils.base64url(hmac.update(jws, secret).digest())
    


    You can manually construct the DocSig JWT and call the endpoint https://wallet.trustedkey.com/newDocumentSignRequest?jwt=hs256_jwt_here

    Bear in mind that you still have to provide the Authorization header checked by the Trusted Key App even for DocSig calls.ax

    Creating a document signature request (SDK)

    The Trustedkey.js SDK abstracts all JWT details for you

    const docsigService = new DocSigService('https://wallet.trustedkey.com/', appId, appSecret, docsigAppId, docsigAppSecret)
    docsigService.documentSignRequest(
        // User email address
        'test@example.com',
        // Unique callback URL per request
        'https://callback.example.com/requestid=589f5a62-e3af-43fa-a14f-b93afb723838',
        // PDF URL
        'https://pdf.example.com/docsigtest.pdf',
        // Object IDs to request from device
        ['2.5.4.3', '1.3.6.1.4.1.53318295.2']
    ).then(_ => {
        console.log('Posted new request')
    })
    


    Receiving the callback

    The callback is called with a PUT request where the request body is the signed PDF document. This call is unauthenticated

    const Express = require('express')
    const FS = require('fs')
    const app = Express()
    
    app.put('/requestid=589f5a62-e3af-43fa-a14f-b93afb723838', (req, res) => {
        console.log('Got final PUT callback!')
    
        // Read data from response body
        req.pipe(concat(data => {
            res.send('{"resp": "OK"}')
    
            // Write file from callback
            // Should not be sync in a real world application
            FS.writeFileSync('out.pdf', data)
        }))
    })
    

    .js Library Reference

    You can find Trusted Key .js libraries here: https://github.com/trustedkey/trustedkey.js

    Documentation for these libraries is through jsdoc.

    To build the documentation simply pull the libraries from github to your local drive.

    Use the following command to create the documentation:

    $ jsdoc -r -c jsdoc.json -d doc --verbose --pedantic . README.md
    


    Client ID & Client Secret

    Please see the guide here on getting a Trusted Key Client ID and Client Secret.

    Understanding Recovery

    Overview

    User recovery is a key strength of the Trusted Key platform. When a user installs a new instance of the Trusted Key App, the Trusted Key Platform enables the user to easily recover their Trusted Key Identity token which will allow them to continue using Relying Party services they have previously registered with.

    Please note that the Recovery process does not recover any identity information such as email address, driver license, or passport. The user will need to setup this information again in their new instance of their Trusted Key App.

    Backup

    After intially setting up the Trusted Key App, the user will be prompted to backup their wallet.

    Backup

    When the user presses the "Backup" button the setup wizard will start. The user will be provided a 12-word list that they are asked to write down. The screen will then randomly choose two words from the list to ensure the user has recorded the list correctly. Finally the user will need to enter a new 6-digit PIN that is specific to the recovery process.

    Backup Wordlist Check Wordlist Enter PIN Generate

    Recovery

    When the user installs a new Trusted Key App the startup screens will provide the option to "Recover Account"

    Open

    When "Recover Account" is pressed the user will be be asked to enter their 6-digit recovery PIN. They will then be prompted to enter their 12-word recovery wordlist.

    Start Empty Words Completed words

    Once filled out the Trusted Key Platform will look for a match to the wordlist and complete the recovery process.

    HTTP Errors

    The Trusted Key platform uses standard HTTP response codes for indicating whether a request succeeded or failed. In general, response codes in the 200-level range indicate success, response codes in the 400-level range indicate a failure caused by information provided, and response codes in the 500-level range indicate a failure caused by a problem on the server.

    HTTP Status Codes

    Code Meaning
    200 OK
    400 Bad request
    401 Unauthorized
    403 Forbidden
    404 Not found
    422 Unprocessable entity
    500 Internal server error
    #
    #