Manage group SSH certificates

You can control and manage Git access to your projects and groups with SSH certificates.

SSH certificates are cryptographically signed documents that authenticate a user’s identity and permissions. They are issued by a trusted Certificate Authority (CA) and contain information such as the user’s identity, validity period, and permissions.

The benefits of SSH certificate authentication are:

• Centralized access control: You can manage access through a central CA, instead of individual user-managed SSH keys.
• Enhanced security: SSH certificates are more secure than traditional SSH keys.
• Time-limited access: You can set certificates to expire after a specific period.
• Simplified credential management: Organizations can maintain a list of approved SSH certificate credentials for repository access.
• Independent from user-managed credentials: Access is controlled with group-managed certificates, and not users’ personal public SSH keys.

SSH certificates and SSH keys

The following table compares SSH certificates and SSH keys:

Authentication flow

The following diagram illustrates how SSH certificate authentication works in GitLab, from requesting a certificate to accessing a repository:

%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
    accTitle: SSH certificate authentication flow
    accDescr: Sequential diagram showing how a user obtains an SSH certificate from a Group Certificate Authority and uses it to access a Git repository through GitLab.

    participant User
    participant GroupCA as Group Certificate Authority
    participant GitLab
    participant GitRepo as Git Repository

    User->>GroupCA: Request SSH certificate
    GroupCA->>User: Issue signed SSH certificate
    User->>GitLab: Attempt to access repository via SSH
    GitLab->>GitLab: Verify certificate is valid and issued by Group CA
    GitLab->>GitRepo: Grant access
    GitRepo->>User: Allow repository operations

The authentication process verifies that users have valid SSH certificates before allowing repository access.

Add a CA certificate to a top-level group

Prerequisites:

• You must have the Owner role for the group.
• The group must be a top-level group, not a subgroup.

To add a CA certificate to a group:

1. Generate an SSH key pair to be used as a Certified Authority file:

   ssh-keygen -f CA

2. Add the public key to the top-level group using Group SSH certificates API to grant access to the projects of the group and its subgroups.

Issue CA certificates for users

Prerequisites:

• You must have the Owner role for the group.
• The user certificates can only be used to access the projects in the top-level group and its subgroups.
• A user’s username or primary email (user or user@example.com) must be specified to associate a GitLab user with the user certificate.
• The user must be an Enterprise User.

To issue user certificates, use the private key from the pair you created earlier:

ssh-keygen -s CA -I user@example.com -V +1d user-key.pub

The (user-key.pub) key is the public key from an SSH key pair that is used by a user for SSH authentication. The SSH key pair is either generated by a user or provisioned by the group owner infrastructure along with the SSH certificate.

The expiration date (+1d) identifies how long the SSH certificate can be used to access the group projects.

The user certificates can only be used to access the projects in the top-level group.

Enforce SSH certificates

You can enforce the usage of SSH certificates and restrict users from authenticating using SSH keys and access tokens.

When SSH certificates are enforced:

• Only individual user accounts are affected.
• It does not apply to service accounts, deploy keys, and other types of internal accounts.
• Only SSH certificates added to the group by Owners are used to authenticate repository access.

Prerequisites:

• You must have the Owner role for the group.

To enforce using SSH certificates:

1. On the left sidebar, select Search or go to and find your group.
2. Select Settings > General.
3. Expand the Permissions and group features section.
4. Select the Enforce SSH Certificates checkbox.
5. Select Save changes.