Jama Connect® SCIM configuration with Okta and Microsoft Azure AD

Author: Katie Huckett

Updated: August 2024 

Audience: Self-hosted & Cloud-hosted customers

Environmental details: Authentication configuration

Overview

System for Cross-Identify Management (SCIM) is a standard for automating the exchange of user identity information between identity domains or IT systems (source).

SCIM will allow your organization to automatically provision users and groups into your Jama Connect environment directly from your identity provider (IDP).  

Currently, Jama Connect supports SCIM provisioning with the following IdPs: 

• Okta Custom Application 
• Microsoft Azure AD

Considerations and Pre-Requisites for SCIM

SCIM Field Mappings and Impact on Your Data 

To configure automated SCIM user and Group provisioning on your Jama Connect environment, you’ll need to consider the following impact areas and decide if making these adjustments is acceptable for your organization’s workflow. 

• Authentication method for users 
• Username and Email formatting 
• Third-party integrations (if applicable)
• Connect Organization-level Group naming and membership

PLEASE NOTE: Depending on your Jama Connect® user configuration, data sanitization efforts must be completed before SCIM enablement.

Existing Jama Connect Customers - Authentication method for users

Basic-Only/SAML or Auth0-Only/Multi-Mode

Please review your Jama Connect® users to see if the Username field matches the Jama Connect email field. 

Note: For Jama Connect's SAML/Auth0 integration to work correctly, the field set as the IdP's subject (e.g., Okta Application userName or Azure AD userPrincipalName) must equal the user's email in Jama Connect. 

Azure AD does not require users to have an email address; however, Connect will require newly provisioned users to have emails. Please ensure all users you wish to provision have an email in the primary field. This email MUST match the userPrincipalName in the AAD user profile.

Data Sanitization to Update Username Field 

• Cloud customers – Contact Support for assistance with data sanitization 
• Self-hosted customers became available in the fall/winter of 2023. 

Existing Customers – Integrations with third-party providers 

• Evaluate current authentication methods with your 3rd party applications 
  • Are you currently using Username to authenticate? 
  • If updating your Username field to an email format will compromise your integration, you’ll need to update your integration simultaneously. 

Existing Customers – Connect Organization-Level Group Considerations

• Review your current Connect organization-level Groups and Group Members
• Make a note of the Groups that you wish to sync with your IDP (you may choose not to sync all org-level groups)
• For the groups that you will sync with your IDP, review the Member list:
  • If you have Basic Auth users in a Connect Group that you will sync with your IDP,
  • AND their status is inactive;
  • THEN, on the next IdP group sync, the inactive Basic Auth group members will be removed from the Connect Group
  • Note: If you need to re-activate an inactive Basic Auth user(s) and want to investigate if they were previously a member of a Connect Group(s), you may search the Group Activity log for entries related to that user(s).
• Review the organization-level Group names for any duplicates
  • If you have duplicate Group names, change them so that they are unique to avoid data synchronization issues

How Users and Groups Work with SCIM

The following actions change: 

• All users and groups in the IDP that are assigned to the Jama Connect application are added to Jama Connect. New users are assigned a license based on availability in the following order: 

• • Creator > Creator (float) 
  • Once users are provisioned, an Administrator may update or batch-update user licenses if needed.

• If they are Basic Auth, all users in Jama Connect® but not in your IDP will be left alone. For proper synchronization, any IDP-authenticated user must be added to your IDP.
• Organization administrators no longer create or edit users in Jama Connect because they are automatically provisioned from your IDP unless you enable multi-mode authentication. With multi-mode enabled, the Basic Auth user activities will be performed in Connect.
• If your organization enables Group provisioning in your IDP, then any org-level group activities for those groups will be managed in the IDP. 
• Any Basic Auth users in an inactive state who are members of a Connect org-level group linked to your IDP will be removed from the Connect group during the next IdP Group sync that is triggered.

The following actions stay the same: 

• Organization administrators retain the ability to assign a license type to users. 
• Users can continue to upload avatar icons. 
• Organization administrators and project administrators continue to manage project groups within individual projects. 
• An organization or project administrator continues to manage user and Group permissions in Jama Connect. 

Configure SCIM Provisioning

• Cloud customers – Contact Support to schedule enablement. 
• Self-hosted customers - Please contact Support for help preparing for a successful implementation. 

Jama Connect Configuration 

