This document describes how to get and set up a personal certificate (also called a grid user certificate). For instructions on getting service and host certificates, you're in the wrong place. See Get Host and Service Certificates.
Getting a User Certificate¶
This section describes how to get and set up a personal certificate to use on OSG. Currently you can get a certificate from either the OSG CA or from CILogon. After May 31st, you will only be able to get a certificate issued by CILogon. Other CAs may be used; if your virtual organization (VO) requires that you get a certificate from a different CA, contact your VO Support Center for instructions.
Know your responsibilities¶
When you request a certificate your provide some public personal information about yourself; name, email address, phone number, and which VO (virtual organization) you belong to. If any of this information changes after you have your certificate you should notify OSG (and probably VO) of the changes. For the OSG RA send email to osg-ra at opensciencegrid dot org.
Your name and email address are encoded into the signed certificate and if either of those change (usually email address) then you should request a new certificate with the correct information and revoke the old certificate.
Getting a Certificate from CILogon¶
You will have to obtain your user certificate using the CILogon web UI. Follow the steps below to get an user certificate:
First, either search for your institution and select it or scroll through list and do the same.
Make sure to select your educational institution from CILogon's list. For instance, do not use your Google ID or GitHub ID.
Log Onbutton and enter your instutional credentials.
- Upon successfully entering your credentials, you'll get a page asking for you to enter a password. Enter a password that is at least 12 characters long and then click on the
Get New Certificatebutton.
- The web page will generate a
usercred.p12file and prompt you to download it. The certiticate will be protected using the password you entered in the prior step.
Getting a Certificate from the OSG CA¶
There are two different ways to obtain your certificate, either via a command line interface, or through a web browser. The links below will guide you through whichever method you choose. The command line method is generally simpler and less prone to errors than using a web browser but it may require extra setup and package installation the first time you do it. Most people end up needing their certificate for both command line grid use and web browser use and it is generally easier to import your certificate into your browser (and email client) from the command line certificate files than to export your certificate from your web browser to use on the command line. This is because of the large variety of web browsers each with its own way to deal with certificates. If you will use the certificate ONLY in your web browser then requesting it from your browser is probably the easiest method.
PKCS12 (.p12) vs PEM format¶
Your certificate and key pair can be stored as separate files, by default named
~/.globus/userkey.pem, or they can be bundled in a single file in PKCS12 (Public Key Cryptography Standard #12), by default named
~/.globus/usercred.p12. All OSG user tools works with both formats. Unless you specify a name in the command, they look first for the certificate/key pair default names, then for the PKCS12 default name and use the first one they find. PKCS 12 is a single file, convenient to move and used by many softwares, e.g. the Web browsers (so you don't need conversions).
Anyway note that the PKCS12 bundle includes normally the certificate, the key and also the CA certificate (or a certificate chain) validating your certificate. In the rare (but possible) case where the CA certificate expires before your certificate this may lead to the creation of a proxy without VOMS attributes and confusing error messages where it is not clear if the problem is with the host, remote server or the certificate, e.g. "Error: Error during SSL handshake:Either proxy or user certificate are expired." or "error:80066423:lib(128):verify_callback:remote certificate has expired:sslutils.c:1963 remote certificate has expired".
[email protected] $ voms-proxy-init -debug Detected Globus version: 2.2 Unspecified proxy version, settling on Globus version: 2 Number of bits in key :1024 Files being used: CA certificate file: none Trusted certificates directory : /etc/grid-security/certificates Proxy certificate file : /tmp/x509up_u20003 User certificate file: /home/user/.globus/usercred.p12 User key file: /home/user/.globus/usercred.p12 Output to /tmp/x509up_u20003 Enter GRID pass phrase for this identity: Your identity: /DC=org/DC=doegrids/OU=People/CN=First Lastname 12345 Creating proxy to /tmp/x509up_u20003 .............++++++ .....................++++++ Done Your proxy is valid until Fri Aug 9 00:18:07 2013 Error: Certificate verify failed. error:80066423:lib(128):verify_callback:remote certificate has expired:sslutils.c:1963 remote certificate has expired Function: verify_callback error:80066412:lib(128):verify_callback:certificate::sslutils.c:2283 subject=/DC=org/DC=DOEGrids/OU=Certificate Authorities/CN=DOEGrids CA 1 issuer =/DC=net/DC=ES/O=ESnet/OU=Certificate Authorities/CN=ESnet Root CA 1 certificate: subject=/DC=org/DC=DOEGrids/OU=Certificate Authorities/CN=DOEGrids CA 1 issuer =/DC=net/DC=ES/O=ESnet/OU=Certificate Authorities/CN=ESnet Root CA 1 Function: verify_callback [email protected] $ voms-proxy-init -debug -voms osg Detected Globus version: 2.2 Unspecified proxy version, settling on Globus version: 2 Number of bits in key :1024 Files being used: CA certificate file: none Trusted certificates directory : /etc/grid-security/certificates Proxy certificate file : /tmp/x509up_u20003 User certificate file: /home/user/.globus/usercred.p12 User key file: /home/user/.globus/usercred.p12 Output to /tmp/x509up_u20003 Enter GRID pass phrase for this identity: Your identity: /DC=org/DC=doegrids/OU=People/CN=First Lastname 12345 Using configuration file /home/marco/.glite/vomses Using configuration file /etc/vomses Creating temporary proxy to /tmp/tmp_x509up_u20003_17448 ..........................++++++ ...................++++++ Done Contacting voms.opensciencegrid.org:15027 [/DC=org/DC=doegrids/OU=Services/CN=host/voms.opensciencegrid.org] "osg" Failed Error: Error during SSL handshake:Either proxy or user certificate are expired. None of the contacted servers for osg were capable of returning a valid AC for the user.
To solve the problem split the bundle in the two PEM files as documented in the referenced document, so that the embedded CA chain is not used.
Renewing your OSG user certificate¶
[email protected] $ osg-user-cert-renew
Issues renewing your OSG user certificate¶
One requirement for renewing your OSG user certificate is that your identity must be vetted within the last 5 years. You can see whether this requirement is met for your user certificate when logged in to the OIM Web Interface.
When using the OIM Web Interface, make sure you are logged in and your name appears in the upper right corner. If it shows "Login" instead of your name, click it to log in.
When you click on your user certificate, under the Renew tab, you will see a line item for "This certificate was approved within the last 5 years". If there is a red X on this line with no other red X's, then you will have to request a new certificate instead of renewing it. Your two options for requesting a new certificate are:
- Request a certificate issued by the CILogon Basic CA (preferred)
If you need to keep your DN, or for whatever other reason you cannot use a CILogon Basic certificate, you will need to revoke and renew your user certificate:
With this method, there is a risk that you may end up without a valid certificate. After revocation, if your sponsor is unresponsive past the May 31, 2018 OSG CA service retirement, your previous certificate will no longer be valid and you won't be able to request a new certificate.
- Log in (your name should appear on the top right), and select your user certificate from the list in the OIM Web Interface.
- In a separate tab, open the +Request New page.
We recommend opening the
Request Newpage in a separate tab before revoking, in order to ensure that your CN gets correctly populated in the
Request Newpage. Also, to ensure a prompt response, be sure that you select a
Virtual Organizationthat you are associated with and a
Sponsorwho will be able to quickly verify your identity.
- Back in the first tab, with your user certificate selected, click the
Revoketab, and enter an explanation that you are revoking in order to re-request your certificate. Then click the red
- In the separate tab, fill out the rest of the User Certificate Request form and click
Revoking your user certificate¶
If the security of your certificate or private key has been compromised, you have a responsibility to revoke the certificate. In addition, if your name or email address changes, you must revoke your certificate and get a new one with the correct information.
Getting a Certificate from a Service Provider with cigetcert¶
You may also get a user certificate from a SAML 2.0 Service Provider such as your home institution or XSEDE. This kind of certificate is short-lived, typically valid only for a week. Therefore it is not suitable for using in your browser. However, it is useful for command-line access to site services such as compute or storage.
You will need to use the
cigetcert tool to get a certificate this way.
Use yum to install the
cigetcert package from the OSG repositories.
This is a new way of getting a certificate and does not work with all institutions.
To get a list of institutions supported by
[email protected] $ cigetcert --listinstitutions Clemson University Fermi National Accelerator Laboratory LIGO Scientific Collaboration LTER Network ...
To get a certificate, run
[email protected] $ cigetcert -i "<INSTITUTION>" Authorizing ...... authorized Fetching certificate ..... fetched Storing certificate in /tmp/x509up_u46142 Your certificate is valid until: Fri Apr 13 17:03:13 2018
Authentication is controlled by the institution; depending on the institution, you may need a valid Kerberos token, or will be prompted for a password.
If all goes well, you should see output similar to what's above.
The certificate is created in
/tmp/x509up_u<YOUR UID>, which is the same place proxies are created by
You may specify default arguments in the
CIGETCERTOPTS environment variable.
This can save you from having to type in the entire institution name every time you want a cert.
For example, to always use FNAL as the institution, put this in your
export CIGETCERTOPTS="-i 'Fermi National Accelerator Laboratory'"
Your VO may also provide specific instructions for how to best use this tool. Contact your VO support center for details.
cigetcert has advanced features, such as the ability to load configuration from a server, or store the cert on a MyProxy server.
See the manual page for cigetcert for more information.
Using cigetcert with XSEDE credentials¶
cigetcert also works with XSEDE as the service provider.
To use XSEDE credentials, you will first need an account at https://portal.xsede.org.
In addition, you need to set up two-factor authentication with XSEDE; see their MFA documentation for details.
Push notifications using the Duo Mobile app are required.
Once you have set all those up, run
cigetcert as follows:
[email protected] $ cigetcert -u <USERNAME> -i XSEDE
<USERNAME> is your username at portal.xsede.org.
You will get prompted to "Enter XSEDE Kerberos Password."
Enter the password for your account at portal.xsede.org.
You should then get a 2FA authentication request with Duo Mobile; once you accept this,
cigetcert will issue the certificate.