OpenID Connect for Atlassian Data Center applications

Still need help?

The Atlassian Community is here for you.

Ask the community

OpenID Connect is an identity layer on top of the OAuth 2.0 protocol. It enables client applications to rely on authentication that is performed by an OpenID Connect Provider to verify the identity of a user. Clients can also obtain basic profile information about a user in an interoperable and REST-like manner from OpenID Connect Providers.

Atlassian provides the OpenID Connect app which allows Atlassian DC products (Jira Software Data Center, Jira Service Desk Data Center, Bitbucket Data Center, and Confluence Data Center) to connect to an identity provider (IdP) to provide authentication of your users. For the complete list of products and their versions compatible with OpenID Connect, see Atlassian Marketplace

OpenID Connect is built in to Jira 8.7, Bitbucket 7.0, Confluence 7.3 and newer. These versions no longer need to install it from Atlassian Marketplace.

OpenID Connect only handles authentication. Application access and any required authorizations, such as ensuring that users belong to the appropriate groups/roles and have the necessary permissions, should be configured in the user directory and/or the application.

Setting up OpenID Connect single sign-on

Once you've installed SSO 2.0, you need to decide if you want your users to log in to your Atlassian application or an identity provider of your choice. Then you'll need to configure IdP to provide single sign-on (SSO) for your users.

Setting up your Identity Provider

If you want your application to use SSO authorization, you'll need to add it to your IdP. The exact process varies depending on the IdP, but you'll usually need to:

  • Define an 'application' in your IdP.

  • Provide some data about the application, including data you can access on your application's Authentication screen.

  • Your Atlassian application will be looking for the username in the sub claim and openid scope be default. If your IdP uses different claim within scope for passing usernames, make sure to specify them in the Username claim and Custom scopes settings in your Atlassian application. For more information, see Using an OpenID Connect to integrate with Okta.

  • Give the appropriate users permissions to use the application.

At the end of the setup process your IdP will provide you with a set of data that you'll need to configure your Atlassian application.

Configuring SSO 2.0 in your Atlassian application 

  1. Go to the SSO screen: 

    • In Jira applications, select  > System > SSO 2.0.

    • In Bitbucket, select  > Accounts > SSO 2.0.

    • In Confluence, select > General Configuration> SSO 2.0.

  2. From the Authentication method drop down list, select OpenID Connect.

  3. Configure the following settings:

    Setting

    Notes

    Issuer URL

    The complete URL of the OpenID Provider.

    Client ID

    The client identifier, as registered with the OpenID Provider.

    Client secret

    Client secret is used in conjunction with the Client ID to authenticate the client application against the OpenID Provider.

    Username claim

    The claim in where your Atlassian application expects the username to be. The default claim is sub. Change it if your OpenID Provider stores the username in a different claim.

    Additional scopes

    Scopes are used by an application during authentication to authorize access to a user's details. Each scope returns a set of user attributes, which are called claims.
    The default scope is openid. Add more scopes if needed to obtain the username claim.

    Login mode

    Define how your users can use single sign-on:

    • Use OpenID Connect as secondary authentication – the default way to log in will be the standard application login form. You can log in using OpenID Connect if you go to your OpenID Provider and select your application, or by using the this URL to log in: BASE-URL/plugins/servlet/external-login.

    We recommended this method so you can test that everything is configured correctly, and that users can log in using SSO.

    • Use OpenID Connect as primary authentication – in this mode, all browser-based users will be redirected from the application's login screen to the IdP to log in. It's still possible to authenticate by:

      • Basic Auth

      • Form-based auth via dedicated REST endpoint

      • Existing Remember Me tokens

      • Git HTTP(S) (for Bitbucket Server)

      • Git SSH (for Bitbucket Server)

      You should only enable this mode once you've verified that OpenID Connect authentication is working as expected.

  4. Click Save configuration

    Once you've configured both your application and your OpenID Provider, you're ready to start using SSO.


Best practices...
  • OpenID Connect authentication requests are only valid for a limited time. Make the time on the server which runs your Atlassian application/s and the time of OpenID Provider are synchronised.

  • If users and groups in your Atlassian application are configured using User Directories, you'll usually want to use the same LDAP directory to be the source of users for both your OpenID Provider and Atlassian application. Users need to exist in the user directory before they can log in using SSO.

Troubleshooting
  • If you make a mistake configuring the OpenID Connect authentication, or are unable to log in using your OpenID Provider, you can restore login form authentication by using issuing a DELETE request (using a username and password for an administrator configured in your user directory):

    curl -u admin_user:admin_password -X DELETE http://BASE_URL/rest/authconfig/1.0/sso
  • If an authentication error occurs, the user will only see basic details about what went wrong. For security reasons, the details about the underlying problem are not shown. You'll need to check the application logs to see the cause of the problem. 

  • In some cases you might also experience errors shown by your OpenID Provider. For those you will need to use the support and tools provided by your OpenID Provider, rather than the Atlassian support.

  • When using OpenID Connect as primary authentication and you have CAPTCHA enabled in the application, users that use HTTP basic authentication (for example in REST resource calls, or when using Git HTTPS in Bitbucket) may get locked out if they enter an incorrect password too many times. In these cases, an administrator will need to reset the user's CAPTCHA in the user list screen.

  • To display stack trace information in the error pages, use the following flag:

    -Datlassian.darkfeature.atlassian.authentication.include.stacktrace.in.error.messages=true
Last modified on Jan 27, 2020

Was this helpful?

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