Skip to content

Commit 5b0d7fe

Browse files
BryanFaubleBryanFauble
authored
[SYNPY-893] Add multiple profile support (#1194)
* Add multiple profile support to the Synapse config file, allowing a single config file to log into several different synapse accounts --------- Co-authored-by: Carmen Montero <[email protected]> Co-authored-by: BryanFauble <[email protected]>
1 parent f348ee7 commit 5b0d7fe

15 files changed

+993
-355
lines changed

‎docs/tutorials/authentication.md

Lines changed: 109 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
[](){ #tutorial-authentication }
22
# Authentication
33

4-
There are multiple ways one can login to Synapse. We recommend users to choose the method that fits their workflow.
4+
There are multiple ways one can login to Synapse. We recommend users choose the method that fits their workflow best.
55

66
## Prerequisites
77

8-
* Create a [Personal Access Token](https://help.synapse.org/docs/Managing-Your-Account.2055405596.html#ManagingYourAccount-PersonalAccessTokens) (**aka: Synapse Auth Token**) token obtained
8+
* Create a [Personal Access Token](https://help.synapse.org/docs/Managing-Your-Account.2055405596.html#ManagingYourAccount-PersonalAccessTokens) (**aka: Synapse Auth Token**) obtained
99
from synapse.org under your Settings.
1010
* Note that a token must minimally have the **view** scope to be used with the Synapse Python Client.
1111
* Include **Download** and **Modify** permissions if you are using the Synapse Python Client to follow any subsequent tutorials.
@@ -20,6 +20,7 @@ Use the [synapseclient.login][synapseclient.Synapse.login] function
2020
```python
2121
import synapseclient
2222
syn = synapseclient.login(authToken="authtoken")
23+
#returns Welcome, First Last!
2324
```
2425

2526
### Command Line Client
@@ -38,43 +39,133 @@ Logged in as: username (1234567)
3839

3940
For writing code using the Synapse Python client that is easy to share with others, please do not include your credentials in the code. Instead, please use the `~/.synapseConfig` file to manage your credentials.
4041

42+
The Synapse Python Client supports multiple profiles within the `~/.synapseConfig` file, enabling users to manage credentials for multiple accounts. Each profile is defined in its own `[profile <profile_name>]` section. A default profile can still be defined using `[default]`.
43+
4144
When installing the Synapse Python client, the `~/.synapseConfig` is added to your home directory.
4245

4346
### Automatically modifying the `~/.synapseConfig` file with the Command line Client
4447
You may modify the `~/.synapseConfig` file by utilizing the [command line client command and following the interactive prompts](./command_line_client.md#config):
4548

49+
#### Modifying the synapse config for multiple profiles
50+
4651
<!-- termynal -->
4752
```
4853
> synapse config
49-
Synapse username (Optional):
54+
55+
Synapse username (Optional): $MY_USERNAME
56+
57+
Auth token: $MY_SYNAPSE_TOKEN
58+
59+
Configuration profile name (Optional, 'default' used if not specified): $MY_CONFIG_PROFILE
60+
```
61+
62+
#### Adding or updating a specific profile passed in as a command line argument
63+
<!-- termynal -->
64+
```
65+
> synapse --profile $MY_PROFILE_NAME config
66+
67+
Synapse username (Optional): $MY_USERNAME
5068
5169
Auth token: $MY_SYNAPSE_TOKEN
5270
```
5371

72+
Note: If you encounter a PermissionError
73+
(e.g., `[Errno 13] Permission denied: '/Users/username/.synapseConfig'`), it is likely that the user does not have write permissions to the `~/.synapseConfig` file.
74+
To resolve this, ensure that you have the necessary permissions to modify this file.
75+
You can change the permissions using the following command:
76+
77+
`chmod u+w ~/.synapseConfig`
78+
79+
5480
### Manually modifying the `~/.synapseConfig` file
5581
The following describes how to add your credentials to the `~/.synapseConfig` file without the use of the `synapse config` command.
5682

57-
Open the `~/.synapseConfig` file and find the following section:
83+
Open the `~/.synapseConfig` file using your preferred text editing tool and find/insert the following section(s):
5884

5985
```
86+
[default]
87+
username = default_user
88+
authtoken = default_auth_token
89+
90+
[profile user1]
91+
username = user1
92+
authtoken = user1_auth_token
93+
94+
[profile user2]
95+
username = user2
96+
authtoken = user2_auth_token
97+
98+
# This section is deprecated. It will be used if a `default` profile or a specific profile is not present in the config file
6099
#[authentication]
61-
#username = <username>
62-
#authtoken = <authtoken>
100+
#username = default_user
101+
#authtoken = default_auth_token
63102
```
64103

65-
To enable this section, uncomment it. You don't need to specify your username when using authtoken as a pair, but if you do, it will be used to verify your identity. A personal access token generated from your synapse.org Settings can be used as your .synapseConfig authtoken.
104+
`username` is optional when using `authtoken`, but if provided, an additional check to verify the `authtoken` matches the `username` is performed.
105+
106+
The `authoken` is also know as a personal access token. It is generated from your [synapse.org Settings](https://help.synapse.org/docs/Managing-Your-Account.2055405596.html#ManagingYourAccount-PersonalAccessTokens)..
107+
108+
### Transitioning from One Profile to Multiple
109+
110+
If you're currently using a single profile (under the `[default]` or `[authentication]` section) and wish to start using multiple profiles,
111+
simply add new sections for each profile with a unique profile name. For example, you can add a profile for user1 and user2 as shown below.
112+
The Synapse Python client will allow you to choose which profile to use at login.
113+
66114
```
67-
[authentication]
68-
authtoken = <authtoken>
115+
[default]
116+
username = default_user
117+
authtoken = default_auth_token
118+
119+
[profile user1]
120+
username = user1
121+
authtoken = user1_auth_token
122+
123+
[profile user2]
124+
username = user2
125+
authtoken = user2_auth_token
69126
```
70127

71-
Now, you can login without specifying any arguments:
128+
## Logging in with your ~/.synapseConfig file
129+
130+
**Note:** If no profile is specified the `default` section will be used. Additionally, to support backwards compatibility, `authentication` will continue to function. `authentication` will be used if no profile is used and `default` is not present in the configuration file.
131+
132+
### Logging in via python code
72133

73134
```python
74135
import synapseclient
75136
syn = synapseclient.login()
76137
```
77138

139+
If you want to log in with a specific profile, simply pass the profile name as an argument to `login()`:
140+
141+
```python
142+
import synapseclient
143+
syn = synapseclient.login(profile="user1")
144+
```
145+
146+
### Logging in via the command line
147+
148+
Logs in with the `default` profile, or the profile set in the `SYNAPSE_PROFILE` environment variable:
149+
150+
<!-- termynal -->
151+
```
152+
#For default login
153+
> synapse login
154+
155+
returns Welcome, last first!
156+
```
157+
158+
Logging in with the `profile_name` given:
159+
160+
<!-- termynal -->
161+
```
162+
#For profile login
163+
164+
> synapse --profile profile_name login
165+
166+
Welcome, last first! You are using the 'profile_name' profile.
167+
```
168+
78169
## Use Environment Variable
79170

80171
Setting the `SYNAPSE_AUTH_TOKEN` environment variable will allow you to login to Synapse with a [Personal Access Token](https://help.synapse.org/docs/Managing-Your-Account.2055405596.html#ManagingYourAccount-PersonalAccessTokens)
@@ -87,21 +178,26 @@ In your shell, you can pass an environment variable to Python inline by defining
87178
SYNAPSE_AUTH_TOKEN='<my_personal_access_token>' python3
88179
```
89180

90-
Alternatively you may export it first, then start: Python
181+
Alternatively you may export it first, then start Python:
91182

92183
```bash
93184
export SYNAPSE_AUTH_TOKEN='<my_personal_access_token>'
94185
python3
95186
```
96187

97-
Once you are inside Python, you may simply login without passing any arguments:
188+
Setting the `SYNAPSE_PROFILE` environment variable will allow you to log into Synapse using a specific authentication profile present in your `.synapseConfig` file. This allows you to have multiple profiles present in a single configuration file that you may swap between. Alternatively, you may use the `profile` parameter in Python, or the `--profile` command line flag for all commands like `synapse --profile <profile_name> COMMAND`.
189+
190+
Once you are inside Python, you may simply login without passing any arguments, or pass a profile argument to access a specific profile:
98191

99192
```python
100193
import synapseclient
101194
syn = synapseclient.login()
195+
196+
import synapseclient
197+
syn = synapseclient.login(profile="user1")
102198
```
103199

104-
To use the environment variable with the command line client, simply substitute `python` for the `synapse` command
200+
To use the environment variable with the command line client, simply substitute `python` for the `synapse` command:
105201

106202
```bash
107203
SYNAPSE_AUTH_TOKEN='<my_personal_access_token>' synapse get syn123

0 commit comments

Comments
 (0)