1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
## liboidcagent-py
A `python` library for `oidc-agent` is available at
https://github.com/indigo-dc/liboidc-agent-py.
To use it in your `python` application install it with
```
pip install liboidcagent
```
and import it with:
```python
import liboidcagent as agent
```
### Error Handling
The library will raise an exception of type `OidcAgentError` if something goes
wrong.
Error Handling can be done the following way:
```python
try:
print(agent.get_access_token(account_name))
except agent.OidcAgentError as e:
print("ERROR oidc-agent: {}".format(e))
```
### Requesting an Access Token For an Account Configuration
The following functions can be used to obtain an access token for a specific
account configuration from `oidc-agent`. If you / your application does not
know which account configuration should be used, but you know for which provider
you need an access token you can also [request an access token for a
provider](#requesting-an-access-token-for-a-provider).
#### get_access_token
```python
def get_access_token(account_name, min_valid_period=0,
application_hint=None, scope=None, audience=None)
```
This function requests an access token from oidc-agent for the `account_name`
account configuration. The access token should have `scope` scopes, be
valid for at least `minValidPeriod` seconds, and have the `audience` audience.
##### Parameters
- `account_name` is the shortname of the account configuration that should be
used.
- If `min_valid_period` is
`0` (default) no guarantee about the validity of the token can be made; it is possible
that it expires before it can be used. Can be omitted.
- `application_hint` should be the name of the application that
requests an access token. This string might be displayed to the user for
authorization purposes. Can be omitted.
- If `scope` is None, the
default scopes for that account are used. So usually it is enough to use `None`
or to omit this parameter.
- If `audience` is None, no special audience is requested for this access
token. This parameter is used to request an access token with a specific audience.
##### Return Value
The function returns only the access token. To additionally obtain other
information use [`get_token_response`](#get_token_response).
##### Example
A complete example can look the following:
```python
token = agent.get_access_token(account_name, 60, "example-app")
print("Access token is: {}".format(token))
```
#### get_token_response
```python
def get_token_response(account_name, min_valid_period=0,
application_hint=None, scope=None, audience=None)
```
This function requests an access token from oidc-agent for the `account_name`
account configuration. The access token should have `scope` scopes, be
valid for at least `min_valid_period` seconds, and have the `audience` audience.
##### Parameters
- `account_name` is the shortname of the account configuration that should be
used.
- If `min_valid_period` is
`0` (default) no guarantee about the validity of the token can be made; it is possible
that it expires before it can be used. Can be omitted.
- `application_hint` should be the name of the application that
requests an access token. This string might be displayed to the user for
authorization purposes. Can be omitted.
- If `scope` is None, the
default scopes for that account are used. So usually it is enough to use `None`
or to omit this parameter.
- If `audience` is None, no special audience is requested for this access
token. This parameter is used to request an access token with a specific audience.
##### Return Value
The function returns three values: the requested
access token, the url of the issuer that issued the token and the time when the
token expires.
The values can be accessed the following way:
```python
token, iss, exp = agent.get_token_response(account_name, 60, "example-app")
token // access token
iss // issuer url
exp // expiration time
token_response = agent.get_token_response(account_name, 60, "example-app")
token_response[0] // access token
token_response[1] // issuer url
token_response[2] // expiration time
```
##### Example
A complete example can look the following:
```python
token, iss, exp = agent.get_token_response(account_name, 60, "example-app")
print("Access token is: {}".format(token))
print("Access token issued by: {}".format(iss))
print("Access token expires at: {}".format(exp))
```
### Requesting an Access Token For a Provider
The following functions
can be used to obtain an access token for a specific OpenID Provider (issuer).
This might be useful for applications that only work with a specific provider
and therefore know the issuer for which they need an access token, but do not
require the user to provide an account configuration shortname.
#### get_access_token_by_issuer_url
```python
def get_access_token_by_issuer_url(issuer_url, min_valid_period=0,
application_hint=None, scope=None,
audience=None)
```
This function requests an access token from `oidc-agent` for the provider with
`issuer_url`. The access token should have `scope` scopes, be valid for at least `min_valid_period` seconds, and have the `audience` audience.
##### Parameters
- `issuer_url` is the issuer url of the provider for which an access token
should be obtained.
- If `min_valid_period` is
`0` (default) no guarantee about the validity of the token can be made; it is possible
that it expires before it can be used. Can be omitted.
- `application_hint` should be the name of the application that
requests an access token. This string might be displayed to the user for
authorization purposes. Can be omitted.
- If `scope` is None, the
default scopes for that account are used. So usually it is enough to use `None`
or to omit this parameter.
- If `audience` is None, no special audience is requested for this access
token. This parameter is used to request an access token with a specific audience.
##### Return Value
The function returns only the access token. To additionally obtain other
information use
[`get_token_response_by_issuer_url`](#get_token_response_by_issuer_url).
##### Example
A complete example can look the following:
```python
token = agent.get_access_token_by_issuer_url("https://example.com", 60, "example-app")
print("Access token is: {}".format(token))
```
#### get_token_response_by_issuer_url
```python
def get_token_response_by_issuer_url(issuer_url, min_valid_period=0,
application_hint=None, scope=None,
audience=None)
```
This function requests an access token from oidc-agent for the provider with
`issuer_url`. The access token should have `scope` scopes, be
valid for at least `min_valid_period` seconds, and have the `audience` audience.
##### Parameters
- `issuer_url` is the issuer url of the provider for which an access token
should be obtained.
- If `min_valid_period` is
`0` (default) no guarantee about the validity of the token can be made; it is possible
that it expires before it can be used. Can be omitted.
- `application_hint` should be the name of the application that
requests an access token. This string might be displayed to the user for
authorization purposes. Can be omitted.
- If `scope` is None, the
default scopes for that account are used. So usually it is enough to use `None`
or to omit this parameter.
- If `audience` is None, no special audience is requested for this access
token. This parameter is used to request an access token with a specific audience.
##### Return Value
The function returns three values: the requested
access token, the url of the provider that issued the token and the time when the
token expires.
The values can be accessed the following way:
```python
token, iss, exp = agent.get_token_response_by_issuer_url(issuer_url, 60, "example-app")
token // access token
iss // issuer url
exp // expiration time
token_response = agent.get_token_response_by_issuer_url(issuer_url, 60, "example-app")
token_response[0] // access token
token_response[1] // issuer url
token_response[2] // expiration time
```
##### Example
A complete example can look the following:
```python
token, iss, exp = agent.get_token_response_by_issuer_url("https://example.com", 60, "example-app")
print("Access token is: {}".format(token))
print("Access token issued by: {}".format(iss))
print("Access token expires at: {}".format(exp))
```
|
