Self-Service Portal

This section describes how to deploy, configure and use Self-Service Portal.

Overview

The Self-Service Portal (SSP) is a web application provided by Thales. It enables to download certificates (credentials) on Android and iOS devices through VMware Workspace ONE PIV-D Manager mobile application. These credentials are derived from the Safenet IDPrime virtual smartcard.

For executing Self-Service Portal, RedirectURLs must be reconfigured in the idp-config.json and IDP Server. Now, IdpScope (mandatory parameter) value will be read from idp-config.json file. For more information, refer to Integration section

Prerequisite(s) for Configuring Self-Service Portal

Following prerequisites are required to configure Self-Service Portal:

IDPV server should be available for making the virtual smart card available for download. For more information, refer to Setting up IDPrime Virtual Server section.

Deploying Self-Service Portal in Docker

Perform the following steps to deploy the container in docker.

The values in <angle brackets> should be updated. After the update, remove the angle brackets.

1. Run the following command to unzip the provided image file as a TAR:

   
   gzip -d <image-name.tar.gz>
   
   
   

2. After unzipping, run the following command to load the image in the Docker registry:

   
   docker load -i <image-name.tar>
   
   
   

   For RHEL 8 or 9 with podman environment, the command is:

   
   podman load -i <image-name.tar>
   
   
   

   After the above command is successful, it returns output in the following format:

   
   Loaded image: idpv_ssportal:2.x
   
   
   

3. Copy the config.js file downloaded from one of the following delivery packages and paste it in the /var/thales/config directory:

   • \<Thales IDPrime Virtual Alpine v2.x>\Self-Service Portal v2.x\

   • \<Thales IDPrime Virtual Ubuntu v2.x>\Self-Service Portal v2.x\

   For making changes in the config.js, refer to Configure Self-Service Portal Parameters.

4. If the user is using self-signed certificate , the following commands should be used to generate cert.pem and key.pem and place it under /var/thales/certs directory:

   • Command to export the private key(key.pem):

     
     openssl pkcs12 -in <cert_name>.pfx -nocerts -out key.pem –nodes
     
     
     

   • Command to export the certificate(cert.pem):

     
     openssl pkcs12 -in <cert_name>.pfx -nokeys -out cert.pem
     
     
     

   Where, <cert_name> is the name of the certificate.

   For creation of the certificate, refer to Enabling SSL and TLS section.

Configure Self-Service Portal Parameters

This section lists the Self-Service Portal parameters that must be configured in the config.js file available under the /var/thales/config directory.

Parameter	Description	Syntax/Sample
inactivityTimeOutInSec	User inactivity time out (in seconds) NOTE:   Default value is 600 seconds.	inactivityTimeOutInSec: 600
sessionDefaultExpiryTime	Session expiry time (in seconds) NOTE:   Default value is 60000 seconds.	sessionDefaultExpiryTime: 60000
sspBaseUrl	Base URL of the express server where the Self-service Portal application is hosted.	sspBaseUrl: 'https://idpvselfserviceportal.com' NOTE:   Mention the port number if running on port other than 443. Example: sspBaseUrl: 'https://idpvselfserviceportal.com:3001'
idpvServerBaseUrl	Base URL of the IDPV server	idpvServerBaseUrl: 'https://www.idpvserver.com' NOTE:   Mention the port number if running on port other than 443. Example: idpvServerBaseUrl: 'https://www.idpvserver.com:5001'
sslCertificateFileName	This certificate is required to configure express server on https.	sslCertificateFileName:'<certificatefile>'   Example: sslCertificateFileName: 'cert.pem'
sslKeyFileName	This file stores the private key.	sslKeyFileName: 'keyfile'   Example: sslKeyFileName: 'key.pem'
loggingLevel	Logging level generates logs based on the log type (error/info/debug) specified. Refer logging level section for more information about logging in Self-service Portal.	loggingLevel: 'info'   Refer to Logging in Self-Service Portal section for more details.
IdpScopes	This is an optional field. Change the scope of any identity provider rather than using the default scope used by Self-Service Portal application for different IDPs.	IdpScopes: { idpname : ‘scopevalue’ } Example 1: Using STA IdpScopes: {sta: 'openid'} Example 2: Using STA and PingFed idps IdpScopes: {sta: 'openid', pingid: 'idpvscope openid email offline_ access' } Example 3: Using STA/PingFed/Okta/SAS PCE/Azure idps IdpScopes: {sta: 'openid ', saspce: 'idpvscope openid' okta: 'idpvscope openid profile email offline_access', pingid: 'idpvscope openid email offline_access' }
enableSSLCheck	Value should be false if the self-signed certificate is required to be ignored.	enableSSLCheck : true

