How to enable auth_fallback functionality when using SAML in Bitbucket Data Center

Still need help?

The Atlassian Community is here for you.

Ask the community

Purpose

The purpose of this KB is to show you how to enable and use Authentication Fall Back for SAML in Bitbucket Server. 

Solution (SSO for Atlassian Server and Data Center 7.12 onwards)

In order to make use of the auth_fallback functionality, the allow-redirect-override flag needs to be enabled via REST API. This can be done with other REST clients or via cURL, but the following is a user-friendly approach:

(warning) Add the contextPath only if you have a context path like /bitbucket in your Bitbucket Base URL. For example https://mycompany.com:443/bitbucketYou can set the context path for Bitbucket Server if you are running another Atlassian application, or Java web application, at the same hostname and context path as Bitbucket Server.

This should return something like the following after clicking SEND:

{
  "results": [
    {
      "id": 1,
      "name": "SAML_Okta",
      "enabled": true,
      "certificate": "-----BEGIN CERTIFICATE-----\XXXXXXXXXXXXXXXXXXXXX\XXXXXXXXXXXXXXX==\n-----END CERTIFICATE-----",
      "sso-type": "SAML",
      "include-customer-logins": false,
      "enable-remember-me": true,
      "jit-configuration": {
        "user-provisioning-enabled": false,
        "mapping-display-name": "",
        "mapping-email": "",
        "mapping-groups": "",
        "additional-openid-scopes": []
      },
      "button-text": "IdP login",
      "idp-type": "GENERIC",
      "sso-url": "https://dev-xxxxxokta.com/app/dev-xxxxxx_bitbucket712_2/xxxxxxx/sso/saml",
      "sso-issuer": "http://www.okta.com/xxxxxxx",
      "username-attribute": "<username> "
    }

We will need to update the enable-authentication-fallback field to true

    To do this, open a new tab in Postman or other REST client


Use the results from the command as reference to set enable-authentication-fallback set to true:

{
	"enable-authentication-fallback": true
}


You should get a 200 or 304 status when pressing the Send button and you will now be able to access http://localhost:PORT/contextPath/login?auth_fallback to bypass SAML. It's important to remember to set the flag back to false once the maintenance has been completed in order to restore the intended behavior.

Solution (SSO for Atlassian Server and Data Center 4.x or newer version until 7.11)

In order to make use of the auth_fallback functionality, the allow-redirect-override flag needs to be enabled via REST API. This can be done with other REST clients or via cURL, but the following is a user-friendly approach:

(warning) Add the contextPath only if you have a context path like /bitbucket in your Bitbucket Base URL. For example https://mycompany.com:443/bitbucketYou can set the context path for Bitbucket Server if you are running another Atlassian application, or Java web application, at the same hostname and context path as Bitbucket Server.


This should return something like the following after clicking SEND:

{
  "sso-type": "SAML",
  "sso-url": "https://dev-486166.oktapreview.com/app/jeancodev486166_bitbucketdc_1/exk9awjfupbFE8VQp0h7/sso/saml",
  "sso-issuer": "http://www.okta.com/exk9awjfupbFE8VQp0h7",
  "certificate": "MIIDpDCCAoygAwIBAgIGAVl1oNWbMA0GCSqGSIb3DQEBBQUAMIGSMQswCQYDVQQGEwJVUzETMBEG\nA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU\nMBIGA1UECwwLU1NPUHJvdmlkZXIxEzARBgNVBAMMCmRldi00ODYxNjYxHDAaBgkqhkiG9w0BCQEW\nDWluZm9Ab2t0YS5jb20wHhcNMTcwMTA2MjExMjExWhcNMjcwMTA2MjExMzExWjCBkjELMAkGA1UE\nBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xDTALBgNV\nBAoMBE9rdGExFDASBgNVBAsMC1NTT1Byb3ZpZGVyMRMwEQYDVQQDDApkZXYtNDg2MTY2MRwwGgYJ\nKoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA\nn5+MbxEb0rRA5kDBxVvzNRO3otJS7UMB3ldTEqivmieXvkXiSLjVYQJr7gbg+OYAX12V35HmrIs6\nRiT/d4trsePI09hRjQD2eMXsd11v1eKmoyAbsV026LZTHoVpXZQyeK383chJLEp2G6lRVdA/uFpP\nj5OCSiB5jVhEdRXymbfeESecMbh5YJu9H025sDBiqyzDHmZXunPdmJ0fyFpY9Q98bMfi7KUICHff\nlncSYQRDYax17wTO/2Nu4akWVESiBaedBlXAKuEOoB26ysxbQiUATOJTKodiGydyxLAlk2DV+Uzz\nDAeN8mQw7y4MArrSDqTWnTbtg3SJl6e0Ho/CGQIDAQABMA0GCSqGSIb3DQEBBQUAA4IBAQBNy/LR\nG85t3nuk4bnh2XRWtOXlSKtq6fVMAtJ4kd8vxB8M8DyFWDIaoXTd35COs1p2LX176hdBKjgau8Ux\nNUOJ3MIOw8qQAwFWguBHFWYhrcgDCVtCvz3wLIBRZehW/tX2ah+M8ATsn8oLPHaL2W11Z0JOiEcV\nIdAu6CyR1iDcVjCT7DV3h8aUWaLjfnfcJasEqiTEs2DH1d8E+GdW/lWaGiAdVlnxmxv5rvkwFxvZ\nDJyk2VPxZmFVdK16cUbPgnk5Bge7wnNaQZOUBmUZKAKmzeA+22lhKPpv8IGTIwEpcoUHggAdhvrT\nHfcvAs4OyFQgeaBA5//UjZVa/MfAFmqP",
  "user-attribute": null,
  "allow-redirect-override": false,
  "include-customer-logins": false,
  "redirect-on-login": false,
  "enable-remember-me": false
}


We will need to update the allow-redirect-override field to true

    To do this, open a new tab in Postman or other REST client


Use the results from the command as reference to set allow-redirect-override set to true:

{
  "allow-redirect-override": true
}


You should get a 200 or 304 status when pressing the Send button and you will now be able to access http://localhost:PORT/contextPath/login?auth_fallback to bypass SAML. It's important to remember to set the flag back to false once the maintenance has been completed in order to restore the intended behavior.

Solution (SSO for Atlassian Server and Data Center 3.x)

In order to make use of the auth_fallback functionality, the allow-saml-redirect-override flag needs to be enabled via REST API. This can be done with other REST clients or via cURL, but the following is a user-friendly approach:

(warning) Add the contextPath only if you have a context path like /bitbucket in your Bitbucket Base URL. For example https://mycompany.com:443/bitbucketYou can set the context path for Bitbucket Server if you are running another Atlassian application, or Java web application, at the same hostname and context path as Bitbucket Server.


This should return something like the following after clicking SEND:

{
  "sso-url": "https://dev-486166.oktapreview.com/app/jeancodev486166_bitbucketdc_1/exk9awjfupbFE8VQp0h7/sso/saml",
  "sso-issuer": "http://www.okta.com/exk9awjfupbFE8VQp0h7",
  "certificate": "MIIDpDCCAoygAwIBAgIGAVl1oNWbMA0GCSqGSIb3DQEBBQUAMIGSMQswCQYDVQQGEwJVUzETMBEG\nA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU\nMBIGA1UECwwLU1NPUHJvdmlkZXIxEzARBgNVBAMMCmRldi00ODYxNjYxHDAaBgkqhkiG9w0BCQEW\nDWluZm9Ab2t0YS5jb20wHhcNMTcwMTA2MjExMjExWhcNMjcwMTA2MjExMzExWjCBkjELMAkGA1UE\nBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xDTALBgNV\nBAoMBE9rdGExFDASBgNVBAsMC1NTT1Byb3ZpZGVyMRMwEQYDVQQDDApkZXYtNDg2MTY2MRwwGgYJ\nKoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA\nn5+MbxEb0rRA5kDBxVvzNRO3otJS7UMB3ldTEqivmieXvkXiSLjVYQJr7gbg+OYAX12V35HmrIs6\nRiT/d4trsePI09hRjQD2eMXsd11v1eKmoyAbsV026LZTHoVpXZQyeK383chJLEp2G6lRVdA/uFpP\nj5OCSiB5jVhEdRXymbfeESecMbh5YJu9H025sDBiqyzDHmZXunPdmJ0fyFpY9Q98bMfi7KUICHff\nlncSYQRDYax17wTO/2Nu4akWVESiBaedBlXAKuEOoB26ysxbQiUATOJTKodiGydyxLAlk2DV+Uzz\nDAeN8mQw7y4MArrSDqTWnTbtg3SJl6e0Ho/CGQIDAQABMA0GCSqGSIb3DQEBBQUAA4IBAQBNy/LR\nG85t3nuk4bnh2XRWtOXlSKtq6fVMAtJ4kd8vxB8M8DyFWDIaoXTd35COs1p2LX176hdBKjgau8Ux\nNUOJ3MIOw8qQAwFWguBHFWYhrcgDCVtCvz3wLIBRZehW/tX2ah+M8ATsn8oLPHaL2W11Z0JOiEcV\nIdAu6CyR1iDcVjCT7DV3h8aUWaLjfnfcJasEqiTEs2DH1d8E+GdW/lWaGiAdVlnxmxv5rvkwFxvZ\nDJyk2VPxZmFVdK16cUbPgnk5Bge7wnNaQZOUBmUZKAKmzeA+22lhKPpv8IGTIwEpcoUHggAdhvrT\nHfcvAs4OyFQgeaBA5//UjZVa/MfAFmqP",
  "user-attribute": null,
  "allow-saml-redirect-override": false,
  "include-customer-logins": false,
  "redirect-on-login": false,
  "enable-remember-me": false
}


We will need to update the allow-saml-redirect-override field to true

    To do this, open a new tab in Postman or other REST client


Use the results from the command as reference to set allow-saml-redirect-override set to true:

{
  "allow-saml-redirect-override": true
}

You should get a 200 or 304 status when pressing the Send button and you will now be able to access http://localhost:PORT/contextPath/login?auth_fallback to bypass SAML. It's important to remember to set the flag back to false once the maintenance has been completed in order to restore the intended behavior.


Last modified on Aug 23, 2021

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.