Each district has a SameGoal SFTP account. This account is most often used to store ephemeral data files uploaded and processed nightly for integrations with your student information system. It can also be used to transfer large amounts of data securely during district onboarding.
Steps
To configure your SFTP account:- Generate your keypair
- Sync your public key
- Verify you can connect
Each SameGoal SFTP account uses public key authentication to ensure secure access. Public key authentication is a more secure means of identifying yourself to a login server than using a password.
When using public key authentication, you generate a public/private key pair consisting of a public key (which everybody is allowed to know) and a private key (which you keep secret and do not give to anybody). Your public key is placed on the server you wish to connect to (in this case, on the SameGoal SFTP server in an authorized_keys file) and your private key is kept on your local workstation. When you use your private key to connect, it generates a signature. A signature created using your private key cannot be forged by anybody who does not have that key, but anyone who has your public key can verify that a particular signature is genuine.
Mac or Linux. Use the ssh-keygen utility to generate an OpenSSH-style public/private key pair on the command line.
- Open a terminal.
- <user>@dev1:~$ ssh-keygen
- Enter file in which to save the key (/home/<user>/.ssh/id_rsa): Press enter to accept default location
- Enter passphrase (empty for no passphrase): Press enter to leave passphrase empty
- Enter same passphrase again: Press enter to leave passphrase empty
- Once your keys have been generated, they will be saved in your ~/.ssh directory:
- Private key: /home/<user>/.ssh/id_rsa.pub
- Public key: /home/<user>/.ssh/id_rsa
Windows. Use PuTTYgen to generate a PPK-style public/private key pair.
- Download 64-bit puttygen.exe from the PuTTY download page
- Launch the program. Set Type of keys to generate to RSA if not set by default. Click the Generate button.
- Click the Save public key button. Recommended file name: id_rsa.pub
- Click the Save private key button. When prompted "Are you sure you want to save this key without a passphrase to protect it?" choose Yes. Recommended file name: id_rsa.ppk
- Copy the key from the PuTTYgen window to your clipboard to paste into SameGoal when syncing your public key.
lightbulb Tip
If necessary, you may
convert an OpenSSH-style private key to a PPK-style private key or vice versa easily.
Add your public key to your SFTP account authorized_keys file using the SameGoal web interface:
- Login with an administrative account.
- Visit Settings > Technical Settings.
- Mac or Linux: Copy/paste the contents of id_rsa.pub into the SFTP Account authorized_keys files box.
- Windows: Copy and paste the public key from the PuTTYgen window. This will ensure that the line breaks are removed. Do not copy/paste the contents of the id_rsa.pub file generated by PuTTYgen.
- Scroll to the bottom of the page and click the Save button.
- It can take up to 60 minutes to propagate new key information to the server after updating the authorized_keys file.
- Verify you are able to connect to your SFTP account 60 minutes after updating your keys.
Use an SFTP tool to connect. Connection information:
- Host: sftp.samegoal.com
- Username: your district domain
- Authentication: Public key only
- Upload directory: /upload/
lightbulb Tip
If you recently added or changed key information, wait 60 minutes before trying to connect.
lightbulb Tip
Do not use SSH or SCP to test the connection. You do not have shell access and these programs will appear to hang when you appear to connect.
lightbulb Tip
If you are having trouble connecting, make sure you are using keys compatible with the SFTP tool you are using. For example:
- WinSCP uses a PPK-style private key. Use your id_rsa.ppk file to connect.
- SG-Agent, Cyberduck, OpenSSH and SG-SFTP require OpenSSH-style public/private keys. Use your id_rsa.pub and id_rsa files to connect.
Each SFTP account has the following directory structure:
- /upload/ - Uploads to this directory are automatically detected and inspected by SameGoal processes.
- If the uploaded data files (in a date-time epoch directory) are recognized to be in a format expected for a particular integration, SameGoal will automatically process the files.
- If the uploaded information format is not recognized (eg. a one-time data dump from a previous system), the data will be ignored until a SameGoal staff member is notified and manually processes.
- This directory is the only directory the district can write to.
- If the district uses an SFTP-based (push-based) integration, a district process will write to this directory.
- If the district uses a SIF-based (pull-based) integration, a SameGoal process will write to this directory.
- /upload-processed/ - After an epoch directory in /upload/ is automatically processed, it is moved to /upload-processed/ with additional logging inserted to indicate whether processing succeeded or failed. Processed epochs are stored in this directory for a short while (typically 30 days), but may be deleted at any time without notice.
- /downloads/ - This directory contains information each district may download from their SameGoal environment. Besides the two directories below, districts may see additional directories depending on integrations available in their state. These directories are empty if not used.
- /downloads/backups/ - PostgreSQL backups of district data.
- /downloads/docviewer/ - Daily epochs of document viewer data for optional use in the generic alerts & document viewer integration.