1. (Okta only) Enable Multi-Mode authentication (if already enabled with the following settings, skip to step 2) 
   • Basic: Ensure ‘Allow users to change their username’ is disabled (unchecked) 
   • SAML: Ensure ‘Disable the auto-generation of new SAML users’ is enabled (checked)

• Create a Service Account user with Basic authentication and Org Admin credentials (referred to as the 'SCIM Admin' from now on)

1. Ensure the pre-requisite data sanitization has been completed
2. (Optional) Configure the following logging packages to TRACE in the Root Admin for monitoring (See: Configure Logs) 
   • com.jamasoftware.contour.rest.versions.scimv2 
   • com.jamasoftware.contour.security.saml.SamlUserDetailsAuthenticationProvider
   • (Microsoft Azure AD only) com.jamasoftware.contour.rest.services.ApiKeyTokenService  

Jama Connect Configuration - for Microsoft Azure AD only

To authenticate Microsoft Azure AD's provisioning feature for non-gallery apps, a Bearer Token is required (aka Secret Token, Long-lived Bearer Token). 

1. Connect must be configured for OAuth2 authentication
2. Ensure you have contacted Support to enable your access to the Bearer Token endpoints
3. POST /rest/token/apiKeygen with Basic Auth credentials if using multi-mode or API credentials if using SAML-only (Org Admin user/password) (please note if using API credentials: it is recommended to use dedicated API credentials for generating the API token for SCIM, and not used for any other REST API calls)
   1. Creates the key pair files within your Connect tenant directory
   2. All API tokens generated from these keys will become invalid if those files are deleted or if new key pair files are generated (DELETE /rest/token/deleteKey)
   3. Key pair files are overwritten on subsequent requests to the above endpoint
   4. No other methods/endpoints interact with the key pair files
4. GET /rest/token with Basic Auth credentials if using multi-mode or API credentials if using SAML-only (Org Admin user/password)
   1. Returns a token for the user provided in the request
   2. Generated token format: apikey_<valid_token>
   3. The Token will expire in six (6) months and is only valid for the tenant from which it was generated.
   4. Note: this process will only work the first time a user calls this endpoint - subsequent calls will return a 409 error unless the revokeExistingToken parameter is used (see step 5)
5. GET rest/Token?revokeExistingToken=true with Basic Auth credentials if using multi-mode or API credentials if using SAML-only (Org Admin user/password)
   1. Returns a new token for the user provided in the request and overwrites the previous Token for the same user
6. DELETE /rest/token/current with Basic Auth credentials if using multi-mode or API credentials if using SAML-only (Org Admin user/password)
   1. Invalidates the Token of the user provided in the request
7. DELETE /rest/token/current?forUser=<userId> with Basic Auth credentials if using multi-mode or API credentials if using SAML-only (Org Admin user/password)
   1. Invalidates the Token of the user whose userId is specified in the forUser parameter

Expiration of the long-term Bearer Token

Microsoft Azure AD will quarantine the application when the Bearer Token expires since calls to Connect will begin failing. It is recommended that an internal alerting system be set up to warn you before this expiration so that you can generate a new Bearer Token in Connect and configure it in Azure AD provisioning before the token expiration and application quarantine. 

Okta Configuration

1. Enable SAML/Auth0 in Okta 
2. Pre-requisite / Data preparation: 
   • Okta App username = Connect username = Connect email 
     

Provisioning Users in Okta

1. With your Jama Connect Okta Application selected:

• Go to General > Edit
• Provisioning > select SCIM
• Save your changes

2. Select the Provisioning tab:

