Goal

    Connect and configure Okta and your Atlassian product to work with the SAML SSO app and also User Sync.

    Prerequisites

    To use the SAML SSO app with Okta, you need the following:

    • an Okta subscription
    • SAML SSO app which is bundled with User Sync since version 3.1.x
    • admin access to your Atlassian product

    Viduo Guide

    Here you will soon find a detailed video guide.

    Step-by-Step Setup Guide

    Install the SAML SSO app

    In your Jira or Confluence, open the in-product marketplace as described in the Atlassian documentation
    Search for "resolution saml" and click "Install" for SAML Single Sign On (SSO) by resolution Reichert Network Solutions GmbH


    After the installation is complete, do not click on Manage yet. The first part of the configuration is User Sync related,
    please read the next chapter. The configuration of the SAML SSO app will follow at a later step.

    Configure Okta for User Sync

    Configuration in the Okta Web Console

    Login to your Okta organisation as a user with administrator privileges
    Any type of administrator role is fine. If you limit this administrator role to manage only specific groups,
    only users in those groups are synced. API tokens have the same permissions as the user who creates them,
    and if the user permissions change, the API token permissions will also change.

    Hoover over Security and click on API.

    Click on Tokens.

    Click on Create Token.

    Add a name for your token and click on Create Token:

    Now the token value will be displayed. Copy it since it will be only displayed once.
    Of course you can create new token.

    Configuration in User Sync Configuration page

    Navigate to the administration console for Jira, Confluence or Bitbucket. 

    Confluence: search for USERS & SECURITY under which you'll find User Sync
    Jira: navigate to the User management tab in which you'll find User Sync
    Bitbucket: navigate to Administration/ Accounts you'll find User Sync listed here

    Click on Add Connector and choose OKTA Connector.

    Set a name, insert your Okta Domain without https:// and enter the token value from before for the API Token.

    To schedule a periodic synchronization of your Okta directory with User Sync, click on Show Advanced Settings at the very bottom of the page.
    Enable Scheduled Synchronization needs to be ticked, the default cron expression would then cause a sync every hour.


    Configure the SAML SSO App

    To start the wizard and to configure Okta as your new identity provider, navigate to the administration console for
    Jira or Confluence. 

    Confluence: search for USERS & SECURITY under which you'll find SAML Single Sign On
    Jira: navigate to the User management tab in which you'll find SAML Single Sign On
    Bitbucket: navigate to Administration/ Accounts you'll find SAML Single Sign On listed here

    Click on it and the wizard start page will show.


    Add new Identity Provider (IdP)

    Click on Add new IdP to start the wizard.

    Adding a new IdP can also be done outside the wizard in the app configuration section Identity Providers

    Select Okta as IdP Type.
    You may also change the name and add a description. The name needs to be unique.
    Click on Next.

    Retrieve SAML Metadata for Okta

    Copy the Single sign-on URL from the screen, you'll need it in your Okta configuration web console. Click on Next.

    Configure Okta

    Now it's time to head over to Okta. Make sure you're logged in as Admin. Choose Applications from the menu bar:

    Click on Add Application

    Click on Create New App

    Select Web as platform and choose SAML 2.0 as Sign on method in the Create a New Application Integration screen.
    Click Create.

    Provide a meaningful App name an click next

    Paste the Single Sign-On URL to both the Single sign on URL and the Audience URI (SP Entity ID) field and click Next

    Step 3 is just for providing some feedback to Okta. Choose your option and click Finish

    You'll be redirected to the Sign on tab from which you can copy the Identity Provider metadata by right clicking the
    link of the same name.

    You also need to define which users and/ or groups should be allowed to sign in via SAML SSO in Okta via the app you've created. 
    Switch to the Groups tab and add one ore more groups the users who should sign in with SSO are members of.

    The simplest example, like below, would be to allow the group Everyone access to the app.
    You could also assign individual people via the People tab to your app.


    Import SAML IdP Metadata

    It's time to resume configuration on the SAML SSO side. Take the Okta metadata link you've just copied and paste it
    into the Metadata URL field in the corresponding field of the Import SAML IdP Metadata wizard screen still open.

    User ID attribute and transformation

    It's recommended to leave this option checked.

    Click on Next.


    As User Update Method choose Update with UserSync-Connector.
    Select the User Sync connector name you've created before and enter email as the Lookup Attribute:

    Click Save & Next to continue. 

    Test configuration of SAML SSO app

    The last step when adding the Okta IdP is a test which can be executed by clicking on the corresponding Start test button.
    Copy the link displayed and paste it into a new incognito/ private browsing window, and execute a login with your Identity Provider.

    Please remember that ...

    • the user your are testing with needs to be assigned to the SSO app you've just created in Okta
    • the user also needs to exist in your Atlassian application already, since we are not using just in-time provisioning here
      (part of the Okta with Just-In-Time Provisioning tutorial)

    The status of the authentication process is permanently updated in the window.

    Enable login redirection

    The last step of adding Okta as your new IdP is to configure redirect options.  
    Selecting Enable SSO Redirect will ensure that users are getting redirected to be logged in via SAML, 
    instead via the login form as before the SSO setup.

    The Override Logged Out URL Method can be left at the default option.
    It will redirect users after log out to a default page where they can login again via username and password or SSO again.

    Save & Close to complete the setup and close the wizard. You are now ready to use Okta with User Sync and SAML SSO in your Atlassian application.

    If Enable SSO Redirect is enabled, you can login to your Atlassian application manually by browsing to the URL that fits your Atlassian application as listed below.
    Use this URL, if you need to login a local user unknown to the Okta or if there are any issues with Single Sign On.

    • Jira: https://<baseurl>/login.jsp?nosso
    • Confluence: https://<baseurl>/login.action?nosso
    • Bitbucket: https://<baseurl>/login?nosso
    • Bamboo 5: https://<baseurl>/userlogin!default.action?nosso
    • Bamboo 6: https://<baseurl>/userlogin!doDefault.action?nosso