A newer version of this documentation is available.

View Latest

Installation and configuration

To install and configure the services that are required by Net iD Portal, install and configure the services in the following sequence:

  1. Install and configure the web service

  2. Install and configure the database service

  3. Install and configure the certificate service

Install and configure the web service

Server role

  1. Start the "Server Manager" in Windows Sever operating system.

  2. Start the "Add Roles and Features" wizard.

  3. Add the "Web Server (IIS)" role.

  4. Add the "Application Server" role including the sub roles: ".NET Framework 4.5", "COM+ Network Access" and "Web Server (IIS) Support".

  5. Close the "Server Manager" and restart the server.

NiP API

  1. Extract the NiP API files from the "WebServiceApplication" package (delivered from SecMaker AB) to an optional directory path on the local server. For example C:\Program Files\Net iD Portal\WebServiceApplication.

  2. Start the "Internet Information Services (IIS) Manager".

  3. Add a new "Application Pool" with an optional name. Set the ".NET CLR version" to 4.0.30319 and the "Managed pipeline mode" to Integrated.

  4. Open "Advanced Settings" of the created application pool. Set the "Application Pool Identity" to either ApplicationPoolIdentity as "Build-in account" or use a custom account that already has been configured as a service account in the environment. The service account is the physical account that need to access the other necessary services of the environment (i.e. database and certificate service).

  5. Create a new "Virtual Directory" or "Web Site" and set the physical path to the extracted NiP API path. Choose the "Application Pool" and set an optional "Alias".

  6. Test the NiP API by browsing and download the WSDL file (i.e. http://server/api/servicesoap.svc?singlewsdl).

  7. If using NiP API with SSL, open the web.Config file and modify the bindings from:

    <security mode="None"></security>

    to:

    <security mode="Transport">
<transport clientCredentialType="None"></transport>
</security>

NiP GUI

  1. Extract the NiP GUI files from package to an optional directory path on the local server. For example C:\Program Files\Net iD Portal\GUI.

  2. Open the "config.js" file and set backendUrl to created service. For example http://server/api/servicesoap.svc.

  3. Start the "Internet Information Services (IIS) Manager".

  4. Create a new "Virtual Directory" or "Web Site" and set the physical path to the extracted NiP GUI path. Choose the "Application Pool" and set an optional "Alias".

  5. Test the NiP GUI by browsing to the URL (i.e. http://server/gui/index.html).

Install and configure the database service

Microsoft SQL Server

  1. Start the setup wizard.

  2. Add the feature "Database Engine Services".

  3. Add the feature "Management Tools – Basic".

  4. Set the optional "Instance" name.

  5. Set the "Collation" mode to SQL_Latin1_General_CP1_CI_AS (Windows-1252 or CP-1252 are the character encodings).

  6. Set the "Authentication Mode" to use Windows Authentication account only. The database needs the service account that also will be used by the Application Pool described above.

Oracle MySQL

  1. Start the setup wizard.

  2. Add the feature: "MySQL Server".

  3. Add the feature: "MySQL Workbench".

  4. Set the "Collation" mode to UTF8_GENERAL_CI with default character set as UTF-8.

Install and configure the certificate service

Microsoft Certificate Authority (MSCA)

  1. Start the "Server Manager" in Windows Sever operating system.

  2. Start the "Add Roles and Features" wizard.

  3. Add the "Active Directory Certificate Services" role including the sub role Certification Authority.

The MSCA can be configured in different ways depending on purpose. The two main instance types for MSCA are:

Stand Alone CA

The Stand Alone CA has no external of extra calls when generating the end entity certificate. The Stand Alone CA only sets the CA signature of the certificate request and issues the certificate. All information about the information to be included in the end entity certificate needs to be included in the certificate request.

Enterprise CA

The Enterprise CA is the most common usage type for MSCA. The Enterprise CA has several certificate templates for generating end entity certificates more dynamically, especially when issuing certificates to different kind of users and computers.

NiP API supports both Stand Alone CA and Enterprise CA but also supports extensible enroll modes for both instance types:

Stamp

NiP API creates the certificate request in PKCS#10 format containing all information about the certificate and sends the request to the CA. The CA only makes the CA signature in the issuance process (stamp). This scenario is very useful when issuing computer certificates.

Modifier

NiP API creates the certificate request in PKCS#10 format that only contains information about the end-entity. The request is sent to the CA and NiP API modifies the rest of the certificate extensions content for the certificate that will be issued by the CA. This scenario is very useful when issuing certificates across domains and services.

Microsoft Enrollment Agent (Microsoft Enterprise CA only)

NiP API creates the certificate request containing information about the end entity and an enrollment agent in CMC format and sends it to the CA. The CA looks up the end entity object in the Microsoft Active Directory and issues the certificate to that object.

MSCA policy modifications

In some cases and scenarios, there must be some modifications done for the MSCA that overrides the default settings. These modifications can be done with the "certutil.exe" ("Certificate Utility") in Microsoft Windows platform. The MSCA service must be restarted after policies or settings have been changed. The most common policies and settings changes are:

  • Type: RequestDisposition
    Flags: REQDISP_ISSUE = 1, REQDISP_PENDINGFIRST = 256
    Command: certutil -setreq policy\RequestDisposition %FLAGS%
    Explanation: This command changes the policy of the request handling for the MSCA.

  • Type: EnableRequestExtensionList
    Flags: +%OID% (add extension) or -%OID% (remove extension)
    Command: certutil -setreg policy\EnableRequestExtensionList +%OID%
    Explanation: This command allows customized extensions in the issued certificate (i.e. certutil -setreg policy\EnableRequestExtensionList +1.3.6.1.5.5.7.1.3 sets the "Qualified Certificate" extension to be allowed in the request).

  • Type: RequestExtensionList
    Flags: +EDITF_REQUESTEXTENSIONLIST (add flag) or -EDITF_REQUESTEXTENSIONLIST (remove flag).
    Command: certutil -setreq policy\EditFlags +EDITF_REQUESTEXTENSIONLIST
    Explanation: This command allows customized extensions to be added into the issued certificate.

  • Type: AttributeEndDate
    Flags: +EDITF_ATTRIBUTEENDDATE (add flag) or -EDITF_ATTRIBUTEENDDATE (remove flag).
    Command: certutil -setreg policy\EditFlags +EDITF_ATTRIBUTEENDDATE
    Explanation: This command allows to customize the validity period of the certificate template within its time span, otherwise the validity of the issued certificate always will be validity specified in the certificate template (Enterprise CA only).

  • Type: BasicConstraintsCritical
    Flags: +EDITF_BASICCONSTRAINTSCRITICAL (add flag) or -EDITF_BASICCONSTRAINTSCRITICAL (remove flag).
    Command: certutil -setreg policy\EditFlags +EDITF_BASICCONSTRAINTSCRITICAL
    Explanation: This command sets the basic constraints as critical in the issued certificate.

  • Type: AttributeSubjectAltName2
    Flags: +EDITF_ATTRIBUTESUBJECTALTNAME2 (add flag) or -EDITF_ATTRIBUTESUBJECTALTNAME2 (remove flag).
    Command: certutil -setreg policy\EditFlags +EDITF_ATTRIBUTESUBJECTALTNAME2
    Explanation: This command allows NiP API to set the SubjectAlternativeName extension of the issued certificate.

  • Type: AllowRequestAttributeSubject
    Flags: +CRLF_ALLOW_REQUEST_ATTRIBUTE_SUBJECT (add flag) or
    -CRLF_ALLOW_REQUEST_ATTRIBUTE_SUBJECT (remove flag).
    Command: certutil -setreg ca\CRLFlags +CRLF_ALLOW_REQUEST_ATTRIBUTE_SUBJECT
    Explanation: This command allows customized subject names (or OIDs) in the subject of the issued certificate.

  • Type: SubjectTemplate
    Flags: +%OID% (add subject name attribute) or -%OID% (remove subject name attribute).
    Command: certutil -setreg ca\SubjectTemplate +%OID%
    Explanation: This command allows customized subject name attributes in the subject of the issued certificate. For example certutil -setreg ca\SubjectTemplate +2.5.4.5 sets the "SerialNumber" attribute to be allowed in the subject).

  • Type: RebuildModifiedSubjectOnly
    Flags: +CRLF_REBUILD_MODIFIED_SUBJECT_ONLY (add flag) or
    -CRLF_REBUILD_MODIFIED_SUBJECT_ONLY (remove flag).
    Command: certutil -setreg ca\CRLFlags +CRLF_REBUILD_MODIFIED_SUBJECT_ONLY
    Explanation: This command allows any custom OID in the subject of the issued certificate. There is no need to modify the "SubjectTemplate" described above. Note that this only works when enrollment mode is set to "Stamp" which means that all customized OIDs must be set in the certificate request. This will not work in "Modifier" enrollment mode.

  • Type: EnforceX500NameLengths
    Flags: 1 (add flag) or 0 (remove flag).
    Command: certutil -setreg ca\EnforceX500NameLengths 0
    Explanation: This command allows values in the subject name attribute to be larger than 64 characters (default).

  • Type: ValidityPeriod
    Flags: %PERIODSTRING% (Years, Months, Hours, Minutes, Seconds).
    Command: certutil -setreg ca\ValidityPeriod %PERIODSTRING%
    Explanation: This command sets the maximum validity period of the issued certificate (i.e. certutil -setreg ca\ValidityPeriod Years sets the maximum validity period to years). Note that this is only useful when using "Stand Alone CA" with enrollment mode as "Modifier". This command has no effect on "Enterprise CA" because the current certificate template overrides the validity maximum period.

  • Type: ValidityPeriodUnits
    Flags: %PERIODINTEGER%
    Command: certutil -setreg ca\ValidityPeriodUnits %PERIODINTEGER%
    Explanation: This command set the maximum validity period units of the issued certificate (i.e. certutil -setreg ca\ValidityPeriodUnits 2 sets the maximum validity period units to "2" (i.e. 2 Years if used with the example of "ValidityPeriod" above)). Note that this is only useful when using "Stand Alone CA" with enrollment mode as "Modifier". This command has no effect on "Enterprise CA" because the current certificate template overrides the maximum validity period. Note that the maximum period units cannot override the validity of the CA itself.

Setup MSCA as a Stand Alone CA and enrollment mode as Stamp:

  1. Set the CA instance as stand-alone root CA or subordinate CA.

  2. Set the "CSP" as RSA Microsoft Key Storage Provider (or ECDSA Microsoft Key Storage Provider if using ECC).

  3. Run the "Certificate Utility" command: certutil -setreq policy\RequestDisposition 1.
    The CA will now automatically issue the certificate.

Setup MSCA as a Stand Alone CA and enrollment mode as Modifier:

  1. Set the CA instance as stand-alone root CA or subordinate CA.

  2. Set the CSP as "RSA Microsoft Key Storage Provider" (or "ECDSA Microsoft Key Storage Provider" if using ECC).

  3. Run the "Certificate Utility" command: certutil -setreq policy\RequestDisposition 257.
    The CA will now set the request as pending before issuing the certificate.

Setup MSCA as an Enterprise CA and enrollment mode as Modifier:

  1. Set the CA instance as Enterprise root CA or subordinate CA.

  2. Set the CSP as RSA Microsoft Key Storage Provider (or ECDSA Microsoft Key Storage Provider if using ECC).

  3. Run the "Certificate Utility" command: certutil -setreq policy\RequestDisposition 257.
    The CA will now set the request as pending before issuing the certificate.

  4. Open the "Certificate Authority" snap-in module.

  5. Right-click the "Certificate Templates" and choose "Manage".

  6. Right-click the "User" template and choose the "Compability Settings" for the current environment.

  7. Set an optional "Template Display Name" and "Template Name" in the "General" tab. Make sure that "Publish in Active Directory" property is disabled.

  8. Set the "Purpose" in the "Request Handling" tab. Disable the "Allow private key to be exported" property.

  9. Set the "CSP" and "KeyLength" in the "Cryptography" tab.

  10. Set "CA certificate manager approval" in the "Issuance Requirements" tab.

  11. Set "Supply in the request" in the "Subject Name" tab.

  12. Click "OK".

  13. Right-click the "Certificate Templates" and choose "New" > "Certificate Template is issue".

  14. Choose the template that just has been created.

  15. Close the snap-in module and restart the MSCA service.

Setup MSCA as an Enterprise CA and enrollment mode as EnrollmentAgent:

  1. Set the CA instance as Enterprise root CA or subordinate CA.

  2. Set the CSP as RSA Microsoft Key Storage Provider (or ECDSA Microsoft Key Storage Provider if using ECC).

  3. Open the "Certificate Authority" snap-in module.

  4. Right-click the "Certificate Templates" and choose "Manage".

  5. Open "Enrollment Agent (Computer)" certificate template and open the "Security" tab.

  6. Add the server of the NiP API (i.e. webserver$) and set "Read" and "Enroll" as permissions to this account.

  7. Click "OK".

  8. Right-click the "Certificate Templates" and choose "New" > "Certificate Template is issue".

  9. Choose the template "Enrollment Agent (Computer)".

  10. Open the "Certificate" snap-in module on the server of the NiP API.

  11. Open the "Personal" folder and right-click the "Certificates" > "All tasks" > "Request New Certificate".

  12. Issue certificate from template "Enrollment Agent (Computer).

  13. Set the "Security Permissions" of the certificate (i.e. Computers and/or UserGroups).

Enterprise Java Beans Certificate Authority (EJBCA):

Please read the documentation on ejbca.org or contact Primekey for a professional installation of EJBCA.

  1. Install EJBCA.

  2. Setup the Certificate Authority.

  3. Create an administrator user that will be used as a web service user (i.e. ws-user) with correct privileges.

  4. Create a PKCS#12 file for the web service user and install the content of the PKCS#12 file on the current web server.

  5. Set permission rights for the private key so it`s accessible by NiP API service account.

  6. Set the web service user status to Generated to ensure that no additional certificates can be enrolled by mistake for this account.

  7. Test the EJBCA web service by browsing and download the WSDL file
    (i.e. https://ejbca:8443/ejbca/ejbcaws/ejbcaws?wsdl).

For more information on how to setup an EJBCA please read the documentation on the following link http://www.ejbca.org/.