SUNET TCS 2020- Information for administrators

This is for administrators at SUNET TCS members for the 2020- "Sectigo generation" of the SUNET TCS service.

For the 2015-2020 "DigiCert generation" of the SUNET TCS Service, please see SUNET TCS 2015-2020 FAQ for administrators. End users, please see SUNET TCS documentation at your organization.

Our SUNET instance of SCM

Our SUNET instance of the Sectigo Certificate Manager is at https://cert-manager.com/customer/sunet

To access it, you need to have your organization and your admin user(s) set up. See below under "Getting access to the system".

Getting help

Help from SUNET TCS

Email tcs@sunet.se after making sure that this document does not contain the answer to your question or a solution to your problem.

Help from Sectigo Support

If instructed by SUNET TCS or this document, contact Sectigo Support using https://sectigo.com/support-ticket with your support question/problem. Unless instructed otherwise, select "SCM Support" as the reason for the ticket. In the description, include a line saying "We are a SUNET member of the GEANT TCS service, using the https://cert-manager.com/customer/sunet SCM instance."

Sectigo Documentation

Sectigo documentation can be found at https://support.sectigo.com/Com_KnowledgeProductPage?c=Sectigo_Certificate_Manager_SCM

Some highlights:

  • "SCM - Sectigo® Certificate Manager Quick Start Guide" is a short introduction to the SCM system
  • "SCM - Sectigo Certificate Manager Administrator's Guide" is the very much longer description
  • "SCM - Sectigo Certificate Manager REST API" describes the REST API

Differences from the DigiCert generation 2015-2020

New vendor, new web interface

Sectigo is the new vendor for TCS instead of DigiCert. We are using their Sectigo Certificate Manager (SCM) instead of DigiCert CertCentral. The rest of this section describes the most important changes you need to understand.

No "division" objects in the new system

There is no concept of divisions in SCM as there was in DigiCert CertCentral.

  • SUNET TCS has an instance of SCM at https://cert-manager.com/customer/sunet which is used by all SUNET TCS administrators (at your level and at the SUNET "superuser" level) but not by GEANT TCS members from other countries.
  • At the SUNET level, we cannot just create a division for a SUNET TCS member and ask you to create an organization object yourselves with all relevant information, as you did in CertCentral. We have to create an Organization in the system to be able to add you. See below for more practical information on how you join.
  • If you need to validate another organization (due to the need to have something different in the O= field of the certificates), that new organization will be "at the same level" as your original organization and there is no division that contains them. You will have acess to both organization due to the fact that we/you will add the same admins for both organizations.

No "User level users"

In DigiCert CertCentral, there were two basic kind of users: "Administrators", who could order/approve certificates, change settings and do other admin level stuff, and "Users" who could only request certificates (but who were nevertheless authenticated by logging into CertCental just like the Administrators).

In the SCM, there are basically only Administrator level users. In fact, the SCM does not talk about users, it talks about admins. That means that you cannot have users logging in to the SCM who can only request certificates. See below under "SSL certificates" for solutions to this.

Departments

The SCM lets you create Departments under Organizations. Just like the Organization name is what goes into the O= of a certificate, the Department name is what goes into the OU= of a certificate. You can use Departments in two ways:

  • Just as a tool to sort certificates and get the correct OU= set, but it will still be the Organization's admins doing the approval.
  • To delegate approval of certificates to department admins for their department. In most(?) cases that would be combined with registering a subdomain (or a completely different domain) and restrict the department to that.

MRAO, RAO, DRAO!

There are three levels of admins in the SCM, all called something with RAO (Registration Authority Officer) in the name:

  • MRAO: the "superuser level" for SUNET people that can work with all organizations, departments, domain, certificates, admins, etc.
  • RAO: the admin level for working with an organization and the departments, domains, certificates, admins etc that belong to that organization.
  • DRAO: the admin level for working with a department, and the domains, certificates, admins etc that belong to that department.

It is a bit more complicated than that: a RAO is connected to one or more organizations, and a DRAO to one or more departments, and there is also the possibility to only have the right for SSL certificates, client certificates and/or code signing certificates. Thus, an admin could be "RAO - SSL Certificates" and "RAO - client certificates" for Organization A, while also being "DRAO - SSL Certificates" for a department belonging to another organization.

