TECHNICAL NOTE
TECHNICAL NOTE
Fasoo User Synchronization from OKTA
This document provides a step-by-step guide on synchronizing user identities from Okta to the Fasoo EDRM Server using the SCIM (System for Cross-domain Identity Management) protocol. By leveraging SCIM-based provisioning, organizations can automate user management, ensuring that user accounts and attributes remain consistent between Okta and Fasoo.
The process outlined in this guide will cover:
Generating an API token in Okta
Importing the oktasync package
Running necessary SQL scripts
Configuring SCIM sync files on the Fasoo Server
Establishing a connection between Okta and the Fasoo EDRM Server
Mapping user attributes
Managing ongoing synchronization
Troubleshooting common issues
By following these instructions, administrators can streamline user provisioning and maintain a secure, up-to-date Fasoo environment.
1.1 Generate an OKTA API token
Use the Tokens tab on the API page of your OKTA tenant to manage and create Okta API tokens and configure restrictions on where they can connect from. API tokens are secrets and should be treated like passwords. API tokens are generated with the permissions of the user that created the token. If a user's permissions change, then so do the tokens.
Note: Tokens are valid only if the user who created them is active. Tokens issued by deactivated users are rejected. To avoid service interruptions, generate API tokens using a service account that won't be deactivated and that has super admin permissions that won't change.
Please refer to the below guide from OKTA for detailed steps on generating this API token
The following steps assume a fully deployed and operational Fasoo FED5 system with all required services running, certificates installed, licenses activated, firewall ports configured, and the above OKTA API token generated.
1.2 Import the oktasync package
Steps:
- Unzip the oktasync-x.x.x.zip package provided to you by your Fasoo technical representative to a dedicated subfolder inside of your Fasoo folder structure.
Example:
2. Execute the SQL files inside of the oktasync-x.x.x subfolder \INIT_QUERY\FED5 .
- Open your SQL database management tool and connect to the appropriate database.
- Select the FED target database where the scripts should be executed.
- Open each SQL file from the \INIT_QUERY\FED5 directory.
- Review the script, ensure the correct database is selected, and execute the query.
- Repeat for all required SQL files.
- Verify execution results and check for any errors.
1.3 Configuring SCIM sync on the Fasoo Server
Steps:
- Update the adSynch.bat file to include your servers JDK path (located in the \oktasync-x.x.x folder).
Note: Not all paths will be the same for all deployments, make sure your path leads to your JDK (java.exe)
If you run the Sync process on the FED server, the certificates are already installed.
The example above would reference the below folder
2. Update the okta.conf file located in the \oktasync-x.x.x\conf subfolder to include all required information.
Note: This file will contain the unique OKTA API token, server host, sync port and DB info.
Below is a sample of each line with a breakdown of each item (relevant field item notes in red).
[SYNCINFO]
SYNC.HOST=fds.fasoo.com -Server host (service URL)
SYNC.PORT=443 -Okta communication port for sync
SYNC.AUTHTOKEN=/////83///8=/RqSDv5RahnsobN -Okta API Authorization Token (generated in section 1.1)
SYNC.TOKENENC=N -Initially set to N, for the Okta API token to encrypt once the SCIM Sync process is run
SYNC.AUTHTYPE=SSWS -Authorization Type (i.e. SSWS, Bearer, Base64)
** ADDITIONAL NOTE for SYNCINFO à SYNC.AUTHTOKEN (above)**
// AUTHTOKEN = raw token --> TOKENENC=N
// AUTHTOKEN = encoded token --> TOKENENC=Y
// After the first execution, AUTHTOKEN will be encoded and TOKENENC will be Y
[FASOODBINFO]
FASOO.HOST=192.168.15.123 - DB Host (IP address or hostname can be used)
FASOO.PORT=3306 -DB Port
FASOO.DBMS=MYSQL -Option: MSSQL or MYSQL depending on SQL Server used
FASOO.USEWINDOWACCOUNT=N -Whether or not to use the Windows Account as DB credentials
FASOO.USERNAME=root -DB User Credential
FASOO.PASSWORD=/////83///8=m0GVOLspNlyF -DB Password
FASOO.DBNAME=FED -DB Name
FASOO.PWDENC=Y -The value Y = already encrypted (N = Password not encrypted)
FASOO.INSTANCENAME= -Leave blank unless instructed
FASOO.FEDVERSION=5 -FED version running (default is 5)
FASOO.SKIPEXCEPTION=Y -Leave set to Y (default) unless otherwise instructed
[GROUPINFO]
//1=CN=Users,DC=fasoo,DC=com|subgroup -If only certain Okta groups are to be synced, list them below by #
1=IAM_Fasoo_DEV -Optional group name listed (otherwise not required for full sync)
2=IAM_Fasoo_PRD -Optional group name listed (otherwise not required for full sync)
3=Domain Admins -Optional group name listed (otherwise not required for full sync)
4=Security Team -Optional group name listed (otherwise not required for full sync)
[POSITIONINFO]
[ROLEINFO]
[ATTRIBUTES]
ATTR.USERNAME=displayName -Do not change unless instructed (not commonly used)
ATTR.USERID=sAMAccountName -Do not change unless instructed (not commonly used)
ATTR.USEREMAIL=mail -Do not change unless instructed (not commonly used)
[DEFAULTS]
DEF.DSDCODE=0100000000006116 -FED DSD Code
DEF.ROLECODE=R001 -Do not change unless instructed (not commonly used)
DEF.POSITIONCODE=P001 -Do not change unless instructed (not commonly used)
DEF.SERVICEURL=https://fds.fasoo.com/fed5 -FED Service URL
[ACTIVITY]
RUN.PRE=YES à -To run the pre-installation script (beforeexec.data)
RUN.POST=NO -To run the post-installation script (afterexec.data)
3. Update \conf\FED5\user.template or \conf\FED5\user.template_mysql to include the SHA256 value of the fixed
server password (the default in both files is the SHA256 equivalent of ‘1111’).
Sample:
insert into fidp_user_temp_all (updated_ts, use_yn, pwd_updated_ts, linked_yn, linked_password_yn, dsdcode, user_id, user_name, user_pwd, user_email, dept_code, position_code, role_code) values (unix_timestamp(now()) * 1000, 'Y', unix_timestamp(now()) * 1000, 'Y', 'Y','#DSDCODE#','#USERID#, #USERNAME#','0ffe1abd1a08215353c233d6e009613e95eec4253832a761af28ff37ac5a150c',
'#USEREMAIL#','#DEPTCODE#','#POSITIONCODE#','#ROLECODE#')
In red above is the SHA265 equivalent of the fixed password of ‘1111’
Example
4. Optional Update \conf\FED\afterexec.data
Note: initial_password_yn = Y (user prompted for password reset upon initial login).
initial_password_yn = N (no prompting, allows for SSO, very common).
Default value in afterexec.data is initial_password_yn = ‘Y’
Example below shows value set to N
1.4 Establishing the connection, running the sync process
The below steps establish a connection to the Okta tenant and commence the user import
- Run adSynch.bat
- Open a command prompt as administrator
- Navigate to the oktasync-x.x.x folder
- run the adSynch.bat command
2. Review the Okta sync log \Fasoo\Oktasync-x.x.x\log\ADSynch.txt
3. Review the FED server log \Fasoo\FED5\logs\fasoo-fed5.20xx-xx-xx.0.log
If the migration fails (or errors appear in logs) please send the below files to your Fasoo support team:
/data/okta.conf.data (process.conf should be LEAVEDATA=Y)
/log/ADSync.txt (process.conf should be LOGMODE=DEBUG)
/conf/okta.conf & process.conf
/Fasoo/FED5/logs fasoo-fed5.20xx-xx-xx.0.log