User Authentication with a PKI Device

Before authenticating with a PKI certificate, it must be registered. The procedure to register a PKI device is explained below.

Registering a PKI Device

Prerequisites:  

  • A bearer token (Access token) obtained by authenticating a privileged user (Organization Administrator, Client ID M2M) through an Authentication flow. You need a privileged user to have enough permissions to perform the actions listed below. Using a bearer token from an non-privileged user / Client ID will result in 401 / 403 HTTP responses from the Authentication Service APIs. To learn how to obtain a token, see Enabling User Authentication.

  • CA signed certificate.

  • Internal ID of the user you want to perform the operation on.

To register a PKI device:

The below endpoint helps you to achieve all the three steps:

POST https://AAAS_PLATFORM/scim/{tenant}/v2/Device/.import

Create a Device

The following arguments need to be supplied to create a device:

  • adapter - PKI

  • deviceType - DT_SCPKI

  • credentialType - CT_CRTCHK1

  • payload - public certificate base64-encoded

Assign a Device to the User

To assign a device to the user, you must know the Internal ID of the user.

The first step is to get the internal Id of the user, so we will search for the user whose external ID is jsmith@company.com.

Note:  
Copy 
POST https://[base-server-url]/scim/{tenant}/v2/Users/.search HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json" 
{
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:SearchRequest"   ],
   "filter":"externalId eq \"jsmith@company.com\"",
   "sortBy":"id",
   "sortOrder":"descending",
   "startIndex":0,
   "count":100
}

The response contains the internal ID, here 52276. 

Copy 
{
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:ListResponse"   ],
   "totalResults":1,
   "resources":[
      {
         "schemas":[
            "urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:hid:scim:api:idp:2.0:UserDevice",
            "urn:hid:scim:api:idp:2.0:UserAttribute",
            "urn:hid:scim:api:idp:2.0:UserAuthenticator"         ],
         "id":"52276",
         "externalId":"jsmith@company.com" 
         (...)     
 
      }
   ]
}

Create an Authenticator for the User

In order to create an authenticator for the user, Authentication Policy value must be supplied

The Authentication Policy to use is: AT_EMPPKI

Important:

Choosing the right device type when using PKI devices with the Authentication Service is very important.

Adapter Device type Credential type

PKI

DT_SCPKI

CT_CRTCHK1

Example

The sample request to register the PKI device type is given below:

Copy 
POST https://[base-server-url]/scim/{tenant}/v2/Device/.import
{
    "adapter": "PKI",
    "binding": {
        "deviceType": "DT_SCPKI",
        "credentialType" : "CT_CRTCHK1"
    },
    "status": "ACTIVE",
    "owner": {
        "value": "52276"
    },
    "policy": {
        "value": "AT_EMPPKI"
    },
    "payload": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURqekNDQW5lZ0F3SUJBZ0l...<truncated>"
}

The response:

Copy 
{"results": [{
   "device": {
      "schemas": ["urn:hid:scim:api:idp:2.0:Device"],
      "id": "13470",
      "externalId": "57585339152211881377412553084082664131",
      "meta": {
         "resourceType": "Device",
         "created": "2020-07-28T23:08:13Z",
         "location": "https://[base-server-url]/scim/{tenant}/v2/Device/13470",
         "version": "1"
      },
      "type": "DT_SCPKI",
      "status": {
         "status": "ACTIVE",
         "active": true,
         "expiryDate": "2042-09-13T12:51:41Z",
         "startDate": "2012-09-13T12:41:42Z"
      }
   },
   "result": 101,
   "reason": "Imported Token"
}]}

Authenticating with PKI Certificate

Prerequisites:  

  1. Register the CA signed public certificate, see Registering a PKI Device.

  2. Import the certificate (private key) which can be installed in the browser certificate store – or stored on a smart card.

    • If certificate is stored in a smart card, import the public certificate in a browser ( .cer file), when inserting the smart card where the browser is installed, smart card middle ware imports the certificate automatically.

    • If certificate is not in a smart card, import the full certificate with the private key in the browser (.pfx or .p12 file)

    3. Important: If a smart card-based certificate is used, insert it into your system where browser is installed.

  3. Use Authorization code flow to access the IDP's PKI endpoint.

  4. Follow the browser instructions to authenticate your private certificate/key.