JIRA

# Setting up MIRACL Trust SSO SSO as an Identity Provider Within JIRA

These instructions are up-to-date at the time of writing, but you should refer back to the Atlassian documentation page on SAML IdP access to check for any changes. We cannot guarantee the accuracy of our SP-specific guidance.

  1. Once you have purchased the SAML / Single Sign On Add-on for JIRA go to the relevant section in your admin dashboard:

    Admin SSO

  2. Click on Add IdP. Give the IdP a name and specify ‘Import Metadata from xml’:

    add idp

  3. Input the xml metadata file which you can download from your running SSO IdP server at http://<yourssoip>/metadata Note that, for a production setup, if you manually download your SSO IdP metadata file, the validUntil date at the top of the file needs to be edited to an appropriate date (it defaults to 48hrs from the current date)

    add xml

  4. Leave the ‘NameID’ box unticked. This is unnecessary as MIRACL Trust is already configured to deliver the NameID attribute in the correct format:

    nameid

  5. Make sure the correct suffixes are added to JIRA url for the Metadata URL, Entity ID and SAML Endpoint URL:

    jira endpoints

  6. You are prompted to test your SSO login. However, you need to make the IdP configurations described in the next section before this is successful:

    Test Settings

# Configuring Your JIRA Service Provider Profile With MIRACL Trust SSO

  1. Edit /etc/miracl-sso/service_providers/jira.yaml:

    sp:
  jira:
    description: Jira issue tracking system
    name: My issue tracking system
    relay_state: ""
    login_url: http://jira.example.com/plugins/servlet/samlsso
    logout_url: http://jira.example.com/logout
    metadata: >-
      <!-- Insert downloaded SP metadata here -->
    sign_response: true
    sign_assertion: true
    encrypt_assertion: false
    user_id_transform:
    - search: ^([^@]+)@[^@]+$
      replace: $1
    authorize:
    - - email: ^[^@]+@example.com$

  2. For the metadata, return to the JIRA admin console, click on ‘Show info for IdP’ in the top right. Then click on the Metadata URL link and download your JIRA metadata into an xml file.

    Note that, if you are using JSON format for your config file, the downloaded metadata should be saved as an xml file and converted to a single line with the " characters escaped with \ to meet json structure requirements. This can be achieved by running the following command on the downloaded metadata.xml file:

    echo -e "\n"$(cat metadata.xml | tr -d '\n' | sed -E 's/"/\\"/g')"\n"

    The contents then are output in the terminal in a format that can be pasted into the metadata field of a JSON file.

  3. Under user_id_transform, you’ll find a function that adjusts for a limitation within JIRA in which email addresses are not allowed as usernames. The regex ‘search’ looks for the email address, and ‘replace’ with $1 means that only the first value - the email prefix - is going to be used. So, for example, john.smith@example.com becomes john.smith.

  4. In the authorize subsection, you can control what users are allowed to attempt login by following one or both of the below steps:

    • Call up an LDAP setup from an ldap.yaml file stored in /etc/miracl-sso/integrations.
    • Configure a regex list of email addresses/domains. The above config shows an example of how you would use email: ^[^@]+@example.com$ to only allow users from a certain email domain to login.

    Note that if this is not set correctly, you receive ‘unauthorized user’ messages.

    For more detailed info on using LDAP, API and/or regex to control authorized users, please see the authorization menu section.

  5. Save and close the file.

  6. In your /etc/miracl-sso/config.yaml file make sure you add jira.yaml to the list of ‘includes’:

    includes:
  - core.yaml

# service providers
  - service_providers/jira.yaml

  7. As always after config changes, restart the server.

  8. Now your service is configured, you can visit https://<yourssoip>/login/jira or https://<yourssoip>/services to log in to the service using IdP-initiated login, or visit the JIRA login page and SP-initiated login are triggered automatically.

  9. You are able to login using the in-browser PIN pad or with the MIRACL Trust app. When logging in to your SSO service for the first time you are asked to register an email address so as to confirm your identity and register you as a user.