Skip to content

Commit 7a7909b

Browse files
adobeDanadobeDan
authored
Merge pull request #20 from adobe-apiplatform/v2
Now that the Github Pages wiki is working, clean up the docs for 2.0b2
2 parents 84b7b2c + deb6fa3 commit 7a7909b

File tree

4 files changed

+179
-62
lines changed

4 files changed

+179
-62
lines changed

‎README.md

Lines changed: 14 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -18,50 +18,25 @@ to install from the download.
1818

1919
# Building
2020

21-
1. Clone this repository or download the latest stable release.
21+
1. Clone this repository or download one of the posted releases.
2222
2. From the command line, change to the `umapi-client.py` directory.
2323
3. To install, run the command `python setup.py install`.
24-
[**NOTE**: You may need admin/root privileges to install new packages in your environment.
25-
It is recommended that you use `virtualenv` to make a virtual python environment.
26-
See the [virtualenvwrapper documentation](http://virtualenvwrapper.readthedocs.io/en/latest/index.html)
27-
for more information]
24+
[**NOTE**: To avoid needing admin/root privileges for the installation
25+
of needed dependencies,
26+
it is recommended that you use `virtualenv` (or equivalent)
27+
to make a virtual python environment. See the
28+
[virtualenvwrapper documentation](http://virtualenvwrapper.readthedocs.io/en/latest/index.html)
29+
for more information.
2830
4. Some of the packages required by this module use encryption, and so may
2931
require you to do local builds of modules that use SSL. Typically, this
30-
will require you to have to `python-dev` module installed (on all platforms),
31-
and there may be other platform-specific requirements (e.g., on Mac OS X,
32-
you will need to make sure the latest SSH libraries are on your LIBPATH.)
32+
will require you to have a python installed that supports compiling
33+
extensions.
3334
5. To run tests, use the command `python setup.py test`.
3435

35-
# Getting Started
36+
# Usage
3637

37-
Before making calls to the User Management API, you must do the following preparation steps:
38+
Usage documentation, as well as information about how to get client
39+
credentials for use of the UMAPI, can be found on the
40+
[umapi-client wiki](https://adobe-apiplatform.github.io/umapi-client.py/),
41+
whose sources are in the `docs` directory of this repository.
3842

39-
1. Obtain admin access to an Adobe Enterprise Dashboard.
40-
2. Set up a private/public certificate pair
41-
3. Create an integration on [Adobe.IO](https://www.adobe.io/)
42-
43-
Step 1 is outside of the scope of this document.
44-
Please contact your organization's administrator of your Dashbord environment to obtain access.
45-
Steps 2 and 3 are outlined in the
46-
[UMAPI documentation](https://www.adobe.io/products/usermanagement/docs/gettingstarted.html).
47-
48-
Once access is obtained, and an integration is set up, you will need the following configuration items:
49-
50-
1. Organization ID
51-
2. Tech Account ID
52-
3. IMS Hostname
53-
4. IMS Auth Token Endpoint (JWT Endpoint)
54-
5. API Key
55-
6. Client Secret
56-
7. Private Key File (unencrypted form)
57-
58-
All but the last of these will be available on the adobe.io page for your integration.
59-
The last one you should have on your local disk, and keep secret.
60-
61-
Once these initial steps are taken, and configuration items are identified,
62-
then you will be able to use this library to make API calls.
63-
64-
# Usage Documentation
65-
66-
The usage documentation may be found on a separate site, which is currently
67-
under construction. Please check back on January 2, 2017 for more details.

‎docs/index.md

Lines changed: 34 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -13,57 +13,72 @@ of the OSI-approved MIT license. Copyright (c) 2016 Adobe Systems Incorporated.
1313
# Installation
1414

1515
You can get this package from PyPI: `pip install umapi-client`.
16-
Or you can download the posted package from GitHub and use pip
17-
to install from the download.
16+
Or you can download the desired release package
17+
from [GitHub](https://github.com/adobe-apiplatform/umapi-client.py/)
18+
and use pip to install from the download.
1819

1920
# Building
2021

21-
1. Clone this repository or download the latest stable release.
22+
1. Clone
23+
[the Github repository](https://github.com/adobe-apiplatform/umapi-client.py/)
24+
or download one of
25+
[the posted releases](https://github.com/adobe-apiplatform/umapi-client.py/releases).
2226
2. From the command line, change to the `umapi-client.py` directory.
2327
3. To install, run the command `python setup.py install`.
24-
[**NOTE**: You may need admin/root privileges to install new packages in your environment.
25-
It is recommended that you use `virtualenv` to make a virtual python environment.
26-
See the [virtualenvwrapper documentation](http://virtualenvwrapper.readthedocs.io/en/latest/index.html)
27-
for more information]
28+
[**NOTE**: To avoid needing admin/root privileges for the installation
29+
of needed dependencies,
30+
it is recommended that you use `virtualenv` (or equivalent)
31+
to make a virtual python environment. See the
32+
[virtualenvwrapper documentation](http://virtualenvwrapper.readthedocs.io/en/latest/index.html)
33+
for more information.
2834
4. Some of the packages required by this module use encryption, and so may
2935
require you to do local builds of modules that use SSL. Typically, this
30-
will require you to have to `python-dev` module installed (on all platforms),
31-
and there may be other platform-specific requirements (e.g., on Mac OS X,
32-
you will need to make sure the latest SSH libraries are on your LIBPATH.)
36+
will require you to have a python installed that supports compiling
37+
extensions.
3338
5. To run tests, use the command `python setup.py test`.
3439

3540
# Getting Started
3641

37-
Before making calls to the User Management API, you must do the following preparation steps:
42+
Before making calls to the User Management API, you must complete
43+
the following prepartory steps:
3844

3945
1. Obtain admin access to an Adobe Enterprise Dashboard.
40-
2. Set up a private/public certificate pair
46+
2. Set up a private/public key pair
4147
3. Create an integration on [Adobe.IO](https://www.adobe.io/)
4248

4349
Step 1 is outside of the scope of this document.
44-
Please contact your organization's administrator of your Dashbord environment to obtain access.
50+
Please contact an administrator of your organization's
51+
Dashbord environment to obtain access.
4552
Steps 2 and 3 are outlined in the
4653
[UMAPI documentation](https://www.adobe.io/products/usermanagement/docs/gettingstarted.html).
4754

48-
Once access is obtained, and an integration is set up, you will need the following configuration items:
55+
Once access is obtained, and an integration is set up,
56+
you will need the following configuration values:
4957

5058
1. Organization ID
5159
2. Tech Account ID
5260
3. IMS Hostname
53-
4. IMS Auth Token Endpoint (JWT Endpoint)
61+
4. IMS Token Exchange Endpoint (aka JWT Endpoint)
5462
5. API Key
5563
6. Client Secret
5664
7. Private Key File (unencrypted form)
5765

58-
All but the last of these will be available on the adobe.io page for your integration.
66+
All but the last of these will be available on the
67+
[adobe.io page for your integration](https://www.adobe.io/console/integrations).
5968
The last one you should have on your local disk, and keep secret.
6069

6170
Once these initial steps are taken, and configuration items are identified,
6271
then you will be able to use this library to make API calls.
6372

6473
# Usage Documentation
6574

66-
We are still working on the version 2 usage documentation.
75+
All new users of the library are highly recommended
76+
to pick up version 2, and follow the
77+
[version 2 usage documentation](usage-instructions-v2.html).
6778

68-
You can find the version 1 documentation
69-
[here](usage-instructions-v1.html).
79+
Users who have applications running against version 1
80+
of the library can still use the version 2 implementation,
81+
but they will need to do some package renames to get access
82+
to the version 1 library classes. This is
83+
outlined in the
84+
[version 1 usage documentation](usage-instructions-v1.html).

‎docs/usage-instructions-v1.md

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
1-
# Usage Instructions
1+
# V1 Usage Instructions (updated for the v2 release)
22

3-
The information below was written for version 1 of the client
3+
The information below was originally written for version 1 of the client
44
library. Since all of the version 1 functionality is now
55
available (in a faster, easier-to-use form) from the v2 client
66
library, it is recommend that new users start with v2. However,
77
v1 users who have not yet upgraded their applications to the use
8-
the v2 client can still access this functionality in the
9-
umapi_client.legacy package, as detailed below.
8+
the v2 classes can still access v1 classes in the v2 release
9+
by using the `umapi_client.legacy` package. The details
10+
are in the material below.
1011

1112
These instructions presume you have already created your
1213
[Adobe.IO](https://www.adobe.io/) integration, as described

‎docs/usage-instructions-v2.md

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# V2 Usage Instructions
2+
3+
4+
These instructions presume you have already created your
5+
[Adobe.IO](https://www.adobe.io/) integration, as described
6+
in the [home page](index.html) of this documentation.
7+
8+
# Getting a Connection
9+
10+
All UMAPI access is predicated on the creation of an authenticated,
11+
authorized connection to the UMAPI server. This access always
12+
happens in the context of a particular integration (as created
13+
on adobe.io). So it requires the following details about
14+
your integration:
15+
16+
1. Organization ID
17+
2. Tech Account ID
18+
3. IMS Hostname
19+
4. IMS Token Exchange Endpoint (aka JWT Endpoint)
20+
5. API Key
21+
6. Client Secret
22+
7. Private Key File (unencrypted form)
23+
24+
Of these, the IMS Hostname and the IMS Token Exchange Endpoint
25+
are standard across almost all integrations, so they are
26+
built into the library as defaults and aren't typically needed.
27+
The Tech Account ID, API Key, and Client Secret are sensitive,
28+
as is the Private Key File, so a best practice is to keep
29+
these values in files separate from your application. The
30+
Organization ID is not as sensitive, but it's best to keep
31+
it with the others since it's also needed for authentication.
32+
33+
For example, suppose `config.yaml` is a YAML file
34+
whose content contains
35+
the sensitive data (elided here for security):
36+
37+
```yaml
38+
org_id: '620049..............101@AdobeOrg'
39+
tech_acct_id: '[email protected]'
40+
api_key: '265434.............d740ac'
41+
client_secret: 'cc6.....-....-47b9-....-......ff3725'
42+
private_key_file: '/path/to/my.secret.key.pem'
43+
```
44+
45+
and suppose `my.secret.key.pem` contains an unencrypted
46+
private key
47+
like this (again, elided for security):
48+
49+
```
50+
-----BEGIN RSA PRIVATE KEY-----
51+
MIIEpAIBAAKCAQEAxBc5BFNUP9hdGHSuOzfxoyL2qq2qcqpSexLsefQS9fDZZjCP
52+
...
53+
fIOe8cq8F5Vcw6l5NwmW+Lw44hJxKAVRg+j79x6C6+zLblRhm+dHBw==
54+
-----END RSA PRIVATE KEY-----
55+
```
56+
57+
Given these two files, you can establish an authenticated,
58+
authorized connection with code such as the following:
59+
60+
```python
61+
import yaml # PyYAML from PyPI provides this module
62+
63+
with open(config_file_name, "r") as f:
64+
config = yaml.load(f)
65+
conn = umapi_client.Connection(org_id=config["org_id"],
66+
auth_dict=creds)
67+
```
68+
69+
The constructor of the Connection object will do all the
70+
work of contacting the token exchange endpoint and using
71+
your credentials to obtain an access token, and it will
72+
remember that access token for use with all your UMAPI
73+
operations. It will be called `conn` in the examples
74+
that follow.
75+
76+
(If you want the details of how access token exchange
77+
is done by the constructor, see the code or the
78+
[v1 usage docs](usage-instructions-v1.html).)
79+
80+
# Querying for Users and Groups
81+
82+
Queries for users and groups are implemented by
83+
classes which allow iterating the results. These
84+
iterators pull the results from the server in
85+
batches of 200 or so, and cache the results locally.
86+
You can access the full list of results with
87+
the `all_results` method, and force the query
88+
to be reloaded and run from the beginning again
89+
with the `reload` method.
90+
91+
Each fetched user or group is represented as
92+
a Python dictionary of its attributes.
93+
94+
## Get a List of Users
95+
96+
```python
97+
users = QueryUsers(conn)
98+
# print first 5 users
99+
for i, user in enumerate(users):
100+
if i == 5: break
101+
print("User %d email: %s" % (i, user["email"]))
102+
# get a count of all users (finishes the iteration)
103+
user_count = len(users.all_results())
104+
```
105+
106+
## Get a List of Groups
107+
108+
This list of groups will contain both user groups and product license
109+
configuration groups.
110+
111+
```python
112+
groups = QueryGroups(conn)
113+
# print all the group details
114+
for group in groups:
115+
print(group)
116+
# after an hour, see if anything has changed
117+
time.sleep(3600)
118+
groups.reload()
119+
for group in groups:
120+
print(group)
121+
```
122+
123+
# Performing Operations on Users
124+
125+
_...under construction..._
126+

0 commit comments

Comments
 (0)