0
# Client Setup & Authentication
1

2
Configuration and authentication options for connecting to JIRA instances. The library supports multiple authentication methods including Basic Auth, OAuth, JWT, and Kerberos.
3

4
## Capabilities
5

6
### JIRA Client Constructor
7

8
Primary interface for creating JIRA client connections with comprehensive authentication and configuration options.
9

10
```python { .api }
11
class JIRA:
12
    def __init__(
13
        self,
14
        server: str = None,
15
        options: dict = None,
16
        basic_auth: tuple = None,
17
        oauth: dict = None,
18
        jwt: dict = None,
19
        kerberos: bool = False,
20
        kerberos_options: dict = None,
21
        validate: bool = False,
22
        get_server_info: bool = True,
23
        async_: bool = False,
24
        async_workers: int = 5,
25
        logging: bool = True,
26
        max_retries: int = 3,
27
        proxies: dict = None,
28
        timeout: int = None,
29
        auth = None
30
    ):
31
        """
32
        Construct a JIRA client instance.
33
        
34
        Parameters:
35
        - server: JIRA server URL (default: http://localhost:2990/jira)
36
        - options: Dict of server configuration options
37
        - basic_auth: Tuple of (username, password) for HTTP basic authentication
38
        - oauth: Dict of OAuth authentication parameters
39
        - jwt: Dict of JWT authentication parameters for Atlassian Connect
40
        - kerberos: Boolean to enable Kerberos authentication
41
        - kerberos_options: Dict of Kerberos authentication options
42
        - validate: Boolean to validate credentials during instantiation
43
        - get_server_info: Boolean to fetch server version info
44
        - async_: Boolean to enable asynchronous operations
45
        - async_workers: Number of worker threads for async operations
46
        - logging: Boolean to enable logging
47
        - max_retries: Maximum number of retries for failed requests
48
        - proxies: Dict of proxy configuration
49
        - timeout: Request timeout in seconds
50
        - auth: Custom authentication object
51
        """
52
```
53

54
Usage examples:
55

56
**Basic Authentication:**
57
```python
58
from jira import JIRA
59

60
# Simple connection with basic auth
61
jira = JIRA(
62
    server='https://your-jira-instance.com',
63
    basic_auth=('username', 'password')
64
)
65
```
66

67
**OAuth Authentication:**
68
```python
69
oauth_dict = {
70
    'access_token': 'your-access-token',
71
    'access_token_secret': 'your-access-token-secret',
72
    'consumer_key': 'your-consumer-key',
73
    'key_cert': 'path/to/private-key.pem'
74
}
75

76
jira = JIRA(
77
    server='https://your-jira-instance.com',
78
    oauth=oauth_dict
79
)
80
```
81

82
**JWT Authentication (Atlassian Connect):**
83
```python
84
jwt_dict = {
85
    'secret': 'your-shared-secret',
86
    'payload': {
87
        'iss': 'your-plugin-key'
88
    }
89
}
90

91
jira = JIRA(
92
    server='https://your-jira-instance.com',
93
    jwt=jwt_dict
94
)
95
```
96

97
**Custom Options:**
98
```python
99
options = {
100
    'server': 'https://your-jira-instance.com',
101
    'rest_path': 'api',
102
    'rest_api_version': '2',
103
    'verify': True,
104
    'resilient': True,
105
    'async': False,
106
    'headers': {
107
        'Cache-Control': 'no-cache',
108
        'Content-Type': 'application/json'
109
    }
110
}
111

112
jira = JIRA(options=options, basic_auth=('username', 'password'))
113
```
114

115
### Configuration Helper Function
116

117
Convenient function for loading JIRA connection details from configuration files.
118