The first admin you will get when joining with your organization will be RAO for all certificate types and for your organization.

Getting access to the system

Members of the "Digicert generation" (2015-2020) service

First of all, if you are doing this before 2020-04-16, visit https://doodle.com/poll/6wgkprntgcve4ptb and select one of the three video meetings to participate in. You will be able to get information, ask for clarifications etc. Also, we will be able to "batch" the handling of new organizations and admins to match the meetings to make it less resource intensive.

To get access to the new system, email tcs@sunet.se with a subject line like "TCS2020: organization name" and tell us:

  • First name, last name, email and preferred user name for the first admin (RAO) of your organization. That person should be a current Administrator in the DigiCert CertCental system.
  • Organization name, adress line, postal code, city and county (län).

We know that Sectigo uses at least https://www.infobel.com/en/sweden and https://proff.se/ to check address and postal code, so please try to find a record there for your organization and use that address line and postal code if it is not obviously wrong (it's not likely that people will rely on the address information in your OV certificates to send you paper mail...) If you try to use other address/postal code information you risk having your organization validation delayed.

New members

If you have not been a member of the 2015-2020 "DigiCert generation" of the service, you are still welcome to join. SUNET TCS is available to all SUNET customers without extra charge. Contact tcs@sunet.se about membership in the service. Do not send any paper documents before that.

Please note that during the spring of 2020 we are prioritizing bringing the current members over to the new service.

Validation

Domains

You must validate one or more domains before you can have certificates issued. There are multiple steps in this process. This is how you add the doman example.org:

  1. Make sure that you are not having CAA records in your DNS zone that forbids Sectigo from issuing certificates for the domain. If that is the case, domain validation will fail too. Having no CAA records is OK, as is having CAA records mentioning "sectigo.com" as approved.
  2. Go to Settings → Domains → Delegations and press the Add button. Fill in the domain name (example.org) and the optional description. Select the type of certificates (SSL, client, CS) that should be enabled for this domain. For your main domain you would typically enable all of them, but for most additional domains you would only enable SSL certificates. If you have set up Departments and this domain should be delegated to the DRAOs of that department, expand the selection line and enable the domain for the right department and the appropriate types too.
  3. Use Add again, embrace the cargo cult, and redo exactly the same step for the domain name with "*." prepended to it (*.example.org in our example).
  4. Wait for a SUNET MRAO to approve your domain delegations. Unfortunately, this step is necessary at this time, but we have asked Sectigo to remove it. When this is done, the delegation status will be Approved and you can proceed to the next step.
  5. Switch from the Delegations to the DCV tab.  Click on the the right line to check it, and use the DCV button that appears to initiate DCV. Select method:
    • Email means that your select one of the five allowed addresses for the domain, and then receive and handle an email sent to that address. For our example, it would be one of "admin@example.org", "administrator@example.org", "hostmaster@example.org", "postmaster@example.org" or "webmaster@example.org".
    • CNAME means that you will be instructed to put a CNAME record with a hash value name in your DNS zone, pointing to another hash value. The system will tell you the values.
    • HTTP/HTTPS means that you will be instructed to put certain contents in a file with a certain name on the web server for your domain name.
  6. Follow the instructions for the method you selected. We have noted that when using the email method, it is typical to told that the code was right, but that there was some other error. If the next step is OK, do not get stuck on that.
  7. When the validation is OK, you will see Validation Status as Validated in the DCV tab. In the Delegations tab, the domain itself should also be shown as Validated. The extra record with "*." prepended will still show as Not Validated for some time (hours to a day) and will then be updated to be Validated too.
  8. You are now ready to use this domain and its subdomains for certificate requests.

Additional organizations

If you need additional organization names (values for the O= part of a certificate), that will have to be added by a SUNET MRAO for you. Follow the same steps as for your first organization (see above under "Getting access to the system"), but instead of providing information about a "first admin", tell us the usernames for the administrators of your "main organization" that should also be RAOs for the new organization.

