OpenID Connect for Atlassian Data Center applications

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 SSO for Atlassian Data Center app that allows Atlassian Data Center applications to connect to an IdP and provide SSO for your users. 

This page describes the latest SSO features available in the following products:

• Jira Software Data Center 8.15 or later

• Bitbucket Data Center 7.12 or later

• Confluence Data Center 7.12 or later

• Bamboo Data Center 8.1 or later

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

Before setting up OpenID Connect single sign-on (SSO), 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 methods screen.

• Your Atlassian application will be looking for the username in the sub claim and openid scope by default. If your IdP uses a 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 OpenID Connect SSO in your Atlassian application 

1. Open the Authentication methods screen: 

   • In Jira applications, select   > System > Authentication methods.

   • In Bitbucket, select  > Accounts > Authentication methods.

   • For Bamboo, select  > Security > Authentication methods.

   • In Confluence, select  > General Configuration > User & Security > Authentication methods.

2. Select Add configuration.

3. Create a unique name for your configuration.

4. From the Authentication method menu, select OpenID Connect single sign-on.

5. Configure the following OpenID Connect settings:

   Setting	Details
   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 mapping	An attribute from your IdP that uniquely identifies a user and can be mapped to the username in Jira. For example, if you entered ${NameID}, we would use the values of this attribute from your IdP as usernames. Check your IdP docs for the list of attributes.
   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.

6. Copy and paste the following links to your identity provider:

   Setting	Details
   Redirect URL	This is the location where the client is sent to after successful account authentication.
   Initiate login URL	This is the URL used for OpenID Provider-initiated login.

7. The following settings are optional and can be selected as you see fit:

   Setting	Details
   Additional settings	If Fill the data automatically from my chosen identity provider is selected, the authorization, token, and user info endpoints will be filled automatically if your identity provider offers this option.
   JIT provisioning	If Create users on login to the application is selected, users will be created and updated automatically when they log in through SSO.
   OpenID Connect behaviour	If Remember user logins is selected, users will be logged in automatically as their login information will be remembered.
   Login page settings	If Show IdP on the login page is selected, users will see identity provider on login page.

8. Select  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 sure that the time on the server which runs your Atlassian application/s and the time of OpenID Provider are synchronized.

• 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.

• If you use OpenID Connect as primary authentication and 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