How to enable auth_fallback functionality when using SSO in Bitbucket Data Center
Related content
- Creating issues and sub-tasks
- How to automatically transition parent linked issue when all child linked issues in the same status using Automation
- Create issues and sub-tasks
- Automation Rule Not Updating Cascade Field Correctly
- Creating issues using the CSV importer
- Cannot delete an issue type and unable to find issues associated to a deleted issue type
- Moving an issue
- Configuring sub-tasks
- Adding, editing, and deleting an issue type
Summary
When making SSO configuration changes or when setting up SSO for the first time, it's possible that a faulty or bad configuration could effectively lock out all users from the application if the SSO provider is set as the primary authentication method. This is because the users will be automatically sent to the non-functioning SSO provider login page, with no ability to access the local Bitbucket Data Center login form.
The purpose of this guide is to show you how to enable and use Authentication Fall Back for SSO in Bitbucket Datacenter, which will allow you to access a special fallback URL in order to log in locally and access the application and repair/disable the SSO configuration currently setup for the environment.
Environment
- Bitbucket Data Center instance using SSO for Atlassian Data Center
Solution (SSO for Atlassian Data Center 7.12 onwards)
Using the REST API
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:
- Download Postman for your browser (or use your own if you have an alternate REST client)
- Open Postman
- Select GET from the dropdown menu and select Basic Auth from the Authorization tab
(enter the admin credentials) - Enter the following URL, modified for your environment: <Base_URL>/rest/authconfig/1.0/sso
(For example: https://bitbucketdc/rest/authconfig/1.0/sso)
Add the
contextPath
only if you have a context path like /bitbucket
in your Bitbucket Base URL. For example https://mycompany.com:443/bitbucket
. You can set the context path for Bitbucket Data Center if you are running another Atlassian application, or Java web application, at the same hostname and context path as Bitbucket Data Center.
After clicking SEND you should receive a response with the following information:
{
"show-login-form": true,
"enable-authentication-fallback": false,
"show-login-form-for-jsm": false,
"last-updated": null
}
You can receive the same response by executing a cURL command similar to the one below:
curl -u <Admin> <Base_URL>/rest/authconfig/1.0/sso
We will need to set the enable-authentication-fallback field to true.
To do this, open a new tab in Postman or other REST client
- Select PATCH from the dropdown and enter the URL: <Base_URL>/rest/authconfig/1.0/sso
(For Example: https://bitbucketdc/rest/authconfig/1.0/sso) - Select
Basic Auth
from the Authorization tab and enter the credentials for the admin account - Go to the Body tab, select
Raw
from the radio button. SelectJSON
from the dropdown menu.
Specify the following request body to set enable-authentication-fallback to true:
{
"enable-authentication-fallback": true
}
The same can be also achieved using cURL command similar to the one below:
curl -u <Admin> -X PATCH -d '{"enable-authentication-fallback": true}' -H "Content-Type: application/json" <Base_URL>/rest/authconfig/1.0/sso
You should receive a response with the status code 200 or 304. Afterwards, you should be able to access <Base_URL>/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 behaviour.
After sending the PATCH request, perform a rolling restart of the Bitbucket nodes to flush the configuration cache. This will help prevent encountering a bug that may cause a Login form has been disabled on this instance warning message.
SAMLDC-154 - Getting issue details... STATUS
This bug affects the following Bitbucket Data Center versions:
- 7.21.17+
- 8.9.6+
- 8.10.6+
- 8.11.5+
- 8.12.3+
- 8.13.2+
- 8.14.1+
- 8.15.0+
- 8.16.0+
- 8.17.0+
- 8.18.0+
- 8.19.0+
In case the restart doesn't resolve the warning above, confirm that the login form is enabled on the instance, using the following GET endpoint:
curl -u <ADMIN>:<PASSWORD> https://<BASE_URL>/rest/authconfig/1.0/sso
If you see the following on the output, it means the login form is disabled:
"show-login-form":false
You can resolve this by setting the value to "true". Here is a PATCH cURL example:
curl -u <ADMIN>:<PASSWORD> -X PATCH -d '{"show-login-form": true}' -H "Content-Type: application/json" https://<BASE_URL>/rest/authconfig/1.0/sso
After setting the value to true, you can run again a GET on the endpoint:
curl -u <ADMIN>:<PASSWORD> https://<BASE_URL>/rest/authconfig/1.0/sso | jq .
{
"show-login-form": true,
"enable-authentication-fallback": false,
"show-login-form-for-jsm": false,
"last-updated": null
}
Obs: Replace the values for ADMIN, PASSWORD and BASE_URL, with the values of your instance.
Using a SQL Query
Important Note on DB Queries
This Database Query / Functionality is not officially supported!
- Atlassian is not responsible for translating queries for different databases.
- This query should only be used as an example. Any desired adjustments should be checked with your local Database Administrator, including queries related to different DBMS that are not present/listed in this KB article, like Oracle Database.
- Atlassian will not be providing support for changes, adjustments, or inquiries regarding the below queries, as this is not part of our Atlassian Support Offerings.
- Atlassian does not provide any support to sample database queries provided in our Knowledge Base documents. Extraction of data from Bitbucket should be performed using our REST API Documentation because we do not keep all data relationships in the DB. Many connections to data are handled in the code. The REST API can go through the code paths to get the data. A SQL would have to do that manually or, in some cases, it can’t be done at all.
In order to disable an SSO via a query on the database, first you need fetch all the currently available SSO configuration using the following query:
SELECT * FROM "AO_ED669C_IDP_CONFIG";
Choose the one you want to disable and use the following SQL Query to disable it:
UPDATE "AO_ED669C_IDP_CONFIG"
SET "ENABLED" = 0
WHERE "NAME" = '<SSO_NAME>';
The above query was tested on Postgres, use it as a basis to your DBMS of choice.
Solution (SSO for Atlassian 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:
- Download Postman for your browser (or use your own if you have an alternate REST client)
- Open Postman
- Select GET from the dropdown menu and select Basic Auth from the Authorization tab (enter the admin credentials)
- Enter the following URL, modified for your environment: https://localhost:PORT/contextPath/rest/authconfig/1.0/saml (For example: https://bitbucketdc/rest/authconfig/1.0/saml )
Add the
contextPath
only if you have a context path like /bitbucket
in your Bitbucket Base URL. For example https://mycompany.com:443/bitbucket
. You can set the context path for Bitbucket Data Center if you are running another Atlassian application, or Java web application, at the same hostname and context path as Bitbucket Data Center.
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
- Select
PUT
from the dropdown and enter the URL http://localhost:PORT/contextPath/rest/authconfig/1.0/saml (For example: https://bitbucketdc/rest/authconfig/1.0/saml ) - Select
Basic Auth
from the Authorization tab and enter the credentials for the admin account - Go to the Body tab, select
Raw
from the radio button. SelectJSON
from the dropdown menu.
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 Bitbucket 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:
- Download Postman for your browser (or use your own if you have an alternate REST client)
- Open Postman
- Select GET from the dropdown menu and select Basic Auth from the Authorization tab (enter the admin credentials)
- Enter the following URL, modified for your environment: https://localhost:PORT/contextPath/rest/authconfig/1.0/saml (For example: https://bitbucketdc/rest/authconfig/1.0/saml)
Add the
contextPath
only if you have a context path like /bitbucket
in your Bitbucket Base URL. For example https://mycompany.com:443/bitbucket
. You can set the context path for Bitbucket Data Center if you are running another Atlassian application, or Java web application, at the same hostname and context path as Bitbucket Data Center.
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
- Select
PUT
from the dropdown and enter the URL http://localhost:PORT/contextPath/rest/authconfig/1.0/saml (For example: https://bitbucketdc/rest/authconfig/1.0/saml ) - Select
Basic Auth
from the Authorization tab and enter the credentials for the admin account - Go to the Body tab, select
Raw
from the radio button. SelectJSON
from the dropdown menu.
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.
If in doubt of which version you have because you can't access the application, you can use the API requests below and proceed with the steps for SSO or SAML above based on the API response.
curl -u <dmin user> -X GET <base url>/rest/authconfig/1.0/sso
curl -u <admin user> -X GET <base url>/rest/authconfig/1.0/SAML
Related content
- Creating issues and sub-tasks
- How to automatically transition parent linked issue when all child linked issues in the same status using Automation
- Create issues and sub-tasks
- Automation Rule Not Updating Cascade Field Correctly
- Creating issues using the CSV importer
- Cannot delete an issue type and unable to find issues associated to a deleted issue type
- Moving an issue
- Configuring sub-tasks
- Adding, editing, and deleting an issue type