Combining the Okta API with SAML for Authenticating and Provisioning Atlassian Applications
Updated: Sep 7
In this article we’ll go through an example of how to cover the full scope of user lifecycle management without creating any custom scripts.
We will analyze at a common scenario where the Identity Provider is an Identity as a Service (IdaaS) solution (in this case, Okta), and the service provider is Atlassian. We’ll see how Okta’s free SSO connector for Jira on premise can be supplemented with a connector that synchronizes users via the API, with the benefit of eliminating manual work on the Jira internal directory.
But first, a brief reminder on why bootstrapping these requirements should never be a serious alternative.
Using Identity APIs without custom scripting should be your mantra
Should I develop this new application in house or buy it from a vendor?
With the popularity of SaaS solutions, this vintage alternative hasn’t disappeared. It has mutated.
When developers utilize third-party APIs to add functionality into their applications, the question now is:
Should I write a script in-house or look for third party connectors?
Obviously, the answer depends from context.
But when it comes to Identity and Access Management (IdAM) and IdaaS, the rule of thumb is very clear:
Be lazy and don’t DIY!
Circulating the delicate blood of your user’s lifecycle with custom scripts is a hazardous practice, any way you look at it.
On the human side, these scripts are usually created as side jobs by technical employees who have other priorities. This means:
they may not have the technical knowledge to start solving the problem right away, spending a lot of effort into preliminary research and analysis. Potentially, they may not find a good solution to the problem;
scripts will be poorly documented, when at all;
there will not be a plan for maintenance.
On the functional side, identity scripts are particularly fragile and prone to break as soon as anything changes: from un updated endpoint to an application update or a new security requirement. And in the IAM landscape, where the user benefit consists in building bridges across applications for a unified and seamless user experience, anything that breaks will create a lot of pain and frustration.
This doesn’t mean that you can’t build your own scripts to match your exact requirements. But make sure that you’re minimizing the ratio of internally developed vs externally maintained code load.
If you keep that in mind, the API of your Identity Provider will certainly give you loads of benefits.
For example, through the Okta API you can perform rather basic operations like listing the roles assigned to a user or adding an application that uses SAML 2.0 for authentication; but you can also get into the fine-grained details with more interesting stuff. Just to give 3 quick examples:
Get session information on any given session ID
List all network zones in your organization (this one is currently in early access)
Solving authentication via SAML and provisioning via API
Identity Provider: Okta
Service Provider: on-premise deployments of Atlassian applications (Jira & Confluence)
Authentication language: SAML
Authentication connector: Okta Authenticator for Jira or Okta Authenticator for Confluence
Provisioning language: REST API
Provisioning connector: User & Group Sync (available for Jira, Confluence, Bitbucket and Bamboo)
Phase 1: Authenticating into Atlassian applications using Okta’s SAML
An admin account in Okta
An active instance of Jira or Confluence on premises
Step 1: Check that your Atlassian application is supported
Okta doesn’t update the connector for every Atlassian application minor version, so if you’re on the most recent version you should make a note that there may be unexpected situations.
Step 2: Download the connector
Download the okta-jira.jar or okta-confluence.jar from Okta’s download page (Okta Admin Console > Settings > Downloads
Step 3: Follow the instructions
Follow Okta’s configuration instructions
Step 4: Maintenance
Note that in order to update the Okta connector you will have to manually modify or replace the file in the Jira or Confluence server (for example, the okta-config-jira.xml file). This can happen when the certificate expires.
Is SAML Just-in-Time provisioning good enough?
Okta’s SAML connector for Atlassian on-premise applications can provision users as they log into Jira or Confluence for the first time (JiT, or Just-in-Time provisioning). While quite convenient in some aspects, JiT has important limitations:
users cannot be deprovisioned
user profiles won’t exist until the user logs on for the first time
IdPs may not be able to send all information in a SAML-response. Indeed, in the case of Okta each attribute must be mapped explicitly.
More generally, here’s a typical list of the pain points that Atlassian administrators will still encounter:
Excessive admin workload due to manual user administration in the internal directory of each Atlassian application
Eliminate orphan accounts and latent usage
Automate employee provisioning and deprovisioning
Exceed license limits due to large volume of inactive users
Ensure group memberships and role-based access are always up-to-date
Access overallocation that exposes sensitive information to employees or partners without the necessary
Phase 2: Provisioning users from Okta into Atlassian via API
JiT might not cut it. What many IT teams want is to synchronize Jira with Okta via the user API: when they do this, Okta’s user directory becomes the single source of truth for employee identities, and manual changes on the Atlassian side are no longer necessary.
Users and Groups Sync has been designed specifically to leverage the APIs of all leading Identity Providers, ensuring a seamless experience for both users and administrators, particularly when it comes to:
onboarding and offboarding users
role-based access control through always up-to-date group memberships.
Connecting your central Okta user directory with Jira can be done in less than 30 minutes with no coding skills. All you need is an admin account in Okta, a new API Token, and a good notion of the structure of your group memberships.
An admin account in Okta
An active instance of Jira/Confluence Server or Data Center in the supported versions
Note that it’s always a good idea to play with User and Group Sync in a test environment first to fully understand the implications of every operation.
Step 1: Configure the connection to Okta
Follow the instructions in the quickstart guide for Okta.
Step 2: Create an API Connector for Okta and Jira
Go to Security>API in the top menu
Hit the Create Token button and save the resulting value
Now move over to Users and Groups Sync: User Sync Configuration > Create a connector
Select Okta Connector
Name it, include your Okta domain and paste the token value
Step 3: Restrict your synchronization
Once connected, User Sync can do all the heavy lifting. You can just click “sync” to synchronize the current users in your IdP with
However, more often than not you will want to restrict which subset of users should be provisioned from Okta into Jira. To do that, follow these steps:
Edit the Okta connector
Show the advanced settings
Under Okta Group Management, add group filters so you sync only users who should be provisioned into Jira
Step 4: Schedule a periodic sync
In the configuration settings, check “Enable scheduled synchronization”, then decide how often you want the sync to automatically run. For example, you can set it to “0 0 * * 0” if you want the sync job to happen every Saturday at midnight.
Step 5: Enjoy the magic!
Just by doing this, you will be able to:
deprovision Jira users directly from Okta
automatically onboard new users as their identity is created or updated in Okta
Forget about any manual administration in the internal Jira directory
Many additional settings in User and Groups Sync will help you manage user identities in Jira to the tiniest detail. Keep reading in the links below if you’re interested in more advanced use cases.
Compare the simplicity of scheduling synchronizations with the time and effort required to understand the scope of possibilities with the Okta API methods, writing new scripts for every situation, testing all the flows, and maintaining them when anything in Jira or Okta changes.
It’s not a headache, it’s a myriad of them. User and Group Sync can give you all the much needed functionality required to provision users into Jira ahead of time, automate administration tasks, and supplement your SSO with accurate user attributes without any overhead. Plus, it can easily coexist with scripts that add additional behaviors and policies around, for example, MFA, device contexts, and so on.
The free Okta authenticators for Jira and Confluence can provide a god SSO foundation in terms of authentication and basic provisioning. However, if you’re looking to bring other Atlassian applications under the hood, like Bitbucket or Bamboo; or if you’d like to configure authentication and provisioning from a centrified connector, make sure to have a look at resolution’s SAML SSO offering.