Note: you will not add an extra organization ("Smorgasboda Hogskola" in addition to "Smörgåsboda Högskola") for a name without non-ASCII characters for grid certificates, as that will be handled differently. We will update this document when Sectigo has provided the details.

Departments

To add a department:

  • Go to Settings → Organizations and click on the organization line to check it, then use the Departments button to bring up the listing window and press Add.
  • Fill in the desired OU= name component in the Department Name field. The rest of the name components will be as for your organization.
  • Select the Client Certificate tab and disable Key Recovery for MRAO and DRAO ("Allow Key Recovery by Master Administrators" and "Allow Key Recovery by Department Administrators", respectively). It will already be disabled for RAOs as that was part of the organization setup done by SUNET.
  • Do not fret over other options on the various tabs, as they can be changed later. Do not enable or change things you do not understand. Finish using the OK button.

Admins connected to the department

You can now go on to create admins (see below) that are DRAOs connected to just this department instead of being RAOs for the whole organization.

Domains connected to the department

If you add department admins (DRAOs) that can approve certificates for their department, you will most likely want to limit them to their own domain (department-example.com) or a subdomain of your main domain (department.example.org) if we imagine that your main domain is example.org.

In the first case with a completely new domain for the department, follow the normal domain validation procedure above to add department-example.com and *.department-example.com with delegation to the department and initiate DCV as you did for your main domain.

In the second case with a subdomain of your already validated main domain, you will still add department.example.org and *.departement.example.org with delegation to the department but you will not have to initiate DCV again, as the SCM is smart enough to know that example.org is already validated. As for your main domain, you should expect department.example.org to show as Validated at once, and *.department.example.org with some delay.

Admins

You create additional admins (RAOs for your whole organization or DRAOs for departments you have created) under the Admins tab with the Add button. You can also edit existing admins by clicking on the line to check them and then using the Edit button.

  • Fill in login (with a suitable user name), email, forename and surname. We advice you to leave the rest of the contact information empty, as it is not needed.
  • Select "Your institution" as Identity Provider and fill in the admin's ePPN ("SWAMID identity") in IdP Person Id to enable the admin to login via SWAMID when SAML has been set up correctly.
  • A password has to be provided for a new admin. The first time they login they will have to change it.
  • Select the desired privileges under Privileges. Do not check "WS API Use Only" (will be explained later).
  • Select the desired roles under Roles which means selecting the right combinations of level (RAO for your organization or DRAO for a department you have created) and certificate type (SSL, client or code signing).
  • When done, you have to communicate the selected password to the new admin (it is not emailed by the system).

We strongly recommend that you create personal admin users (not shared ones), to be able to see who has done what in the system.

It has been reported that some privileges cannot be assigned by one RAO to another. If that affects you, email tcs@sunet.se to have it fixed manually.

SSL Certificates

Applying for and approving certificates in the SCM as an admin

Go to Certificates → SSL Certificates and press Add to request a certificate.

  • Select the Manual creation of CSR mode
  • Provide a CSR by pasting it into the text area or upload it as a file using the Upload CSR button.
  • Select and fill in the right information in the Basic info step. Make sure you select a multi-domain certificate type to get a text box to fill in Subject Alternative Names if needed. If you request this on behalf of somebody else, you can add their email address as External Requester.
  • You can use "Click here for advanced options" to get access to a comment field where you can enter information you want to be able to see later. Do not remove address fields using the Remove checkboxes as that seems to cause the certificate to be stalled as the information will not match the pre-validated organization information.
  • On the next screen, accept or decline auto-renewal and finish with OK.

If your admin has the "Allow SSL auto approve" privilege selected, the certificate will be automatically approved (which makes sense, because why would you have entered all the information above if you did not want to approve the certificate?) and will show up as "Applied".

If your admin does not have that privilege selected, the certificate will show up as "Requested" and you will have to approve it by selecting it and using the Approve button.

When the certificate has been issued, its status will be shown as "Issued" and you will get an email about it.

If needed, you can also download the certificate by clicking on the line to check it and using the Details button, then the Select button to the right of "Download The Certificate".

EV Certificates

If you need EV certificates, talk to tcs@sunet.se about how to proceed, as the best procedure will not be to just request an individual EV certificate. Also, we would like to work with you to document the process, so we can document it for the benefit of other members.

