Adding SAML integration to your existing user management infrastructure
This page is an overview of the steps required to integrate SAML single sign-on (SSO) with your installed Atlassian applications.
Using an external LDAP directory
1. Prerequisites
Your user directory - either LDAP or internal with LDAP authentication - needs to be set up in the Atlassian application. Please refer to the documents below for instructions:
- Jira Software Data Center: Connecting to an LDAP directory
- Jira Service Desk Data Center: Connecting to an LDAP directory
- Bitbucket Data Center: External user directories
- Confluence Data Center: Connecting to an LDAP Directory
You will also need a SAML identity provider (IdP). A list of the third-party providers tested with Atlassian SAML authentication can be found here.
Note: With Microsoft Active Directory, you can also use a local installation of Active Directory Federation Services as your identity provider (see the instructions below).
2. Integrate the LDAP directory with your identity provider
Configure your identity provider to import users from your LDAP directory. You should consult your identity provider's documentation for details:
The username/NameID attribute as read by the identity provider must match Directory > Configuration > User name attribute as set in your Atlassian application.
3. Configure SAML in your Atlassian application
Configure SAML in the application as described on this page. Your identity provider should supply you with a Single sign-on issuer, an Identity provider single sign-on URL and an X.509 Certificate. Copy the Assertion Consumer Service URL and Audience URL (Entity ID) displayed in your Atlassian application into your identity provider's configuration.
Your users can now log in by authenticating on your identity provider's site and selecting your application. Alternatively, they can use the address BASE-URL/plugins/servlet/external-login.
If you wish, you can now completely replace the built-in login form via the SAML Authentication > Login mode setting. If something ever goes wrong and you're locked out of your application, you can restore native authentication via REST.
Using Microsoft Active Directory with Federation Services
1. Prerequisites
Your user directory - either Microsoft AD or internal with authentication delegated to Microsoft Active Directory - needs to be set up in the Atlassian application. Please refer to the documents below for instructions:
2. Install and configure Active Directory Federation Services 3.0
Refer to the official documentation for instructions.
3. Configure SAML in your Atlassian application
Configure SAML in the application as described here, using the guidelines below. If you don't have a Relying Party Trust for your Atlassian application in ADFS, you will need to create it.
| Atlassian SAML parameter | Location in Microsoft ADFS Management |
|---|---|
| Single sign-on issuer | Copy from AD FS > Service > Edit Federation Service Properties... > General > Federation Service identifier. By default the issuer is https://<adfs hostname>/adfs/services/trust |
| Identity provider single sign-on URL | Copy from AD FS > Service > Endpoints > Token Issuance > The row with Type 'SAML 2.0/WS-Federation'. By default the url is https://<adfs hostname>/adfs/ls |
| X.509 Certificate | Export the Token-Signing certificate in Base-64 encoded X.509 format, then copy contents from the resulting .cer file. |
| Assertion Consumer Service URL | In AD FS > Trust Relationships > Relying Party Trusts > (your application) > Properties > Endpoints, add a new SAML Assertion Consumer with a Post binding. Paste into URL. |
| Audience URL (Entity ID) | In AD FS > Trust Relationships > Relying Party Trusts > (your application) > Properties > Identifiers, paste into a new identifier. |
Notes
- Make sure that AD FS > Trust Relationships > Relying Party Trusts > (your application) > Edit Claim Rules.. > Issuance Transform Rules use the same LDAP attribute for outgoing Name ID claim as Directory > Configuration > User name attribute in your Atlassian application. You'll need to create this rule if it doesn't exist.
Using Atlassian Crowd
With LDAP
With Active Directory Federation Services
If you use Atlassian Crowd server for user management, it adds another layer to one of the the above configurations. The only difference is that the external directory will communicate with Atlassian Crowd, while SAML authentication will be set up in the application.
Using your application's internal directory
Currently there is no automated way to synchronize users between internal directories and the SAML identity provider. You might choose to use an LDAP directory to be the shared source of data for your provider and the Atlassian application.
Alternatively you will need to make sure users are created in both your provider and your internal directory. This can be done either manually, or by using an API to automate the user creation.