Tips about IdP Change with update of the account email domain

[#1]

Hello Community!,

A few days ago, I worked on a project that required changing the IdP connection, and I want to share with you a few tips about it.

In this case, the new IdP uses another domain and has new emails for the users. 

The main goal of this procedure was to keep the users’ permissions, data, and access, by changing the email of the accounts before the new IdP provisioning, to mitigate access problems after the change.

The procedure to do that is:

1. Verify the new domain and claim accounts;

2. Prepare the list with the accountId, old email and new email of the users;

3. Prepare the groups and users in the new IdP;

4. Delete the Provisioning from the old IdP;

5. Update the SSO Configuration to new IdP and connect with the new domains;

   1. Test the SSO login.

6. Adjust and Run a script to update users email;

7. Configure the Provisioning with the new IdP;

8. Configure the Policies;

9. In case of Share Domains in Multiple Organizations;

10. Open a ticket with Atlassian to replace account data.

11. In case of rollback

 

Verify a domain and claim the accounts

First of all, the origin and destiny of both domains need to be verified and claimed in the Organization before the procedure.

The first tip is about verifying if the domain was used in another Organization. After verifying the domain, and claiming the accounts, it is recommended to analyze if the domain's accounts will be available or not.

• Analyze if the total accounts match with claimed accounts, if don’t:

  • Export the accounts in the domain screen in Organization

  • Verify if anyone was claimed previously in another organization.

This step is so important to share the management of the accounts in multiple organizations. If the domain was shared, it is important to identify the organization, the organization admins and create a procedure to manage these accounts previously of the change.

 

Prepare the list with the accountId, full name, old email, and new email of the users

The tip in this phase is to create a from-to csv file with 4 columns: accountId, full name, old email, and new email to use in Script.

The simple way to get this information is to export a list of users of the organization.

In the exported file you get the account id, name, status, and email of the users

You could prepare a csv file with the accountId, full name, and email and get with the IdP manager the new emails of the users, preparing the csv file.

This csv file will be used for the script to replace the old email to a new one in user accounts.

CSV File Sample:

In this step, it is recommended to verify if these new emails already have an Atlassian account. You can analyze that by exporting the accounts in the domain screen.

The new emails that already have an account, can’t be changed by scripting and can’t be in the csv file. After the IdP changes, it will be necessary to open a ticket with atlassian support to transfer the issue, projects, spaces, and permissions data related to the old account to the new one in the atlassian products.

 

Prepare the groups and users in the new IdP

Create the Enterprise App in IdP with the same groups and configure the users. 

The group name must be the same to not affect any permissions and access for the users after the change.

If the group names were different, they must be changed in all configurations of the products, and it could have a big impact on the users.

 

Delete the Provisioning from the old IdP

If the provisioning was active, the accounts can’t be changed. Only IdP can change these accounts.

Because of that, we need to delete the provisioning before the emails update.

 

Update the SSO Configuration to the new IdP and connect with the new domains

To have a quick rollback if it is necessary we recommend updating the SSO connection instead of deleting the previous one and creating a new one.

In this step, it is important to copy the configuration of the old Idp: Entity, callback url, and certificate, for a possible rollback, before updating the SSO configuration.

 And proceed with the configuration.

Also, we must verify the SAML attributes configuration is ok and perform a login test, after done.

I suggest using a script, indicated below, to change one user’s email, and test the login and permissions with this user.

After SSO configuration, define the domains linked to the policy and SSO connection.

 

Adjust and Run a script to update users email

I have created a bash script to read a csv file with 4 columns:

• accountId

• Name

• Old email

• New email

CSV File Sample:

The endpoint used: https://developer.atlassian.com/cloud/admin/user-management/rest/api-group-users/#api-users-account-id-manage-email-put

 The Bash Script to update account email:

#!/bin/bash

# Parameter 
token='XYZ123' 
url="https://api.atlassian.com/users" 
csv_file='emails.csv' 
log_file="log_$(date +'%Y%m%d%H%M%S').txt"
 
# Internal Field Separator 
IFS=$'\r\n' 

# API Call 
tail -n +2 "$csv_file" | while IFS=, read -r USERID NAME EMAIL1 EMAIL2; do 
   echo -e " " 
   echo -e "\n $(date +'%Y%m%d%H%M%S') - Change user $USERID - $NAME - to $EMAIL2\n" 

   curl -s --request PUT --url "$url/$USERID/manage/email" \
        -H "Authorization: Bearer $token" \
        -H 'Accept: application/json' \
        -H 'Content-Type: application/json' \
        --data "{ 
            \"email\": \"$EMAIL2\"
        }"
 done | tee -a "$log_file"

To use this script, it is necessary to have an Organization API key, configure it in a token parameter, and replace the name of the csv file.

To get API Key: Manage an organization with the admin APIs

It is important to verify the end of the line terminators of the file to LF. It could be done in VSCode.

The script and the csv file need to be in the same folder.

It could be run in the terminal of linux, mac or wsl. 

The time spent running is about 1500 users per hour.

The script will present one row per user in a terminal and the log file.

 

Configure the Provisioning with the new IdP

It is important to check the User attributes in IdP to be the same as the user configured.

And after configuration, provisioned one user on demand, to check if the provisioning configuration is correct.

The risk in this step is the IdP sending another attribute as an email, like UPN, and duplicate accounts in the Atlassian Organization.

After syncing it is mandatory to check the groups.

 

Configure the Authentication Policies

In case of necessary use of the accounts with the old domain, it could be possible to put them in a local policy.

 

In case of the Share Domains in Multiple Organizations 

It is recommended to configure both organizations with Manual Claim.

If one of them was Automatic, the new accounts will be claimed there and it will be necessary to make a manual unclaim to claim these new accounts in the correct Organization.

 

Open a ticket with Atlassian Support to the duplicated accounts

Having duplicated accounts means the same person has one account with the old domain and a new one with the new domain, it will be necessary to open an Atlassian Support ticket to ask to transfer the issues, projects, spaces, and permissions data related from the old account to the new one in the Atlassian products.

 

In case of the Rollback

• Delete the Provisioning

• Configure and check the SSO with the old IdP using the information backup.

• Invert the email columns in a csv file.

• Run the script

• Configure and check the provisioning with the old IdP.

Atlassian Reference:

Verify a domain to manage accounts | Atlassian Support

Configure SAML single sign-on with an identity provider | Atlassian Support

Disconnect your identity provider | Atlassian Support

Understand user provisioning | Atlassian Support

Understand authentication policies | Atlassian Support

Edit authentication settings and members | Atlassian Support

Resolve group conflicts when syncing users | Atlassian Support

Atlassian User Management API