Grid Certificates

We are waiting for the grid certificate profiles to be correct before advising you about them.

Allowing non-admins to request certificates

You can allow persons who are not admins in the SCM to request certificates ("enroll" in Sectigo-speak). To do that, go to Settings → Organizations and select your organization and select Edit. (Or, if this should apply only to a departement, after selecting the organization, use the Departments button, select the department, and use Edit on that instead).

  • On the SSL Certificate tab, enable Self Enrollment and put a shared secret value in Access Code and copy the URL present below that field. You can now hand out this URL to persons who can use it with the access code to access the Certificate enrollment page for non-admins. As you can see when you test using it, it contains approximately the same fields as the "Add Certificate" pages in the SCM itself. Be aware that the email address is not checked (more than for having the right domain) so you need an out-of-band method of authenticating the requestor.
  • If you have SAML attribute release working towards Sectigo (see "SAML Configuration" below), you can also enable "Self Enrollment via SAML", keep the Access Code secret and hand out the URL below the Token field to users. They will then have to authenticate using SAML before getting to the same kind of enrollment form as above. As the email address will now come from your IdP via SAML you can be more confident that it is correct, but it is up to you to decide if it is good enough, or you still will require additional conformation out-of-band before approving.
  • Do not enable "Automatically Approve Self Enrollment Requests". At least, you will want to manually approve certificate requests arriving via this route!
  • While you are at it, you will want to Customize the Server Software so the users are not presented with a gazillion choices. Also, you might also want to customize the SSL Types for the Enrollment Form (on the right-hand side), to stop users from selecting certificate types you do not want them to. You can still keep the ability to select them in the SCM (the left-hand Admin UI selection).

Client Certificates

Self-service portal via SAML

Sectigo will provide a self-service portal for requesting client certificates, matching the work-flow seen with the DigiCert portal (digicert.com/sso) and the earlier Confusa portal. That is, an end-user logs in via SAML authentication, selects the appropriate options and gets a certificate back.

The self-service portal is under development. We will update this section when it is ready for testing.

Issuing client certificates using the SCM

