Configure IdP

Import From Metadata

SAML Single Sign on IdP metadata

If your IdP provides a SAML Metadata file/URL, you can configure the plugin SSO settings by uploading the metadata file or configuring the metadata URL.

The Select IdP dropdown has a few pre-configured IdPs like ADFS and Azure AD. Each IdP has a unique method of making the metadata available – some can be configured to fetch the metadata URL and some only have the option of uploading a file. For example, if ADFS is your IdP, you will be asked for the hostname of your AD server. The metadata URL will then be generated based on the hostname and the plugin will retrieve IdP metadata from this URL. For IdPs like Okta, G Suite or One Login, the process for getting metadata is standard. For example, if you choose G-Suite, you will be asked to upload a metadata file.

For IdPs other than the ones mentioned in the drop-down, you may choose whether to upload a metadata file or to give a metadata URL depending on what your IdP supports. Custom options will be relevant here.

Metadata Rollover / Certificate Rollover

This option is useful if your IDP changes the certificates at intervals (Eg. Azure AD, ADFS, etc). The IDP sends signed responses and the plugin uses the configured certificate to validate that response. So whenever the certificates are changed on IDP you need to update the certificate on the plugin as well otherwise SSO will break as the plugin won't be able to validate the response. The metadata rollover feature is useful in this case. If it is enabled then plugin will fetch the IDP metadata periodically and will get the latest certificate so, you don't have to manually change the certificate on the plugin whenever it is changed on the IDP side.

Manual Configuration

If you have the following information from your IdP, you can configure the plugin by manually adding this information in the respective field. Here are the required fields:

IdP Name

You can enter a name for your IdP in this field. This field will be useful if you have configured multiple SAML IdPs.

SAML Single Sign on IdP name

For example, if you configure 2 IdPs namely IdP1 and IdP2, you manage them easily from the list as shown in the image below

SAML Single Sign on list of IdP

The IdP name that is entered in this field will be the name that will be displayed on the login button for this IdP. This login button will be used by end-users to initiate SSO for this IdP.

IdP Entity ID/Issuer

A unique URI/name used to identify the Identity Provider. This ID is provided by all SAML 2.0 compliant IdPs. Also, this is required for SAML SSO to work properly. The app uses IdP Entity ID to validate SAML Response.

Single Sign-on URL

An endpoint from IdP responsible for parsing the SAML Authentication request. The plugin sends SAML Request to this endpoint after initiating SSO. The SAML SSO URL might change according to the binding type selected in the app. Refer to the binding type section to know how to determine the binding type and SSO URL.

SSO & SLO Binding Type

The app sends XML Messages to IdP to perform Single Sign On and Single Logout. These SAML Messages are called SAML Request and Logout Request respectively. The Binding Type defines how the app will send these messages.

  • HTTP Redirect: The SAML Request message is sent as a GET request to IdP when HTTP redirect is selected. This means that the app will send SAML Request in URL parameters. This increases the length of the URL significantly. The URL length is even larger if a signed request is sent.
    Some IdPs have a limit on the length of the URL, hence we recommend not using this method if your IdP supports HTTP-POST.

  • HTTP Post: The SAML Request message is sent as a POST request to IdP when HTTP Post is selected. This allows you to send SAML Request to IdP without increasing the length of the URL and hence it is recommended to use this binding type.

NameID Format

NameID is considered as a unique identifier of the user performing SSO. Some IdPs require SP to request a specific NameID format for SSO to work properly. Keep the value of this field Unspecified if your IdP doesn’t require any specific NameID format.

IdP Signing Certificate

This is the public signing certificate provided by the IdP. IdP signs the SAML Response before sending it to the app. The app uses this public certificate to verify the signature in the SAML Response.

Single Logout URL (optional)

If you want the user to be logged out from the IdP as soon as they logout from the Atlassian application and vice versa, you can set this URL. A Single Logout URL is provided by most of the SAML 2.0 Compliant IdPs. The plugin sends SAML Logout Request to this endpoint after the user logs out from the application and this endpoint is responsible for parsing the SAML logout request.

The SAML SLO URL might change according to the binding type selected in the app. Refer to the binding type section know how to determine the binding type and SLO URL.

This is an optional field. Configure it only when you want to logout users from IdP after they log out from the application.

How to know which Binding Type your IdP supports?

You can find this information in IdP’s metadata file.

  1. Open IdP’s metadata
  2. Search for SingleSignOnService.
  3. Check the value of Binding attribute. You can see in the image below that this sample IdP supports both Binding Types
    SAML Single Sign on Admin
  4. The value of Location attribute is the Single Sign-On URL for that binding type.

Authentication Context Class (optional)

The authentication context indicates how a user authenticated at an Identity Provider. The Identity Provider includes the authentication context in an assertion at the request of a Service Provider or based on configuration at the Identity Provider.

Manual Configuration Fields image

SAML Single Sign on manual

Other Features/ Troubleshooting Options

Test Configuration

You can use this button to verify your configurations. Once you click on this button,

  1. A popup window will open.
  2. This will initiate an SSO flow and you’ll need to log in to the IdP. (If you’re already logged into the IdP, this step will be skipped.)
  3. Once you log in, you’ll see a test status window.

If,

  • Configurations are correct: You’ll see a Test Successful message with a list of attributes from the IdP as shown below.
    SAML Single Sign on test
  • Configurations are incorrect: you’ll see a Test Failed message with the cause of the error and resolution as shown below.
    SAML Single Sign on faild
  • Test Failed: You can refer miniOrange SAML App troubleshooting page to fix it.