Adding SAML integration to your existing user management infrastructure

On this page

 

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:

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

The username/NameID attribute as read by the identity provider must match Directory > Configuration > User name attribute as set in your Atlassian application.

Your users should now be able to log in to the identity provider's site using the credentials from the LDAP directory.

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.

Note: The Atlassian Crowd single sign-on feature isn't compatible with SAML SSO. The feature is off by default. If your applications use this feature, disable it before setting up SAML configuration.

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.

 

Last modified on Aug 25, 2017

Was this helpful?

Yes
No
Provide feedback about this article

Not finding the help you need?

Ask the community

Powered by Confluence and Scroll Viewport.