This section lists the Self-Service Portal parameters that must be configured in the WebServerConfig section appsettings.yml file available under the /var/thales/config directory.

Parameter	Description	Syntax/Sample
SelfServicePortalUrl	If you are using Self-Service Portal, provide the public base URL of Self- Service Portal accessible from client machines.	Enter the same URL that is given in the sspBaseUrl parameter specified in the config.js file: Syntax: https://sspBaseUrl:sspPort Example: https://idpvselfserviceportal.com:3001

Configuring Logging for Self-Service Portal

Logging is used to capture important information during different operations performed on the application.
For example: authenticating through identity provider, calling API of server etc. It is also useful in finding out the root cause in case of exception or error.

In Config.js file we have the below three options to configure logging level:

• error – logs error,line number and exception information if any error occurs.

• info – logs error,warning and short information about the performed operations.

• debug – logs error, warning, and detailed information about the performed operations. This log is quite useful to see the details and identify the root cause of bug or exception in the application.

In the Self-service Portal, the below information parameters are logged:

• Loglevel

• Message

• TimeStamp

• TenantId

• TokenId

• User

• Error info & Stack trace (in case of exception/error)

Along with the above information, every request/response is also getting logged.

Configuring RedirectURL

For the deployment of IDPV Server with Self-Service Portal, update the RedirectURL as below:

• Update in idp-config.json:

  • If Self-Service Portal is running on the default port - 443, the IDP configuration should contain idpRedirectUrl as <sspBaseUrl>/redirect. For example, https://idpvselfserviceportal.com/redirect

  • If Self-Service Portal is running on any other port (for example, 3001), the IDP configuration should contain idpRedirectUrl as <sspBaseUrl:sspPort>/redirect. For example, https://idpvselfserviceportal.com:3001/redirect

    The value of sspBaseUrl and sspPort must match with sspBaseUrl specified in the config.js file.

• Update IDP server configuration:

  The IDP server configuration should be set as per following combinations for different IDPs to support Self-Service Portal.

IDP	RedirectURL in idp-config.json	RedirectURL in IDP Server
		Structure	Example
STA	https://sspBaseUrl/redirect	https://sspBaseUrl>/*	https://idpvselfserviceportal.com/*
PingFed	https://sspBaseUrl/redirect	https://sspBaseUrl>/*	https://idpvselfserviceportal.com/*
Okta	https://sspBaseUrl/redirect	https://sspBaseUrl/redirect	https://idpvselfserviceportal.com:sspPort/redirect
		https://sspBaseUrl>/redirect	https://idpvselfserviceportal.com:sspPort/redirect
Azure	https://sspBaseUrl/redirect	https://sspBaseUrl/redirect	https://idpvselfserviceportal.com:sspPort/redirect
		https://sspBaseUrl>/redirect	https://idpvselfserviceportal.com:sspPort/redirect
SAS PCE with Keycloak agent	https://sspBaseUrl/redirect	https://sspBaseUrl/*	https://idpvselfserviceportal.com/*

Deploying Self-Service Portal

Run the following command to start the Self-Service Portal:

docker run -d --name <container-name> -it -d -p <host-https-port>:3001 -v <configurationfilepath>:/home/node/app/ExpressServer/config.js -v <certfolder>:/home/node/app/ssl/ <docker image>:<version>

Where,

