How to Combine the Okta API with SAML to Provision Atlassian Applications

How to Combine the Okta API with SAML to Provision Atlassian Applications

Okta's free connectors for Jira and Confluence Server can authenticate users. But how do you solve provisioning?

Table of Contents

In this article we’ll go through an example of how to cover the full scope of user lifecycle management with the Okta API 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 Okta 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:

  1. 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;
  2. scripts will be poorly documented, when at all;
  3. 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 Okta API will certainly give you loads of benefits.

Screenshot of the
The endpoint for the List Roles GET method in the Okta API

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:

Policy object attributes in the Okta API documentation
The Okta API has an extensive list of attributes for policy objects

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

Prerequisites

  • 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.

Check the supported versions for Jira and for Confluence.

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.

Keep reading: Advantages and disadvantages of Just-in-time provisioning

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 into Atlassian via the Okta 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.

Prerequisites

  • An admin account in Okta
  • An active instance of Jira/Confluence Server or Data Center in the supported versions
  • User and Group Sync installed, or resolution’s SAML SSO plugin installed (which includes User Sync for free).

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

Keep reading:

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.

Conclusion

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.

Subscribe to our newsletter:

Related articles: