FarmMaps/Documentatie
8
0
Fork 0
Code Pull Requests Releases Activity

Adding authentication articles

Browse Source
This commit is contained in:
Auke Sytsma 2020-04-17 16:08:10 +02:00
parent fe831fd327
commit ed3bfa6767
3 changed files with 78 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
Create-access-token.md Normal file
View File

@ -0,0 +1,26 @@
# Get an access token
This page explains how to get an access token, this token needs to be sent along when sending requests to the REST API.
Please follow the steps below
1. Go to the swagger documentation: [https://farmmaps.awacc.nl/swagger/index.html](https://farmmaps.awacc.nl/swagger/index.html)
2. Click "Authorize" and check the "Scopes" checkbox, click authorize again.
3. You will now be redirected to the FarmMaps OpenID login form, enter your details (akkerweb account, acceptation or test) and login.
4. Once logged in, you will automatically be redirected back to swagger again.
5. Close the "Available authorizations" popup.
6. Expand one of the items listed, for example "CodeListItem".
7. Click "Try it Out" and then "Execute"
8. Under "Responses" the curl command lists the access token after `-H "Authorization: Bearer `:
```
curl -X GET "https://farmmaps.awacc.nl/api/v1/codelistitems" -H "accept: application/json" -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkNERkM3M0I0NzY0Q0M5RTYxQTVDRjg3OEM5MDlFRUU0ODFFODk5MzEiLCJ0eXAiOiJhdCtqd3QiLCJ4NXQiOiJ6Znh6dEhaTXllWWFYUGg0eVFudTVJSG9tVEUifQ.eyJuYmYiOjE1ODcxMzE4ODMsImV4cCI6MTU4NzEzNTQ4MywiaXNzIjoiaHR0cHM6Ly9hY2NvdW50cy5mYXJtbWFwcy5hd2FjYy5ubCIsImF1ZCI6ImFwaSIsImNsaWVudF9pZCI6ImZhcm1tYXBzYWNjX3N3YWdnZXIiLCJzdWIiOiJtYWlsdG86YXVrZUBzaW1wZWx3ZWJkZXNpZ24ubmwiLCJhdXRoX3RpbWUiOjE1ODcxMzE4ODIsImlkcCI6ImxvY2FsIiwic2NvcGUiOlsiYXBpIl0sImFtciI6WyJwd2QiXX0.HOnc6ohPFljzPRXMpDnDMXlmlYCb5SBrNB3OMrpjAGx_TSES-ZJ8QuOwyeVLEn4LG0USkMzKZpR4MGAZvkN-5CgLu2unFWHjVBU_tY16QBg7pOnd-ZdXbMojINFk05EIFXEL2vBMWV1i3pxQVFK3jb7ybt_Lkw-X-2PwkcwaJk72aNY05pBswhyEr1PqSlVc5jOZuJzdzB6q17FRkCvxtIGmM-aSQpCozMdwD1CTu7ZBM_hvtFSmmkyWLh6PeFsj65ls18fWuBU_ekV3Djbj786GXRYUWS2_ObTbzfc0rEyy7fzesI1Jty6iYT6ZkUGl9NRt670wg7QZi7-qFRxglX6uU2JpW6veTBNkBgmDiJqbaSaJt-ADn32BGDjdSePxeD1shbeNAqYun9UkTn81PBptp3WpAd4hDuziL2k_m5IpryznJQu3G42Q27F3roFi4E1t7kcJNUs0umGPx_JTdMiipG-QOV20U4BnIOwH0qbxjUumEs24qCpT0YGArblK60a4_XFX6qinkKtUi4WfE5mHJnCF3y1iJ0hv0eGixzVLPGIcqTlSIFDIUhj_wzHSX-c5fXKIv-n9mE6_TBUoGZGdH2EAXq_ohTN_Ipmp2cmw7u7tFWOsPB-7UQzxh2dHDgtJ-V9u02j4jbCflRKuN7CQ5DB3Yvnfg2FuCoOSngQ"
```
So the access token is:
```
eyJhbGciOiJSUzI1NiIsImtpZCI6IkNERkM3M0I0NzY0Q0M5RTYxQTVDRjg3OEM5MDlFRUU0ODFFODk5MzEiLCJ0eXAiOiJhdCtqd3QiLCJ4NXQiOiJ6Znh6dEhaTXllWWFYUGg0eVFudTVJSG9tVEUifQ.eyJuYmYiOjE1ODcxMzE4ODMsImV4cCI6MTU4NzEzNTQ4MywiaXNzIjoiaHR0cHM6Ly9hY2NvdW50cy5mYXJtbWFwcy5hd2FjYy5ubCIsImF1ZCI6ImFwaSIsImNsaWVudF9pZCI6ImZhcm1tYXBzYWNjX3N3YWdnZXIiLCJzdWIiOiJtYWlsdG86YXVrZUBzaW1wZWx3ZWJkZXNpZ24ubmwiLCJhdXRoX3RpbWUiOjE1ODcxMzE4ODIsImlkcCI6ImxvY2FsIiwic2NvcGUiOlsiYXBpIl0sImFtciI6WyJwd2QiXX0.HOnc6ohPFljzPRXMpDnDMXlmlYCb5SBrNB3OMrpjAGx_TSES-ZJ8QuOwyeVLEn4LG0USkMzKZpR4MGAZvkN-5CgLu2unFWHjVBU_tY16QBg7pOnd-ZdXbMojINFk05EIFXEL2vBMWV1i3pxQVFK3jb7ybt_Lkw-X-2PwkcwaJk72aNY05pBswhyEr1PqSlVc5jOZuJzdzB6q17FRkCvxtIGmM-aSQpCozMdwD1CTu7ZBM_hvtFSmmkyWLh6PeFsj65ls18fWuBU_ekV3Djbj786GXRYUWS2_ObTbzfc0rEyy7fzesI1Jty6iYT6ZkUGl9NRt670wg7QZi7-qFRxglX6uU2JpW6veTBNkBgmDiJqbaSaJt-ADn32BGDjdSePxeD1shbeNAqYun9UkTn81PBptp3WpAd4hDuziL2k_m5IpryznJQu3G42Q27F3roFi4E1t7kcJNUs0umGPx_JTdMiipG-QOV20U4BnIOwH0qbxjUumEs24qCpT0YGArblK60a4_XFX6qinkKtUi4WfE5mHJnCF3y1iJ0hv0eGixzVLPGIcqTlSIFDIUhj_wzHSX-c5fXKIv-n9mE6_TBUoGZGdH2EAXq_ohTN_Ipmp2cmw7u7tFWOsPB-7UQzxh2dHDgtJ-V9u02j4jbCflRKuN7CQ5DB3Yvnfg2FuCoOSngQ
```
### Note
* The access token expires after one hour.

30
Home.md
View File

@ -15,17 +15,39 @@ At the moment, FarmMaps provides two environments for development.
When developing your application, using the **acceptation environment is highly recommended**.
### Credentials
### Obtaining credentials
To get access to the API, you need an akkerweb development account (akkerweb development and farmmaps development use the same credentials).
These can be created at:
* https://awacc.nl (for the acceptation environment)
* https://awtest.nl (for the testing environment)
### Authentication
To start uploading files, you need to authenticate to the API. The REST API uses OpenID Connect as the protocol.
Once you have an account, you can create a JSON Web Token to authenticate at the API endpoint.
[Todo: Basic explanation, based of "Authentication.md"]
### Authentication & Authorization flow
FarmMaps uses Open ID Connect to provide user authentication and authorization services.
Open ID Connect (and OAuth beneath the surface) allows your application to access user information or data that is located at another service, without providing you the password to access the account. This is very useful if your application relies on data that needs to provided by this other service for your application to work.
So, in the authentication flow there are two parties:
* The OpenID Provider (OP), holding the accounts database and providing the authentication services.
* The Relying Party (RP), relying on authentication through the OP, to get access to the required data or endpoints.
The general flow (for FarmMaps) is as follows:
* The user is at your application
* Your application needs to access the farmmaps account of that user (i.e. to upload, modify or retrieve data)
* Your application creates an authentication request for the Open ID Provider.
* The user is redirected to the "Log in page" of the OpenID Provider.
* The user logs in at the login page.
* On succesfull login, the user is redirected back to your application and the OpenID Provider returns an access token.
Now that the user is back at your applicaiton and the application has an access token, it can then request resources from the OpenID provider.
For each request, the access token needs to be sent along. This access token provides proof that the person sending the request is allowed to access the request and is who he/she claims to be. FarmMaps uses [JWT](https://jwt.io/introduction/) as the format for the access token.
To continue please see one of the articles below:
- [Integrating FarmMaps Open ID Connect into your application](/wiki/Integrating-FarmMaps-OIDC)
- [Creating an access token for testing.](/wiki/Create-access-token.md)
## How to build a FarmMaps App
- Accessing the API

26
Integrating-FarmMaps-OIDC.md Normal file
View File

@ -0,0 +1,26 @@
# Integrating FarmMaps OpenID Connect
Farmmaps uses OpenID Connect (OIDC).
This page lists the information needed to integrate OpenID connect into your application.
Note that for testing purposes it is quicker to just [generate an access token]() instead of implementing a complete integration.
Please see [https://openid.net/connect/](https://openid.net/connect/) if you are not familiar with OpenID Connect.
To integrate OIDC, it is recommended to use a (certified) library/implementation for your language of choice:
* [https://openid.net/developers/libraries/](https://openid.net/developers/libraries/)
When developing in C# / .NET, the recommended library is the `IdentityModel OpenID client`:
* [https://identitymodel.readthedocs.io/en/latest/native/overview.html](https://identitymodel.readthedocs.io/en/latest/native/overview.html)
To configure your library with the right settings, you'll need the Farmmaps OpenID configuration:
* https://accounts.farmmaps.awtest.nl/.well-known/openid-configuration
#### Note
* *At the moment, FarmMaps does not support dynamic client registration.
Please request a client id from one of our developers when you need one for your application.
In the meantime, it is recommended to simply [generate an access token]() to explore the REST API.*