• Under Integration > SCIM Connection > select Edit
• Please fill out the required form (once this is saved, it will allow access to the To App and Okta settings)
  • SCIM connector base URL: Connect application URL + SCIM path (e.g. https://example.jama.net/rest/scimv2)
  • Unique identifier field for users: userName
  • Supported provisioning actions: Push New Users; Push Profile Updates
  • Authentication mode: Basic Auth (note: other authentication methods cannot be used at this time)
  • Username: SCIM Admin username that you created in previous steps
  • Password: SCIM Admin password that you created in previous steps
  • Select the Test Connector Configuration button to ensure everything is configured correctly
    • If you receive an error, it could be either the SCIM feature flag was not enabled, and you need to contact Support for assistance, or you may need to re-check your SCIM Admin username and password
  • Save your changes

3. Select the Sign On tab:

• Go to Settings > Edit
• Under Credential Details, set the following:
  • Application username format: Email
  • Update application username on Create and update
• Save your changes

4. Return to the Provisioning tab:

• Select To App > Edit and set the following:
  • Create Users: enabled
  • Update User Attributes: enabled
  • Deactivate Users: enabled
• Save your changes

5. Now, you can assign new Okta users to your Jama Connect Okta Application!

• Please confirm that the email address format in the Application User username and email fields matches that in the email address field during the assignment process. (You may need to copy/paste the primary email value into the username field.)

6. Existing users assigned to the application will see a warning icon indicating they must be provisioned with the external application (Jama Connect).

• To provision the existing users, select the Provision User button, which is only available after step 5 is performed.

Provisioning Groups in Okta

1. Follow the steps above in the 'Provisioning Users in Okta' section through step 2 with the following modification:

• Supported provisioning actions: Push New Users, Push Profile Updates, Push Groups
• If necessary, please complete the remaining steps in the 'Provisioning Users in Okta' section.

2. If you have not created the Okta Groups that you want to provision into Connect as new groups (or to link to existing Connect org-level groups), then create them now

3. With your Jama Connect Okta Application selected:

• You can go to the Push Groups tab.
• Select the Push Groups button > select the By Name section
• Search for your Okta Group and select the appropriate Group from the suggestion dropdown
• Under the Match result & push action > select either Create Group or Link Group
  • Create Group will provision the Okta group into Connect
    • If no name match is found in Connect, a new org-level Group will be created
    • If a group with an exact name match is found in Connect, the Okta group will be linked with the corresponding Connect group, and the users within the Connect group will remain within the Group after linking occurs
    • Users within the Okta group will not be provisioned into Connect (this must be done via Assignment)
  • Link Group will also provision the Okta group into Connect
    • The Link Group text field dropdown in Okta should remain empty since we do not support importing groups
    • If a group with an exact name match is found in Connect, the Okta group will be linked with the corresponding Connect Group, and the users within the Connect group will remain within the Group after linking occurs
    • Users within the Okta group will not be provisioned into Connect (this must be done via Assignment)
• Save your changes

Microsoft Azure AD Configuration

1. In the Azure portal, go to Azure Active Directory > Enterprise Applications

• Select the application that exists for Connect (the same one used to configure SSO)
• Select Provisioning
• Select Get Started, then set Provisioning Mode to Automatic
  • Tenant URL: Connect application URL + SCIM path (e.g. https://example.jama.net/rest/scimv2)
  • Secret Token (aka Bearer Token): Paste in the Bearer Token generated from Connect as described in the above steps
• Click Test Connection
  • If successful, a brief status box will display in the window's top-right for a few seconds.
• Click Save, but do not start provisioning.
  • You must leave Provisioning turned off since the default mappings in Azure AD include unsupported attributes. 
  • The following section will correct the settings for mappings.

Configure Actions/Mappings for Users

1. If you had dismissed the screen after the section above, go back to the Enterprise Application > select Provisioning> select Edit Provisioning

2. Expand the Mappings section > select Provision Azure Active Directory Users

3. Change the default Target Object Actions to turn off Delete (see screenshot below)

• Connect supports 'soft delete' (inactive users) but does not handle 'hard delete.'

4. Change the default Attribute Mappings to remove unsupported attributes

• Delete every attribute except the following (under the column customappsso Attribute):
  
  • userName
  • active
  • emails[type eq "work"].value
  • name.givenName
  • name.familyName

5. Save your changes

Configure Actions/Mappings for Groups

This feature is optional. If you do not want to synchronize Groups and Group Membership from Azure AD to Connect, edit the group mapping and set Enabled to No.

• Even if you turn off mappings for Groups, you can still assign Azure AD users to the Connect application by assigning the Azure AD Group, which contains the users. In this scenario, users will be provided with Connect but will not create a Group in Connect.

1. Go to Provision Azure Active Directory Groups

• The default Target Object Actions are supported. You do not need to adjust any settings in this section.
• The default Attribute Mappings are supported. You do not need to adjust any settings in this section.

Enable Automatic Provisioning in Azure AD

When you are ready, enable Provisioning by selecting Start Provisioning.

• Azure AD provisioning runs a batch job in the background. It can take several minutes before a new provision cycle starts (e.g., 40 minutes).

Viewing Logs from Azure AD Provisioning

You can view provisioning logs by selecting View provisioning logs.

Please feel free to leave feedback in the comments below.