Skip to content

Commit

Permalink
Merge pull request #193 from lumapps/MP-2254/use-application-token
Browse files Browse the repository at this point in the history 
Use application token in authentication
  • Loading branch information
@theo-ardouin
theo-ardouin committed Dec 14, 2023
2 parents 20dbf38 + fe1889d commit e72132f
Show file tree
Hide file tree
Showing 17 changed files with 161 additions and 1,180 deletions.
1 change: 0 additions & 1 deletion config/coverage.ini
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@ source =
tests
parallel = true
omit =
lumapps/api/authlib_helpers.py
lumapps/latest/api/swagger/**
**/__init__.py
examples/**
Expand Down
126 changes: 17 additions & 109 deletions docs/authentication.md
View file
Original file line number Diff line number Diff line change
@@ -1,134 +1,42 @@
# Authentication

The first thing you'll need in order for you to be able to use the LumApps Api's is a valid token.
The first thing you'll need in order for you to be able to use the LumApps Api is a valid token.

You can see them [here](https://apiv1.lumapps.com/#tag/Authentication)

The LumApps sdk can help you when using a service account or a regular token, all you have to do is to give the sdk the credentials infos and the subsequent calls made by the tool will be authenticated using those credentials.

**Note**:

Be sure to target the right lumapps environment, by default the sdk use site.lumapps.com as an environment.
If your env is different (eg, sites-ms.lumapps.com) you can precise it like so:

```python
from lumapps.api.base_client import BaseClient
api_info = {
"base_url": "https://sites-ms.lumapps.com"
}
client = BaseClient(token="<your_token>", api_info=api_info)
```
Be sure to target the right lumapps environment. Refer to the [environment documentation](https://lumapps.github.io/lumapps-sdk/environment) first.

## Using a regular token

To authenticate with a regular, short lived token, instanciate the sdk like so:

```python
from lumapps.api.base_client import BaseClient
client = BaseClient(token="<your_token>")
```

## Using an authorized service account

By default a service account does not allows you to contact all LumApps API endpoints, to do so you need to get a token as a given user and then use this token to authenticate the requests

<details>
<summary>An example with curl</summary>
<p>

The flow is as follow:
<br>

<ol>
<li>
With your service account get a google access token
<div style="margin: 8px;">
To know how to get this token with curl and you service account follow <a href="https://gist.github.com/ryu1kn/c76aed0af8728f659730d9c26c9ee0ed" target="_blank"> this tutorial</a>
<br/>
For an extended documentation on that process you can follow the <a href="https://developers.google.com/identity/protocols/oauth2/service-account" target="_blank"> google documentation</a>
</div>
</li>
<li>
Use this token as the bearer token to call the <a href="https://apiv1.lumapps.com/#operation/User/Gettoken" target="_blank"> user/get endpoint</a>
<br/>
<div>
<pre>
<code>
curl -s -X GET https://<you_lumapps_env_base_url>/_ah/api/lumsites/v1/user/getToken?customerId=<my_platform_id>&email=<user_email_I_want_to_autehntify_as> \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <the_google_access_token_you_got_previously>"
</code>
</pre>
</div>
</li>
<li>
Use the returned LumApps access token to authenticate your subsequent requests to LumApps Api's.
<br/>
For instance you can call the user/get endpoint:
<div>
<pre>
<code>
curl -s -X GET https://<you_lumapps_env_base_url>/_ah/api/lumsites/v1/user/get \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <the_lumapps_access_token_you_got_previously>"
</code>
</pre>
</div>
</li>
</ol>

</p>
</details>

<details>
<summary>An example with Postman</summary>
<p>

The flow is the same as with curl but to do it with postman there are some specificities and that's why we provide a <a href="../static/get_token_postman_collection.json" target="_blank">collection that illustrate it</a>.

<br/>

This collection uses <a href="https://learning.postman.com/docs/sending-requests/variables" target="_blank">postman variables</a> and you have to set some to use it:

<br/>
<ul>
<li><i>sa_private_key</i>: Private of the service account</li>
<li><i>sa_email</i>: Service account email</li>
<li><i>lumapps_base_env_url</i>: The base url of the LumApps env (eg, https://sites.lumapps.com)</li>
</ul>

<br/>

You'll also have to execute in order, the requests are numbered so make sure to execute them from 1 to 4.

</p>
</details>
client = BaseClient(api_info, token="<your_token>")
```

<details>
<summary>With the LumApps sdk</summary>
<p>
## Using an application

The sdk BaseClient offers two methods to help with that `get_new_client_as` and `get_new_client_as_using_dwd` that allows you to get a new BaseClient correctly authenticated.
First of all, please create an application following the documentation on the [dev portal](https://developer.lumapps.com/documentation/oauth).

Then, the sdk BaseClient offers one method to retrieve a new authenticated `BaseClient`: `get_new_client_as`.

```python
from lumapps.api.base_client import BaseClient
my_service_account = {...}
my_platform_id="<your_plaform_id>"

my_application = {
"client_id": "<application_client_id>",
"client_secret": "<application_client_secret>",
}
customer_id = "<your_customer_id>"
user_to_authenticate_on_behalf_of = "<user_email>"

client = BaseClient(
auth_info=my_service_account)
.get_new_client_as(
user_email=user_to_authenticate_on_behalf_of,
customer=platform_id
)
api_info, auth_info=my_application
).get_new_client_as(
user_to_authenticate_on_behalf_of, customer_id
)
```
</p>
</details>

**Note**:

The LumApps bearer token you get in that case extends to 24h instead of 1h.
11 changes: 6 additions & 5 deletions docs/environment.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
# Environment

As your LumApps platform can be on a specific environment you'll need to give the ApiClient the correct base url in order for it to work correctly.
As your LumApps platform can be on a specific environment you'll need to give the BaseClient the correct base url in order for it to work correctly.

By default the ApiClient uses `https://sites.lumapps.com`.
This information can be found in the debug dialog in the customer platform (**CTRL + ?** or **CTRL + SHIFT + ?**) in `Haussmann Cell`.

It should be under the following format: `https://XX-cell-YYY.api.lumapps.com`.

To use another base url (you can find more informations about those url [here](https://docs.lumapps.com/docs/home/architecture/archi-lumapps-platform-site-architecture)) you have to do:

```python
from lumapps.api.client import ApiClient
from lumapps.api.client import BaseClient

client = ApiClient(api_info={"base_url": <my_base_url>})
client = BaseClient({"base_url": <my_base_url>})
```
3 changes: 1 addition & 2 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,7 @@ Python >= 3.8
The fastest one to implement is the following:

Get your token by logging to your LumApps account.
Go to [https://sites.lumapps.com](https://sites.lumapps.com) and authenticate.
Once connected, open the javascript console of your browser and run:
Once connected on your platform, open the javascript console of your browser and run:

```javascript
fetch(window.location.origin+"/service/user/token", {method: "POST"})
Expand Down
Loading

0 comments on commit e72132f

Please sign in to comment.