• <container-name>: The name of the Virtual IDPrime Server container. It can be any value, but must be as per container naming guidelines of the docker.

  For example, idpvselfserviceportal

• <configurationfilepath > is the path of the host directory that contains relevant files or certificates

  For example, /var/thales/config.js

• <certfolder> is the path of the host directory that contains exported private key and certificate files (cert.pem, key.pem). For example, /var/thales/certs

• <host-https-port > Self-Service will be access on this port from the web browser. For example, 443

For example,

    docker run --name selfserviceportal -it -d -p 3001:3001 -v /var/thales/config.js:/home/node/app/ExpressServer/config.js -v /var/thales/certs:/home/node/app/ssl/ idpv_ssportal:2.3.1.62

Running Self-Service Portal

For running the Self-Service Portal on the web browser, a web URL(selfserviceportalURI) is needed which can be found in the following ways:

• It is generated while creating the tenant. The URL(selfserviceportalURI) can be found in the logs after tenant creation command. For more information, refer to Setting up Tenant Utility section.

Keyword	Structure	Syntax/Sample
selfserviceportalURI	https://<sspBaseUrl >/selfservice/<tenantCode>	https://idpvselfserviceportal.com /selfservice/RcEO2NIt Note: Mention the port number if running on a port other than 443. Example: https://idpvselfserviceportal.com:3001 /selfservice/RcEO2NIt

Supported Versions

The following software versions are supported:

Web Browsers

• Google Chrome (96.0.4664 or higher)

• Firefox (94.0.2 or higher)

• Microsoft Edge (87.0.664 or higher)

Mobile Operating System

• iOS (14.0 and above)

• Android (13.0 and above)

Identity Provider

• SafeNet Trusted Access

• Keycloak with SAS PCE

• PingFederate

• Okta

• Microsoft Entra ID

Requirements

To download smartcards or credentials on mobile device from Self-Service Portal, the following requirements apply:

• Make sure VMware Workspace ONE PIV-D Manager is installed on your device. You can download the application from Play Store or App Store for Android or iOS, respectively.

Prerequisites

The following prerequisites are required:

• Non-Mobile Device (Desktop client such as Windows and Linux)

• At least one active^[1] smartcard is available.

• User must be authorized to download credentials.

• User must be able to choose MobileOS. User is redirected to the OTP screen after Enter PIN screen as shown in step 2 of For Non-Mobile Devices.

• Mobile Device

  • At least one active^[1] smartcard available.

  • User should be authorized to download credentials.

  • User is not required to select MobileOS as it is automatically detected.

  Where,

  [1] - Inactive smartcards can be categorized as:

  • Smartcard that is locked.

  • Smartcard for which provisioning is not completed.

  • Smartcard that has no certificate available.

  • Smartcard that has no usable certificate.

Downloading the smartcard(s) on PIV-D

After meeting the prerequisites, perform the following steps:

1. Open the web browser and type the web URL generated during tenant creation (selfserviceportalURI). For more information, refer to Running Self-Service Portal section.

   There will be a prompt for authentication from configured IDP.

   

2. The following screen should be displayed. Click Start enrollment.

   

3. The following screen is displayed. Select a smartcard, and click Continue.

   

4. Enter your smartcard PIN, and click Continue.

   

Depending on the device type, perform the following steps:

For Non Mobile Devices

1. Select the OS type in the Select your device screen.

   

2. Depending on the selected OS type, user is redirected to the following QR screens:

   • For Android
     

   • For iOS
     

   Components of the QR Screen

   The following components are available on the QR screen:

   • QR Code:

     • A unique QR code is generated when each new user logs in or same user re-logs in/session expires.
     • The default validity of the QR code is 30 minutes.
     • Once the OTP is consumed for unlocking the QR code, the QR code gets invalidated.

   • OTP:

     • A unique OTP is generated when each new user logs in or same user re-logs in/session expires.
     • The default validity of the QR code is 30 minutes.

3. Click Continue in step 2 to complete the activation.

   The Activation Complete screen is displayed.

   

