Skip to content

Authorising certificates and users

In addition to trusting the SSH CA, hosting entities must perform two further checks. This will ensure that access is authorised appropriately.

  • The certificate must be intended for itself (and not another hosting entity).
  • The principal named by the certificate must be authorised to use a local account.

To enable hosting entities to check that the certificate is intended for itself, the SSH CA includes the domain grant extension (ssh-domain-grant@core.aai.geant.org) in the certificate. This extension names the hosting entity's domain, as registered with EFP Allocations. The hosting entity can validate the certificate by matching this value against its own domain name.

To enable hosting entities to check that the principal named by the certificate is authorised to use a local account, the SSH CA provides the user’s MyAccessID CUID as the certificate principal’s value.

The same user’s CUID will be different for certificates issued by the Staging and Production SSH CAs. As discussed previously, this is because these CAs are connected to different instances of MyAccessID. The table below provides a summary.

SSH CA MyAccessID Identity Providers CUID format
Production Production eduGAIN and Guest IDP (Production) CUID@myaccessid.org
Staging Acceptance Guest IDP (Acceptance) CUID@acc.myaccessid.org

By default, sshd does not recognise the domain grant extension. To assist hosting entities, the EFP provides two tools that can be used with sshd to enforce the extension policy.

  • The first tool is ssh-cert-authorize. This is a specialised tool designed for use with the AuthorizedPrincipalsCommand configuration directive. This approach is recommended for hosting entities having less complex requirements.

  • Some hosting entities may have more complex needs. A second tool, ssh-cert-tool, is a general-purpose certificate parser for SSH certificates. It provides both human-readable and JSON output formats, making it simple to use with local scripts and tools invoked using AuthorizedPrincipalsCommand.

This document provides a quick overview of these tools. More detailed information can be found at

Both tools are obtained from the link above.

  1. Clone the repository.

       git clone git@gitlab.geant.org:core-aai-platform/ssh-cert-tool.git

  2. Build and install the binaries.

       cd ssh-cert-tool && sudo make build && sudo make install

Using ssh-cert-authorize

The recommended approach, which is appropriate for less complex scenarios, uses standard sshd functionality combined with the ssh-cert-authorize tool.

  1. Create a file naming your domain, as it is registered with EFP Allocations.
       echo "login.my-hpc.eu" | sudo tee /etc/ssh/cert-allowed-domain.conf > /dev/null
  2. Add an AuthorizedPrincipalsCommand configuration directive specifying the path to ssh-cert-authorize and its parameters.
       echo "AuthorizedPrincipalsCommand /usr/local/bin/ssh-cert-authorize %u %k" | sudo tee -a /etc/ssh/sshd_config > /dev/null
  3. Add an sshd configuration directive naming the user under whose account the command is run.
        echo "AuthorizedPrincipalsCommandUser nobody" | sudo tee -a /etc/ssh/sshd_config > /dev/null

Having verified that the certificate is authorised for the hosting entity's domain, it is then necessary to authorise the certificate principal for a local user account. This can be done using the AuthorizedPrincipalsFile directive. This specifies a path to a file enumerating the certificate principals authorised to use the account named by the file.

Recall that the SSH CA names certificate principles using their MyAccessID CUID attribute so the file(s) must contain one or more instances of a MyAccessID CUID.

  1. Create a directory to store the files (one for each user account).
        sudo mkdir /etc/ssh/authorised_principals
  2. Add an sshd configuration directive specifying the path to this directory.
        echo "AuthorizedPrincipalsFile /etc/ssh/authorised_principals %u" | sudo tee -a /etc/ssh/sshd_config > /dev/null
  3. Create a file that maps the certificate principal to a local user account.
        echo "1234abcd-5678-efgh-1234-abcdef123456@acc.myaccessid.org" | sudo tee /etc/ssh/authorised_principals/testuser > /dev/null
  4. Restart the sshd service.
        sudo systemctl restart sshd

Using ssh-cert-client

The ssh-cert-authorize tool will be sufficient in many cases. However, it may not be appropriate in other scenarios; for example, where user information is stored in a directory or relational database, or where complex authorisation logic must be enforced.

In these cases, ssh-cert-tool can be used to extract certificate parameters and process these with other tools; for example, within a local custom script that is invoked by AuthorizedPrincipalsCommand. The script below provides a simple example of its use.

#!/bin/bash  
# cert-verify.sh - Simple certificate verification script  
# Usage: cert-verify.sh <username> <certificate_blob>

USERNAME="$1"  
CERT_BLOB="$2"

# Parse certificate to JSON  
CERT_JSON=$(echo "$CERT_BLOB" | ssh-cert-tool parse --json)

# Extract domains using jq  
DOMAINS=$(echo "$CERT_JSON" | jq -r '.extensions.domains[]?' 2>/dev/null)

# Get host domain  
HOST_DOMAIN=$(cat /etc/ssh/cert-domain.conf)

# Check if any certificate domain matches host domain  
for domain in $DOMAINS; do  
    # Simple wildcard check: *.example.com matches web.example.com  
    if [[ "$HOST_DOMAIN" == $domain ]]; then  
        exit 0  
    fi  
done

exit 1