119
```python { .api }
120
def get_jira(
121
    profile: str = None,
122
    url: str = "http://localhost:2990",
123
    username: str = "admin",
124
    password: str = "admin",
125
    appid: str = None,
126
    autofix: bool = False,
127
    verify: bool = True
128
) -> JIRA:
129
    """
130
    Return a JIRA object by loading connection details from config file.
131
    
132
    Parameters:
133
    - profile: Section name from config.ini file
134
    - url: JIRA server URL
135
    - username: Username for authentication
136
    - password: Password for authentication
137
    - appid: Application ID
138
    - autofix: Boolean for auto-fixing issues
139
    - verify: Boolean for SSL certificate verification
140
    
141
    Returns:
142
    Configured JIRA client instance
143
    """
144
```
145

146
Usage example:
147
```python
148
from jira import get_jira
149

150
# Load from default profile in config file
151
jira = get_jira()
152

153
# Load from specific profile
154
jira = get_jira(profile='production')
155

156
# Override specific settings
157
jira = get_jira(
158
    profile='development',
159
    url='https://dev-jira.company.com',
160
    verify=False
161
)
162
```
163

164
### Session Management
165

166
Methods for managing JIRA sessions and authentication state.
167

168
```python { .api }
169
def session(self, auth = None) -> dict:
170
    """Get current session information."""
171

172
def kill_session(self) -> None:
173
    """Destroy the current session."""
174

175
def kill_websudo(self) -> None:
176
    """Destroy WebSudo session."""
177
```
178

179
### Server Information
180

181
Methods for retrieving server and connection information.
182

183
```python { .api }
184
def server_info(self) -> dict:
185
    """Get JIRA server information including version and build details."""
186

187
def myself(self) -> User:
188
    """Get information about the current authenticated user."""
189

190
def client_info(self) -> dict:
191
    """Get client connection information."""
192
```
193

194
Usage examples:
195
```python
196
# Get server information
197
server_info = jira.server_info()
198
print(f"JIRA Version: {server_info['version']}")
199
print(f"Build Number: {server_info['buildNumber']}")
200

201
# Get current user
202
current_user = jira.myself()
203
print(f"Logged in as: {current_user.displayName}")
204
print(f"Email: {current_user.emailAddress}")
205

206
# Get session details
207
session_info = jira.session()
208
print(f"Session Name: {session_info['name']}")
209
```
210

211
## Authentication Types
212

213
### Basic Authentication
214
HTTP Basic authentication using username and password:
215
```python
216
jira = JIRA(server='https://jira.company.com', basic_auth=('user', 'pass'))
217
```
218

219
### OAuth 1.0
220
OAuth authentication for applications:
221
```python
222
oauth = {
223
    'access_token': 'token',
224
    'access_token_secret': 'secret',
225
    'consumer_key': 'key',
226
    'key_cert': '/path/to/private.pem'
227
}
228
jira = JIRA(server='https://jira.company.com', oauth=oauth)
229
```
230

231
### JWT (JSON Web Token)
232
JWT authentication for Atlassian Connect apps:
233
```python
234
jwt = {
235
    'secret': 'shared-secret',
236
    'payload': {'iss': 'plugin-key'}
237
}
238
jira = JIRA(server='https://jira.company.com', jwt=jwt)
239
```
240

241
### Kerberos
242
Kerberos authentication for enterprise environments:
243
```python
244
jira = JIRA(
245
    server='https://jira.company.com',
246
    kerberos=True,
247
    kerberos_options={'mutual_authentication': 'DISABLED'}
248
)
249
```
250

251
## Options Dictionary
252

253
The `options` parameter accepts the following configuration keys:
254

255
- `server`: Server URL (default: http://localhost:2990/jira)
256
- `rest_path`: REST API path (default: api)
257
- `rest_api_version`: REST API version (default: 2)
258
- `agile_rest_path`: Agile API path (default: greenhopper)
259
- `verify`: SSL certificate verification (default: True)
260
- `client_cert`: Client certificate tuple for SSL
261
- `resilient`: Enable resilient session with retries (default: True)
262
- `async`: Enable async operations (default: False)
263
- `async_workers`: Number of async worker threads (default: 5)
264
- `headers`: Custom HTTP headers dictionary
265
- `cookies`: Custom cookies dictionary