While this is not supposed to be the main route when the self-service portal is in place, this is how you can issue personal certificates using the SCM:

  • As a RAO, go to Certificates → Client Certificates and use the Add button. Select the appropriate Organization, Department and Domain. Fill in the Email Address and the Common Name. Fill in the separate name fields. Leave Secret ID blank and Validation Type Standard.
  • You have now added the person, rather than a certificate. Click the person to check the line and use the Certificates button. There, use Send invitation to send an invitation email to the user, containing a nonce that authorized that user to create a client certificate.
  • The user will have to provide a Password (that will be used to encrypt the generated PKCS#12 file) and a Passphrase (that can be used to revoke the certificate without your assistance), as well as accept a click-through license.
  • The user will then receive a PKCS#12 file containing the key, certificate and chain ready for importing in web browsers etc.

Things worth noting:

  • Yes, the key is generated on the server side. There is no option of uploading a CSR to keep use a key generated on the client side. This may not be acceptable for users due to policy (not allowed to have the key generated on the server side) or technical reasons (key not exportable from hardware device). For the self-service portal, it will be required that the user is offered to upload a CSR, and then gets certificate+chain back, instead of key+certificate+chain.
  • There is also the option of enabling a AccessCode, which is a shared secret between you and all users than enable them to get a client certificate as long as they have access to their email. We advise you not to use that.
  • There is also the possibility to enter a SecretID per user, to enable them to get a client certificate by entering that together with their email address. For occasional client certificates, we do not see the upside of this as compared to the invitation method above, and for bulk issuing we will rely on the self-service portal via SAML as soon as that is ready.

Code Signing Certificates

We will update this section when a SUNET TCS member has found the need for a code signing certificate, gone through the procedure and shared the experience with us.

Notifications

Under Settings → Notifications you can add and edit what notifications the system will send you when certain conditions are met. Use the Add button to have a look at the various Notification Types that are available.

  • You should add at least a notification for SSL Expiration to make sure you get expiration emails matching the ones you got from the earlier systems. Also DCV Expiration should be added for the same reason.
  • If you have made it possible for non-admins to request certificates (see above), you may also want to get SSL Awaiting Approval to be aware that there is a request to approve.
  • Please do not enable "Notify MRAO Admin(s)" as that would send email to the SUNET level "superusers" too.

If you have a need to change the text in the emails sent from the system, you can do that under Settings → Templates → Email TemplateIf you do, please report your experience with that feature (good or bad) to tcs@sunet.se.

SAML Configuration

Configure your IdP to work with Sectigo

SAML login is activated for the SUNET instance of SCM but you need configure the attribute manually in your Identity Provider due to that the SCM entity in metadata has no defined entity category. The reason behind this is that Sectigo has registered their Service Provider in inCommon and they can't issue the European only entity category .GÉANT Dataprotection Code of Conduct.

The following attributes should be released to the entityId https://cert-manager.com/shibboleth:

  • eduPersonPrincipalName (urn:oid:1.3.6.1.4.1.5923.1.1.1.6)
  • mail (urn:oid:0.9.2342.19200300.100.1.3)
  • displayName (urn:oid:2.16.840.1.113730.3.1.241)
  • givenName (urn:oid:2.5.4.42)
  • sn (urn:oid:2.5.4.4)

SWAMID has added the needed attribute release at the end of the current Shibboleth IdP best practice Example of a standard attribute filter for Shibboleth IdP v3.4.0 and above and in Manual attribute releases with ADFS Toolkit. If your Identty Provider uses this example filter uncomment the release configuration for Sectigo SCM and the correct attributes will be released.

Test that your IdP is correctly configured

After your Identity Provider administrators has configured the attribute release you should test it at https://cert-manager.com/customer/sunet/ssocheck. In this test only eduPersonPrincipalName and mail is required but for the upcoming personal certificates givenName, sn and displayName (not displayed in the test) will be required.

Configure SCM

When you have verified that your IdP is correctly configured, you can go on to configure use of SAML authentication:

  • To use federated login in the SCM portal you need to go into all your current RAO and DRAO admin accounts (Admins) and change the field Identity provider to "Your institution" and the field IdP Person Id to the ePPN (eduPersonPrincipalName) of the admin. If you don't do this manual mapping of eduPersonPrincipalName to the admin account then a much more insecure automatic mapping by mail address will be done at first SAML login. Right now there is a annoying known bug when using the SAML integration. The SAML integration picks up the name from the SAML assertion but don't handle character encoding correct.
  • See above under "Allowing non-admins to request certificates" for information about "Self Enrollment via SAML" for SSL certificates.

Using the REST API

Sectigo REST API documentation can be found at https://support.sectigo.com/Com_KnowledgeProductPage?c=Sectigo_Certificate_Manager_SCM in the "SCM - Sectigo Certificate Manager REST API"  document.

Authentication is via login name and password for a RAO or DRAO admin. The customerUri is "sunet".

We recommend that your create separate RAO or DRAO admins to use with the API instead of reusing the same admins as for web UI work. To create an API-only admin:

  • Use your RAO to create the new admin as you would create a "normal web UI admin", including setting a temporary password. You will not be able to use the API with this temporary password.
  • Login to the new admin in the SCM and perform the mandatory initial password change for it.
  • Back with your original RAO, edit the new admin and set the "WS API use only" flag for it.

More gotchas we have discovered, so you do not have to discover them too:

  • To be allowed to use the API calls for handling certificates, you must edit the appropriate Organization or Department object, and on the SSL Certificate tab, enable the Web API checkbox. You will be required to provide a value for the Secret Key field too. Enter a good random value there and promptly forget it (it is not used for the current REST API but for an older SOAP API).
  • Be aware that the "serverType": -1 in their certificate enroll example refers to the "other" Server Software type, so if you have removed that when cleaning up useless Server Software types, that example will not work.

As inspiration for API use, Fredrik Domeij at UmU has provided bash scripts to request and retrieve certificates. You find them as umu-example-api-bash.tar.

 ACME support

There is support for ACME and some of the test members have started to try that. We will update this section as we get feedback.



  • No labels