Knowledge Base

 View Only

Jama Connect SCIM configuration with Okta and Microsoft Azure AD

By Katie Huckett posted 05-31-2022 07:50

  

Information Updated July 2022 for Jama Connect release 8.76

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

Table of Contents

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 areas of impact and decide if making these adjustments are 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 existing Jama Connect user configuration, data sanitization efforts will need to be completed prior to SCIM enablement.


Existing Jama Connect Customers - Authentication method for users

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

Review your Jama Connect users to determine 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. Ensure that all users you wish to provision have an email in at least the primary email field. This email MUST match the userPrincipalName in the AAD user profile.

Data State Action Needed
Username and Email match for all users No further action is required
If any Username and Email fields do NOT match Update the Username field for any user with a non-email address format to match their email field

Data Sanitization to Update Username Field 

  • Cloud customersContact Support for assistance with data sanitization 
  • Self-hosted customers - Run SQL queries in order to identify users that may cause a problem during the update process. Contact Support for assistance with SQL queries, if needed. 
Authentication Type Users that need to be updated to support SCIM User pairs that are likely to cause a problem during the update process
Basic-only Active 
Email Address != UserName 
If at least one of the two users needs to be updated, First User Email Address == Second User Username 

If both users need to be updated, First User Email Address == Second User Email Address 
SAML or Auth0-only Active 
AuthenticationType: IdP-login 
Email Address != UserName 

Same as above
Multi-mode Active 
AuthenticationType: IdP-login 
Email Address != UserName 

Same as above

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 

NOTE: It is recommended that you use a Basic authenticated Service Account to authenticate your third-party applications.

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
NOTE: Project-level groups are managed solely in Connect and are not impacted by SCIM

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
  • All users that are in Jama Connect, but not in your IdP, will be left alone if they are Basic Auth. Any user that is IdP authenticated will need to be added to your IdP for proper synchronization. 
  • Organization administrators no longer create or edit users in Jama Connect because they are automatically provisioned from your IdP, unless you have multi-mode authentication enabled. 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 that are in an inactive state and a member of a Connect org-level group that is 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: 

    Action in IdP Result in Jama Connect
    User(s) added to the 'Jama' application in IdP User added.
    Attributes in Jama Connect are overwritten by values from the IdP if a user already exists.
    User attributes are modified User attributes are modified.
    User is deactivated/deleted User is deactivated.
    User is activated User is activated.
    If the user doesn't exist, a new user is created. The new user is assigned a Creator or Creator (float) license dependent on availability. An Org admin may reassign the license type once the user has been created.
    Group(s) added to the 'Jama' application in your IdP Org-level Group created
    If an Org-level group already exists in Connect with the same name, the group will be linked to the IdP
    Group attributes modified Org-level Group attributes are modified
    User added to Group User is added to the Org-level Group
    User is removed from Group User is removed from the Org-level Group
    Group deleted Org-level Group is deleted

    Configure SCIM Provisioning

    • Cloud customers Contact Support to schedule enablement. 
    • Self-hosted customers - Contact Support to turn on the SCIM feature flag and assist with enablement to ensure 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' hereinafter)
    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/Auth0.SAML/Auth0UserDetailsAuthenticationProvider
      • (Microsoft Azure AD only) com.jamasoftware.contour.rest.services.ApiKeyTokenService  

    Jama Connect Configuration - for Microsoft Azure AD only

    For authenticating 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 (Org Admin user/password)
      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 (Org Admin user/password)
      1. Returns a token for the Basic Auth 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/roken?revokeExistingToken=true with Basic Auth credentials (Org Admin user/password)
      1. Returns a new token for the Basic Auth user provided in the request and overwrites the previous token for the same user
    6. DELETE /rest/token/current with Basic Auth credentials (Org Admin user/password)
      1. Invalidates the token of the Basic Auth user provided in the request
    7. DELETE /rest/token/current?forUser=<userId> with Basic Auth credentials (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 put the application in 'quarantine' when the Bearer Token expires since the calls to Connect will begin failing. It is recommended to setup an internal alerting system to warn you prior to this expiration so that you can generate a new Bearer Token in Connect and configure it in Azure AD provisioning prior to 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 GeneralEdit
    • Provisioning > select SCIM
    • Save your changes

    2. Select the Provisioning tab:
    • Under IntegrationSCIM Connection > select Edit
    • Fill out the required form (once this is saved it will allow access to the To App and To 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
      • 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 SettingsEdit
    • 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 AppEdit and set the following:
      • Create Users: enabled
      • Update User Attributes: enabled
      • Deactivate Users: enabled
    • Save your changes

    5. You are now ready to assign new Okta users to your Jama Connect Okta Application!
    • Make sure to confirm that both the Application User username and email fields match the email address format during the assignment process. (You may need to copy/paste the primary email value into the username field.)
    6. For existing users already assigned to the application, you will see a warning icon indicating that they are not yet provisioned with the external application (Jama Connect).
    • To provision, the existing users, select the Provision User button that 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
    • Complete the remaining steps in the 'Provisioning Users in Okta' section if needed


    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:

    • 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 note 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 on 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 for a few seconds in the top-right of the window
    • Click Save but do not start provisioning
      • For now you must leave provisioning turned off, since the default mappings in Azure AD include unsupported attributes. 
      • The next 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 disable 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 choose to disable 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 provisioned to Connect, but will not create the 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.

    0 comments
    79 views