Introduction
From version 5.7 it is possible to configure a connection to an OpenID Connect (OIDC) compatible identity provider. OIDC 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows clients to verify the identity of the end-user based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner. This can be used to authenticate a user when performing self-service operations on managed credential tokens in vSEC:CMS.
This article will cover the following:
- Setup a connection template to an OIDC provider;
- Create a self-service template where we use the OIDC provider to authenticate the user;
- Issue a Windows logon certificate to a credential using the self-service template;
- Log onto a Windows client using the issued credential.
The PKI used here will be a Microsoft Certificate Authority (CA). If another CA is to be used please refer to the Administration guide for details on configuring a connection to such a CA.
The OIDC provider that will be used for this article will be from Google.
It will be required that at minimum you have already successfully completed the configuration steps described in the article Setup Evaluation Version of vSEC:CMS. The instructions in this document are applicable regardless of whether you are running the evaluation version or a production version.
The server where vSEC:CMS is installed needs to be configured to use IPv4. If the server is using IPv6 then you can disable IPv6 by setting the below registry on the server: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip6\Parameters] "DisabledComponents"=dword:000000ff
OIDC Connection
If you don’t have a connection for self-service already set up then from Options - Connections click the Add button and select OAuth Identity Provider (IdP) and click Ok. Enter a name in the Template name field and click the Get button. Enter the appropriate identity provider into the URL field, along with the Client ID and Client Secret in the fields provided and click Ok.
If all the details are valid then you will see information populated in the OpenID Connect Provider window. The Provider URL is the actual URL of your OIDC provider. The Configuration is the public URL that can be pasted into a browser where you can see additional information. The Claims list the actual claims available that can be used (see below).
The claims listed are the default claims available from the well known endpoint. If you add optional claims these will not be listed here as these are application specific.
In the User Directory section select your directory that should be used from the Directory drop-down field. In the User ID mapping field enter the LDAP compliant query that will be run to validate that the user exists in your organizations directory and also to derive the users DN that the certificate credential will be issued to if an issuance is being performed. For example, if it is required to authenticate the user by checking your directory for the email address that can be retrieved from the user’s JSON ID Token object, then enter (mail=###email###) into the User ID mapping field, where mail is the user directory attribute name and ###email### is the claim from the JSON ID Token object.
The ### characters need to be used here so vSEC:CMS knows where it should put the value(s) from the claim.
If you are using EntraID and want to use the UserPrincipalName (upn) attribute then you need to add this as an optional claim as Token type ID like in example below:
Enable Fail if more than one user ID found if the authentication flow should fail if more than one user is returned from the LDAP query. Enter the Redirect URL into the field which is the back-end service that the OIDC should redirect to, for example, http://my-cms-server:<port>/oidc. Click the Configure server button to configure the vSEC:CMS web service that the OIDC provider needs to redirect back to. The service that will be used here is the vSEC:CMS User Self-Service. You will need to have configured this already in your environment. Normally SSL is used to secure the communication channel, therefore enable the Use SSL checkbox and select an SSL/TLS certificate to be used from the Server certificate drop-down box that is available on the server. Enter port number different from what was configured for the vSEC:CMS User Self-Service connection. Click Ok to save and close.
Click the Test button to perform an actual test on a user in your environment.
Self-Service Connection
If you don’t have a connection for self-service already set up then from Options - Connections click the Add button and select User Self-Service and click Ok. Enable the enable SOAP checkbox as we will use SOAP in this example. Depending on your environment settings enter a hostname and port to listen on. You can also setup support for SSL if you wish to use HTTPS for secure communication between the client and server. If you use SSL it is important that the HostIP address field is entered with the name of the server as it appears in the SSL certificate. The SSL certificate should be a machine certificate available on the vSEC:CMS server.
Make sure that the vSEC:CMS - User Self-Service service is running after you configure this in Windows services.
Credential Configuration
Ensure that a credential configuration exists for the credential that you are going to use here. See the article Add Credential Configuration before starting below.
1. From Templates - Card Templates click the Add button.
Click the Edit link beside General. Enter a template name. Presuming that you are using one of the minidriver credentials that is supported by vSEC:CMS select Minidriver (Generic minidriver card) for Card type.
Click the Manage button beside Self-service using the following template. Click the Add button. Enter a template name and enable Self-issuance enabled and Retire card enabled checkboxes. From the User Authentication for PIN Unblock drop-down list select the OIDC connection configure earlier. Leave all other settings as is and click the Save button to save and close.
Click Close and from the main General dialog enable Self-service using the following template and from the drop-down list select the template just created. Leave all other settings as is and click Ok to save and close the dialog.
2. Click the Edit link beside Issue Card. Select the checkbox Automatically initiate cards after issuance and Issue by user(s) radio button. Click the Configure button in the User ID Options section. Select the AD connection already configured from User ID from drop down list and select the OIDC connection template created earlier from Authenticate user using drop down list. Click Ok to save and close.
In the Enroll Certificate Options section enable Enroll certificate(s) checkbox and click the Add button. Select the Windows logon certificate template created earlier and click Ok. Leave all other settings as is and scroll down to the bottom of the dialog and click Ok to save and close.
3. Click Ok to save and close the template configuration dialog.
Issue Credential
On a client machine it will be necessary to install the vSEC:CMS User Self-Service (USS) application. Use the vSEC:CMS Client MSI to install this component. It is recommended to install the USS silently as it is possible to pass in the URL link to the backend vSEC:CMS server that the USS needs to communicate with. This will remove the requirement to manually configure the USS to communicate with the backend in this case.
Open a command Window as administrator and change to the location where the MSI installer is located.
msiexec /i "vSEC_CMS Client 64bit.msi" /quiet ADDLOCAL=USS USSSOAP="http://172.16.86.106:8443/uss"
Where USSSOAP points to the backend server where vSEC:CMS is installed. Important to append /uss to the end of the server hostname/IP. The communication between USS and server is HTTP(S) using SOAP protocol.
The client host will automatically reboot when running above command so make sure you have saved any material you may be working on when performing this task.
Depending on the credential that you are testing with it will be necessary to have the appropriate credential drivers installed on your host. Please check with the credential provider that you have the correct credential drivers installed.
Start the My Smartcard from the shortcut icon on the client desktop. Go to the My Profile page. With the credential attached that is to be issued click the Issue button.
You will now be requested to authenticate using your OIDC credential. In this example we are using Google as the OIDC provider.
In this example environment 2-step verification is required.
The credential template is configured to use the user’s email address retrieved from the user’s JSON ID Token object to validate that the user is valid in AD and authenticate.
At the end of the process you will be prompted to enter a PIN for the credential to complete the flow.
Once you complete this then the credential can be used to log onto your domain environment.