4. If you click Back in step 2 to return to the Select your device screen.

   Select the device OS, and click Continue, the new QR code with OTP is generated.

For Mobile Devices

1. After entering the PIN, the device OS is automatically detected, and the user is redirected to the QR screen.
   

2. Follow the step 2 to step 4 of For Non-Mobile Devices.

3. If you click the Back option in step 2, there are the following results:

   • In the case of the number of smartcards > 1, it is redirected to the Select Smartcard screen.

     

   • In case the Self-Service Portal is being used for SWS, it is redirected to the Start enrollment screen. For more details of a tenant which is specific for SWS, refer to Downloading the smartcard on PIV-D for users on SWS

     

Downloading the smartcard on PIV-D for users on SWS

The workflow for SWS Tenants is different for Self-Service Portal. SWS only uses certificates, hence the smartcards are not relevant here. Therefore, the Smartcard list and the Enter Pin screens are skipped.

Following workflow is valid for SWS tenants:

• Open the web URL(selfserviceportalURI) in the web browser, and click Start enrollment as given in Downloading the smartcard(s) on PIV-D

• For non-mobile devices, select the mobile OS type and user is redirected to the QR screen, refer to For Non Mobile Devices.

• For mobile devices, user is redirected to the QR screen directly from the Start enrollment screen, refer to For Mobile Devices.

Downloading Certificates on a Mobile Device using PIV-D

As a prerequisite, IDPV server and Self-Service Portal should be accessible on the device.

Perform the following steps to download certificates on your mobile device using PIV-D:

1. Log into the PIV-D application.

2. On the Select Provider screen, tap the THALES tile.

   

3. On the next screen, tap SCAN QR CODE to scan the QR code from the Self-Service Portal QR code screen.

   

   If the PIV-D application fails to scan the QR code,

   1. Open your mobile device camera and scan the QR code. This will generate a QR code string.

   2. Copy the string and paste it in the Paste QR code box as shown in the below screenshot.

   

4. Enter the one-time passcode (OTP) that you received on the Self-Service Portal QR-code screen and tap CONTINUE.

   

5. Set your Keystore passcode and tap Next. It is recommended keep to it same as your mobile device password. You will need this passcode while performing a PKI operation.

   

6. You will be redirected to the Install Credentials via KeyChain screen.

   1. Tap INSTALL.

      

   2. Select the VPN and app user certificate cretificate type and tap OK.

      

   3. Enter the password to extract the certificates. This password is already saved by PIV-D on your mobile device, so you can paste it from the clipboard. Tap OK.

      

   4. Enter a certificate name and tap OK.

      

      The certificate will be downloaded on your mobile device.

      

Performing a PKI Operation Using the Certificate

You can use a certificate to perform PKI operations on your mobile device, such as signing a PDF file.

The certificate must contain the Signing claim for PDF signing.

Perform the following steps:

1. On your mobile device, tap Settings and tap Signed Documents.

   

2. Select the PDF file that you want to sign and tap SIGN.

   

3. Enter the Keystore passcode that you set in step 5 of Downloading Certificates on a Mobile Device using PIV-D. Tap OK

   

4. Verify the signature on the PDF file and save the signed document.

   

Error message(s) and Warning(s) in Self-Service Portal

Based on type of error, the enclosed error messages gets displayed whenever server side authentication fails.

• Something-went-wrong – A common error page which may come due to any unexpected/non-generic error, refer logs for specific information.

• Not Authorized – This error page comes when user is authenticated from identity provider but don’t have required claims/roles to access IDPV server API data.

• No Access – This error page comes if entered tenant code is not valid or the express sever is not able to fetch tenant configuration details from IDPV server before initiating the identity provider authentication.

Following warning is being thrown by Self-Service Portal server if the user deploys and run the Self-Service Portal on port 443.
running on default https port 443. If the application is running in a docker container, then make sure the HTTPS default port is opened otherwise portal won't be accessible outside the docker container.

Advisory

While deploying the Self-Service portal and IDPV server on the same machine. Make sure both docker containers should run on different ports.