Software Links
Getting Started
- A Globus Primer
- Globus Is Modular!
- Quickstart
- Installing GT
- Platform Notes
- GT Developer's Guide
- GT User's Guide
- Migrating Guides
Reference
Manuals
Common Runtime
Security
- GSI C
- GSI Java
- Java WS A&A
- C WS A&A (coming soon)
- CAS
- Delegation Service
- MyProxy
- GSI-OpenSSH
- SimpleCA
Data Mgt
WS MDS
Execution Mgt
Table of Contents
This section describes the configuration steps required to:
- determine whether or not to trust certificates issued by a particular Certificate Authority (CA),
- provide appropriate default values for use by the grid-cert-request command, which is used to generate certificates,
- request service certificates, used by services to authenticate themselves to users, and
- specify identity mapping information.
In general, Globus tools will look for a configuration file in a user-specific location first, and in a system-wide location if no user-specific file was found. The configuration commands described here may be run by administrators to create system-wide defaults and by individuals to override those defaults.
The Globus tools will trust certificates issued by a CA if (and only if) it can find information about the CA in the trusted certificates directory.
The trusted certificates directory is located as described below and exists either on a per-machine or on a per-installation basis.
X509_CERT_DIR is the environment variable used to specify the path to the
trusted certificates directory. This directory contains information about which CAs are
trusted (including the CA certificates
themselves) and, in some cases, configuration information used by grid-cert-request to formulate
certificate requests. The location of the trusted certificates directory is looked for in
the following order:
- value of the
X509_CERT_DIRenvironment variable $HOME/.globus/certificates/etc/grid-security/certificatesexists$GLOBUS_LOCATION/share/certificates
The following two files must exist in the directory for each trusted CA:
Table 1. CA files
| The trusted CA Certificate. |
| A configuration file defining the distinguished names of certificates signed by the CA. |
Non-WS Globus components will honor a certificate only if:
- its CA certificate exists (with the appropriate name) in the TRUSTED_CA directory, and
- the certificate's distinguished name matches the pattern described in the signing policy file.
The cert_hash that appears in the file names above is the hash of the CA certificate, which can be found by running the command:
$GLOBUS_LOCATION/bin/openssl x509 -hash -noout < ca_certificateSome CAs provide tools to install their CA certificates and signing policy files into the trusted certificates directory. You can, however, create a signing policy file by hand; the signing policy file has the following format:
access_id_CA X509 'CA Distinguished Name' pos_rights globus CA:sign cond_subjects globus '"Distinguished Name Pattern"'
In the above, the CA Distinguished Name is the subject name of the CA certificate, and the Distinguished Name Pattern is a string used to match the distinguished names of certificates granted by the CA.
Some very simple wildcard matching is done: if the Distinguished Name Pattern ends with a '*', then any distinguished name that matches the part of the CA subject name before the '*' is considered a match.
Note: the cond_subjects line may contain a space-separated list of distinguished name patterns.
A repository of CA certificates that are widely used in academic and research settings can be found here.
The grid-cert-request command, which is used to create certificates, uses the following configuration files:
Table 2. Certificate request configuration files
globus-user-ssl.conf | Defines the distinguished name to use for a user's certificate request. The format is described here. |
globus-host-ssl.conf | Defines the distinguished name for a host (or service) certificate request. The format is described here. |
grid-security.conf | A base configuration file that contains the name and email address for the CA. |
directions | An optional file that may contain directions on using the CA. |
Many CAs provide tools to install configuration files with the following names in the Trusted Certificates directory:
globus-user-ssl.conf.cert_hashglobus-host-ssl.conf.cert_hashgrid_security.conf.cert_hashdirections.cert_hash
The command:
grid-cert-request -ca cert_hashwill create a certificate request based on the specified CA's configuration files.
The command:
grid-cert-request -ca
will list the available CAs and let the user choose which one to create a request for.
The default CA is the CA that will be used for certificate requests if grid-cert-request is invoked without the -ca flag.
You can specify a default CA by invoking the grid-default-ca command (follow the link for examples of using the command).
The directions file may contain specific directions on how to use
the CA. There are three types of printed messages:
- REQUEST HEADER, printed to a certificate request file,
- USER INSTRUCTIONS, printed on the screen when one requests a user certificate,
- NONUSER INSTRUCTIONS, printed on the screen when one requests a certificate for a service.
Each message is delimited from others with lines ----- BEGIN message type TEXT
----- and ----- END message type TEXT -----. For example,
the directions file would contain the following lines:
----- BEGIN REQUEST HEADER TEXT -----
This is a Certificate Request file
It should be mailed to ${GSI_CA_EMAIL_ADDR}
----- END REQUEST HEADER TEXT -----If this file does not exist, the default messages are printed.
Different CAs use different mechanisms for issuing end-user certificates; some use mechanisms that are entirely web-based, while others require you to generate a certificate request and send it to the CA. If you need to create a certificate request for a service certificate, you can do so by running:
grid-cert-request -host hostname -service service_name
where hostname is the fully-qualified name of the host on which the service will be running, and service_name is the name of the service. This will create the following three files:
Table 3. Certificate request files
| An empty file. When you receive your actual service certificate from your CA, you should place it in this file. |
| The certificate request, which you should send to your CA. |
| The private key associated with your certificate request, encrypted with the pass phrase that you entered when prompted by grid-cert-request. |
The grid-cert-request command recognizes several other useful options; you can list these with:
grid-cert-request -help
Several Globus services map certificates to local unix usernames to be used with unix services. The default implementation uses a gridmap file to map the distinguished name of the identity of the client's certificate to a local login name. Administrators can modify the contents of the gridmap file to control what certificate identities are allowed to access Globus services, as well as configure, via an environment variable, what gridmap file a particular service uses.
In addition to the identity-based mapping done via the gridmap file, administrators can configure Globus services to to use arbitrary mapping functions. These may use other criteria, such as SAML assertions, to map a certificate to a local account, or may map certificates to temporary accounts. Administrators can install different mapping implementations and configure services to use them by creating appropriate configuration files and setting environment variables.
Gridmap files contain a database of entries mapping distinguished names to local user names. These may be manipulated by using the following tools.
To add an entry to the gridmap file, run:
$GLOBUS_LOCATION/sbin/grid-mapfile-add-entry \
-dn "Distinguished Name" \
-ln local_nameTo delete an entry from the gridmap file, run:
$GLOBUS_LOCATION/sbin/grid-mapfile-delete-entry \
-dn "Distinguished Name" \
-ln local_nameTo check the consistency of the gridmap file, run
$GLOBUS_LOCATION/sbin/grid-mapfile-check-consistency
To configure a service to use a particular gridmap file, set the
GRIDMAP variable in the service's environment to the path of the gridmap
file. In this way, you can grant different access rights to different certificate
identities on a per-service basis by setting the GRIDMAP variable in
different service environments.
You can use tools described above to operate on different gridmap files by either
setting the GRIDMAP environment variable prior to invoking them, or by
using the -mapfile command-line option.
For reference, the GSI C code looks for the gridmap in these locations:
A gridmap line of the form:
"Distinguished Name"local_name
maps the distinguished name Distinguished Name to the local
name local_name.
A gridmap line of the form:
"Distinguished Name"local_name1,local_name2
maps Distinguished Name to both
local_name1 and local_name2; any
number of local user names may occur in the comma-separated local name list.
For more detailed information about the gridmap file see the file description and grammars on dev.globus.org.
To use an alternative credential mapping, you create a gsi-authz.conf file containing information about how the mapping functions are
called from the authorization library.
To configure a per-service authorization configuration file, set the
GSI_AUTHZ_CONF variable to the path to the configuration file in the
environment of the service.
For reference, the GSI C code looks for the authorization configuration file in these locations (in the given order):
Table 5. Authorization Configuration File Locations
| Location |
|---|
|
|
|
|
|
|
|
|
The authorization file defines a set of callouts, one per line. Each callout is defined by an abstract type, library, and symbol separated by whitespace. Comments begin with the # character and continue to the end of line.
Table 6. Authorization Configuration File Locations
| Field | Meaning |
|---|---|
|
|
Type of the callout: globus_mapping is used for credential mapping callouts |
|
|
Path to the shared object containing the callout implementation. The library name may be a literal filename, or a partial filename to which the compilation flavor of the service is appended to the filename before its extension. |
|
|
The exported symbol containing the entry point to the callout implementation. |
Here is a sample gsi-authz.conf file that configures a
globus_mapping callout to use the
globus_gridmap_callout function in the /usr/local/globus/lib/libglobus_gridmap_callout_gcc32dbg shared object:
# abstract-type library symbol globus_mapping /opt/globus/lib/libglobus_gridmap_callout_gcc32dbg globus_gridmap_callout
End Entity Certificate (User, Host and Service) Certificates and the GSI Authorization Callout Configuration File:
- May not be executable
- May not be writable by group and other
- Must be either regular files or soft links
Private Keys and Proxy Credentials:
- Must be owned by the current (effective) user
- May not be executable
- May not be readable by group and other
- May not be writable by group and other
- Must be either regular files or soft links
CA Certificates, CA Signing Policy Files, the Grid Map File and the GAA Configuration File:
- Must be either regular files or soft links
GSI Authorization callout configuration files
- Must exist
- Should be world readable
- Should not be writable by group and other
- Should be either a regular file or a soft link
GSI GAA configuration files
- Must exist
- Should be world readable
- Should not be writable by group and other
- Should be either a regular file or a soft link