---
title: "How can I use SSO to authenticate git clients in Bitbucket?"
canonical: "https://www.techtime-initiative.com/space/EasySSO/3146015/How%20can%20I%20use%20SSO%20to%20authenticate%20git%20clients%20in%20Bitbucket%3F"
format: markdown
---
## Git clients and SAML in EasySSO

From [version 4.1.5.4](https://marketplace.atlassian.com/apps/1214247/easy-sso-bitbucket-kerberos-ntlm-saml/version-history) EasySSO supports SAML in Bitbucket.

Unfortunately, there are no git clients (command line, IDE-integrated or GUI ones e.g. SourceTree or TortoiseGit) that support SAML for authentication. As such, EasySSO for Bitbucket explicitly ignores the `/scm/*` URI in SAML authenticator, thus not even attempting SAML authentication for git operations.

If only SAML authentication is enabled in EasySSO, when using command-line or IDE-integrated or GUI tools your users will have to authenticate via **one** of the following:

- use [SSH key for authentication](https://confluence.atlassian.com/bitbucket/set-up-an-ssh-key-728138079.html)
- create [personal access tokens](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html)
- use their regular credentials.

However, all these clients support NTLM and Kerberos.

This opens a possibility of offering Kerberos/NTLM SSO to the git clients while doing SAML in the UI by specifying a user-agent allowlist in Kerberos/NTLM Authenticator's/Advanced Configuration/User Agent Filtering Configuration either via "User Agent Rules" (simply capture some git client UA strings and run them through the instant parser that is present on the same page) or via "User Agents Regexps to Ignore" by using a negative match regex. E.g. something like:

```
^((?!git\/).)*$
```

## Git clients and NTLM/Kerberos in EasySSO

If you are using NTLM/Kerberos authenticator in EasySSO with Bitbucket the following tips will help you set up your single sign-on for GIT clients.

### User-Agent Excluded Rules

By default EasySSO will block git agents from authenticating. To enable git agents to authenticate with NTLM/Kerberos and EasySSO 

### Step 1

Go to the EasySSO configuration screen, on the top right-hand side of the screen click on "Advanced"

![image-20240826-023004.png](media://a0cea8f2-6aeb-48da-8499-70bfd2b91079)

### Step 2

In the "Additional Parameters" click the ‘User Agent Filtering Configuration’ navigation tab at the top of the screen.

![Advanced Configuration with arrow 800px wide.png](media://3cd87606-5199-4fc6-91a7-c2ca78ea9f71)

### Step 3

In ‘User-Agent Excluded Rules’, add a # to the rule 

```
UNKNOWN,UNKNOWN,UNKNOWN,UNKNOWN,UNKNOWN,UNKNOWN
```

so that it becomes

```
# UNKNOWN,UNKNOWN,UNKNOWN,UNKNOWN,UNKNOWN,UNKNOWN
```

![User-Agent Excluded Rules with arrow - 800px wide.png](media://80645478-1770-419c-b11b-c9c10f23d824)

### Step 4

Save the config.

This will allow git agents to authenticate with Kerberos.


### Change git remote URL Notation

For NTLM or Kerberos authentication to work your git remote HTTP URLs need to use the following notation: `http://:@host/repopath`. The ":" in front of "@" tells git to use OS default credentials, i.e. use NTLM or Kerberos when challenged. For example, `https://yourcompany@bitbucket.mycompany.org/scm/bus/project.git` becomes `https://:@bitbucket.mycompany.org/scm/bus/project.git`.

You can see the current remote URL with the following command:

```
git remote -v
# Example output:
# origin https://bitbucket.mydomain.com/scm/proj/your-repo.git (fetch)
# origin https://bitbucket.mydomain.com/scm/proj/your-repo.git (push)
```

And you can change it with the command:

```
git remote set-url origin https://:@bitbucket.mydomain.com/scm/proj/your-repo.git
```

After this all git operations on this repository should not request the user to supply credentials – instead, their domain credentials should be used automatically.

Under the EasySSO Advanced Configuration, “Prefer HTTP(S)” can be set to offer HTTP/HTTPS clone URLs that are automatically rewritten for NTLM/Kerberos SSO in the Bitbucket UI.

![image-20240826-022046.png](media://17a835ae-720a-4dd2-8de2-4231b1556270)

### Work around bug in git clients since 2.11.x

Git 2.11.x has introduced a bug in NTLM authentication, this global setting enables the old behaviour.

```
git config --global http.emptyAuth true
```

### Set cookiefile on git via Windows command line 

Cookies need to be enabled to work around some issues with the push command. Use the following line to enable cookies:

```
git config --global http.cookiefile <absolute path to cookie file>
# Example:
git config --global http.cookiefile C:\Users\yourcompany\git-cookies.txt
```

### Kerberos headers

We do recommend configuring[ Kerberos](https://techtime-website.atlassian.net/wiki/spaces/EasySSO/pages/1474702) to be used – NTLM is great and will still be used when Kerberos is not possible (e.g. on VPN), but it is a 3-step protocol where the client goes back and forth with the server 3 times, while Kerberos is more efficient being a 1-step protocol.

> ⚠️ **Please note: **When using the Kerberos protocol the browser sends a relatively huge volume of information in HTTP request headers.
> ⚠️ 
> ⚠️ Due to other configurations that may be present in your organisation- the cumulative total size of information may cross the threshold configured for the Atlassian application (usually 8Kb). This usually manifests itself with blank pages being returned once Kerberos starts working. If you are getting this please change the maximum size of the header allowed.
> ⚠️ 
> ⚠️ For Jira and Confluence and older Stash/Bitbucket - look for Connector elements in server.xml, which is usually located in `/conf` directory of the installation (not the HOME directory). Increase or add the value for `maxHttpHeaderSize`. You can start by simply doubling the default of 8192 to 16384.
> ⚠️ 
> ⚠️ For Bitbucket 5.1+ add `max-http-header-size=16384` to `bitbucket.properties`

### An intermediary fix for: “Incorrect syntax”

Fix: Users need to enter their username and password into the pop-up offered by the git GUI client in the following syntax: **DOMAIN\**username + domain password

## Enabling verbose git logging

Troubleshooting authentication with git is much easier with additional logging turned on. 

Windows environments (PowerShell command)

```
$env:GIT_CURL_VERBOSE = "1"
git clone https://:@<YOUR GIT URL>
```

Linux environments

```
GIT_CURL_VERBOSE=1 git clone https://:@<YOUR GIT URL>
```

## Kerberos with Eclipse

Eclipse uses a built in java git client, to authenticate with Kerberos and Bitbucket using EasySSO

1. Edit the eclipse.ini file and add the following
  example

Example krb.ini file contents

```
[libdefaults]
  default_realm = DEV.TECHTIME.ORG
  dns_lookup_realm = false
[realms]
TECHTIME.ORG = {
   admin_server = DEV-DC-01.dev.techtime.org
   kdc = DEV-DC-01.dev.techtime.org
}
```

Example login.conf file

```
KrbLogin {
    com.sun.security.auth.module.Krb5LoginModule required
    useTicketCache=true
    ticketCache="C:\Users\administrator\krb5cc_Administrator"
    doNotPrompt=false;
};
```

2. Create a kerberos ticket using kinit. Note: On windows you can use the version of kinit shipped with eclipse which will be installed in `%USERPROFILE%`\.p2\pool\plugins\<JRE_VERSION>\jre\bin   
Example path to kinit `%USERPROFILE%`\.p2\pool\plugins\org.eclipse.justj.openjdk.hotspot.jre.full.win32.x86_64_21.0.9.v20251105-0741\jre\bin\kinit.exe
3. Ensure the ticket cache generated by kinit matches the ticketCache path inside the login.conf file.
4. Open Eclipse and when prompted for the username and password, input the username of the user logged in with kinit, the password should be left empty. authentication should work correctly.

## If you want to stop git clients from using NTLM/Kerberos SSO

The following steps show you how to configure your EasySSO installation if you Don't want your git clients attempting single sign-on, but want all other attempts to authorise via SSO. (For example developers using browsers to access the repository for reviews, or commenting on code.)

### Step 1

Go to the EasySSO configuration screen, on the top right-hand side of the screen click on "Advanced"

![image-20240826-023004.png](media://a0cea8f2-6aeb-48da-8499-70bfd2b91079)

### Step 2

In the "Additional Parameters" section add `excludes=/scm/*` on it's own line

![image-20240826-023051.png](media://cfa530f7-9691-4968-a7f2-60c793b5d746)

### Step 3

Save the config.

This will stop all git clients from attempting single sign-on, but will allow SSO via browsers.