You can use certificates to secure MDriven web endpoints, make certificate-authenticated outbound calls, and support certificate-based token scenarios; this page is for administrators and developers who need to choose, install, and diagnose the right certificate material.
Choose the certificate for the job
A certificate binds an identity to a public key. The associated private key is the sensitive part that proves control of that identity. Whether the private key is present determines what you can do with the certificate.
| Scenario | What you need | Important requirement |
|---|---|---|
| HTTPS/TLS for an MDriven web application | A server certificate whose identity matches the URL used by clients and by MDrivenServer | Install and bind it in the web-server configuration. See Documentation:IIS or Documentation:Serving MDriven with Nginx Server as a Proxy. |
| An outbound REST or SOAP request that must be signed with a client certificate | A client certificate with its private key, installed where the service runs | Configure the certificate thumbprint in the ViewModel as described in Documentation:Sign client rest request with certificate. |
| Verify a JWT or SAML2 token issued by another party | The issuer's public certificate/public key | A public certificate can verify a token but cannot issue a token. |
| Issue JWT or SAML2 tokens | A certificate or key material that includes the private key | The private key is required to sign and issue tokens. See Documentation:Authenticate with a jwt. |
For example, an external identity provider can provide a public certificate. You can use it to verify that a received token was signed by that provider, but you cannot use that public-only certificate to create a token as that provider.
Understand certificate files
When you obtain a certificate, you may receive only a certificate file. That file commonly contains the public certificate, not the private key. Importing such a file can be sufficient when you only need to trust or verify it, but it is not sufficient when the application must identify itself or sign data.
A PFX file is commonly used when you need to move a certificate together with its private key. Treat a PFX and its password as sensitive credentials.
| Material | Contains | Typical use |
|---|---|---|
| Public certificate | Public key and certificate identity | Trusting a certificate or verifying signatures. |
| Certificate with private key | Public certificate and private key | HTTPS server identity, client-certificate authentication, and token signing. |
| PFX export | A transferable package that can include the private key | Installing the same certificate on the server or service that must use it. |
Do not assume that a certificate file can be exported as a PFX. If the private key was not included when the certificate was imported, a PFX containing that private key cannot be created from that public-only import.
Import and export certificate material
Use the certificate-management procedure approved for your environment. The existing MDriven guidance identifies DigiCertUtil.exe as a tool for managing code-signing and SSL certificates, including situations where you need to export a certificate as PFX and standard Windows tools cannot do so.
Before exporting or deploying a certificate, confirm these points:
- The certificate includes the private key when the target scenario requires signing or client/server authentication.
- The certificate subject and names match the URL that will be used for HTTPS.
- The certificate is installed on every machine that actually makes the call or serves the endpoint.
- The runtime account can access the certificate store and private key.
- You have protected the PFX file and any export password.
For example, if a web application hosted on one server sends a signed request, installing the client certificate only on a developer workstation will not help. Install it on the server that initiates the request.
Configure HTTPS correctly
For a hosted MDriven application, the requested URL and the certificate must match. This includes calls that MDrivenServer makes to itself during intraprocess calls. A mismatch can produce a certificate error even when the certificate appears valid in a browser.
- Decide the HTTPS URL that users and the server will use.
- Obtain or create a certificate that matches that URL.
- Install and bind the certificate in your hosting stack.
- Test the same URL from the deployment environment.
- If a certificate error remains, verify the URL match, the trusted root chain, and the browser behavior.
Use Documentation:Fault-finding certificate problems in IIS for the IIS-specific checks. It also calls out the need for a trusted root when using a self-signed certificate and recommends testing with another browser. For IIS setup, see Documentation:IIS. For a reverse-proxy deployment, see Documentation:Serving MDriven with Nginx Server as a Proxy.
Develop with localhost
For local development, use localhost. If Chrome blocks a local HTTPS endpoint because its certificate is not trusted, the existing development guidance is to enable Chrome's insecure-localhost setting:
chrome://flags/#allow-insecure-localhost
This setting is for local development. Do not use it as a substitute for a valid, trusted certificate in a deployed environment.
Use a client certificate from a ViewModel
MDriven can locate a client certificate by thumbprint for outbound REST and SOAP calls. The detailed setup belongs in Documentation:Sign client rest request with certificate; follow that page when your ViewModel uses restGet, restPost, or SoapCall.
The essential configuration is:
- Add a root ViewModel column of type string named
ClientCertThumbPrint. The name is case-sensitive. - Supply the thumbprint in the ViewModel that performs the outbound call.
- Install the certificate, including its private key when required, in the certificate store available to the account that runs the service.
Enter the thumbprint without spaces. For example, convert:
78 3f f5 92 55 c3 7d 1d 6b 68 fd b4 a7 a5 cc e7 5f 26 ee 78
to:
783ff59255c37d1d6b68fdb4a7a5cce75f26ee78
A copied thumbprint can contain an invisible Unicode character, causing the lookup to fail even though the visible characters look correct. If this happens, paste the value into Notepad, save it as ANSI, reopen it, remove the unexpected character, and use the cleaned value.
Deployment considerations
On an on-premises installation, install the certificate on each server machine that needs to use it. The certificate store must be accessible to the user that runs the service; the client-certificate guidance specifically refers to X509Store(StoreName.My, StoreLocation.CurrentUser).
For an Azure web application, upload the certificate and configure the application so the app can access it. The existing Swish guidance uses the application setting WEBSITE_LOAD_CERTIFICATES with value * to make uploaded certificates available to the web app. See Documentation:Swish for that payment-specific implementation.
Some integrations impose their own certificate-store requirements. For example, Documentation:BankId states that BankID currently requires a trusted certificate store.
Keep certificate issues separate from SQL trust issues
A message such as The certificate chain was issued by an authority that is not trusted can also occur when connecting to SQL Server. That is a SQL connection-setting issue, not necessarily an HTTPS binding problem. See Documentation:SQL not trusted for the applicable connection-string guidance.
Troubleshoot certificate errors
Work through these checks in order:
- Confirm the purpose: server HTTPS, client authentication, token verification, or token signing.
- Confirm whether the private key is required and present.
- Confirm that the certificate identity matches the URL for HTTPS.
- Confirm that the certificate is installed on the machine that performs the action.
- Confirm that the service account can find and use the certificate.
- For a ViewModel client certificate, confirm the exact root column name
ClientCertThumbPrintand remove spaces or invisible characters from its value. - Confirm that the certificate chain is trusted by the relevant client or server.
- Test in another browser when diagnosing browser-specific HTTPS behavior.