API Authentication

13 mars 2024 à 17:28 Edit on Gitlab

Authentication

Table of Contents

Basic Auth

Basic Auth is no longer supported. Please use OAuth2.0 to authenticate towards the API.

Updating custom scripts from Basic Auth to OAuth

If you are using a custom made script using Basic Auth (with your username and password) you will need to change your script to use OAuth Authentication.

OAuth will use a personal client identifier and client secret in place of your username and password. You will be authenticated as your regular user.

Here are the steps to update your scripts:

  1. Send us the informations needed to Register an OAuth client of type Client credential (don’t forget to specify your username).
  2. Once your Client identifier and Client secret received update your script as in the example below.

Example: Original Basic Auth script

# 1. Get observations
#    Replace USERNAME and PASSWORD
curl --user "USERNAME:PASSWORD" -X GET "https://obs.infoflora.ch/rest/v4/observations" -H "accept: application/json"

Example: Updated OAuth script

This exemple uses the jq package to extract the access_token value from the json response. You might need to install this package.

# 1. Get an access token (valid 1 hour) for your client identifier
#    and client secret and store it in $ACCESS_TOKEN.
#    Replace CLIENT_ID and CLIENT_SECRET
ACCESS_TOKEN=$(curl --location --request POST 'https://auth.infoflora.ch/oauth2/token' \
--user "CLIENT_ID:CLIENT_SECRET" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=CLIENT_ID' 2>/dev/null | jq -r '.access_token')
# 2. Get observations
#    Replace USERNAME and PASSWORD
curl -X GET "https://obs.infoflora.ch/rest/v4/observations" \
  -H "accept: application/json" -H "authorization: Bearer $ACCESS_TOKEN"

OAuth2.0 authentication

Authentication and authorization with OAuth2 is allowed using the Authorization code flow with PKCE flow or Client credentials flow.

To get started, you first need to get register a client and get a client unique identifier (client_id) and an accompanying secret key (client_secret). Once your client is registered, you can authenticate using these endpoints:

Some documentation about OAuth2

Getting a token using the Authorization Code Grant Flow

There is 3 main parts to authentication when using the Authorization Code Grant Flow with PKCE.

  1. Requesting the authorization code
  2. Exchanging this authorization code for an access token
  3. Refreshing the access token
                                          +-------------------+
                                          |   Authz Server    |
+--------+                                | +---------------+ |
|        |--(A)- Authorization Request ---->|               | |
|        |       + t(code_verifier), t_m  | | Authorization | |
|        |                                | |    Endpoint   | |
|        |<-(B)---- Authorization Code -----|               | |
|        |                                | +---------------+ |
| Client |                                |                   |
|        |                                | +---------------+ |
|        |--(C)-- Access Token Request ---->|               | |
|        |          + code_verifier       | |    Token      | |
|        |                                | |   Endpoint    | |
|        |<-(D)------ Access Token ---------|               | |
+--------+                                | +---------------+ |
                                          +-------------------+

Part 1 and 2 illustrated. Illustration taken from RFC 7636, section 1.1

1. Requesting the authorization code

You will need to send a GET request looking like this:

https://auth.infoflora.ch/oauth2/authorize/fr
?client_id=CLIENT_ID
&redirect_uri=CLIENT_REDIRECT_URI
&code_challenge=CODE_CHALLENGE
&code_challenge_method=S256
&response_type=code

  • CLIENT_ID is the id of the client you registered ;

  • CLIENT_REDIRECT_URI is one of the URLs you registered for your client on which you wish to receive the generated autorisation code and tokens see Register an OAuth client ;

  • CODE_CHALLENGE is a Base64 URL Encoded value of a random string hashed using the SHA256 algorithm. For details on how to generate the code_challenge value, please see Client Creates a Code Verifier.
    Here is an exemple in PHP of the challenge generation from the code verifier string that you will use on the next request.

    // A random generated string for this authorization request. This value is to be store for later use.
$codeVerifier = \base64_encode(random_bytes(32));

// The code verifier is encoded
$encodedCodeChallenge = \base64_encode(\hash('sha256', $codeVerifier, true));
$codeChallenge = \rtrim($encodedCodeChallenge, '=');

If the request is successful (the user has been successfully authenticated), the authorization server will redirect the Client to the redirect_uri provided in the request and will attach to this redirect URL an authorization code. The authorization code will need to be used in the following request to exchange it for the access token. (ex: https://my-app.com/oauth2redirect?code=AUTHORIZATION_CODE)

2. Exchanging this authorization code for an access token

With the obtained authorization code you can exchange it for an access token. To do this you need a POST request using Basic Auth to submit your CLIENT_SECRET. It is the recommended way to authenticate using the Client Credentials Flow. The request will look like this:

curl --location --request POST 'https://auth.infoflora.ch/oauth2/token' \
--user "CLIENT_ID:CLIENT_SECRET"
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=CLIENT_ID' \
--data-urlencode 'code=AUTHORIZATION_CODE' \
--data-urlencode 'redirect_uri=CLIENT_REDIRECT_URI' \
--data-urlencode 'code_verifier=CODE_VERIFIER'
  • CLIENT_ID is the id of the client you registered ;
  • CLIENT_SECRET is the secret associated to the client you registered ;
  • CLIENT_REDIRECT_URI is one of the URLs you registered for your client on which you wish to receive the generated autorization code and tokens see Register an OAuth client ;
  • CODE_VERIFIER is the earlier generated random string you used to generate the CODE_CHALLENGE ;
  • AUTHORIZATION_CODE is the code you received from the authorization server at the first step.

If you cannot use Basic Auth to submit your CLIENT_SECRET you also can sent it in your request payload like this:

Including the client credentials in the request-body using the two parameters is NOT RECOMMENDED and SHOULD be limited to clients unable to directly utilize the HTTP Basic authentication scheme (or other password-based HTTP authentication schemes). The parameters can only be transmitted in the request-body and MUST NOT be included in the request URI.

curl --location --request POST 'https://auth.infoflora.ch/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=CLIENT_ID' \
--data-urlencode 'client_secret=CLIENT_SECRET' \
--data-urlencode 'code=AUTHORIZATION_CODE' \
--data-urlencode 'redirect_uri=CLIENT_REDIRECT_URI' \
--data-urlencode 'code_verifier=CODE_VERIFIER'

If the request is successful, then authorization server will respond with the tokens.

{
    "token_type": "bearer",
    "expires_in": 3600,
    "access_token": "ACCESS_TOKEN",
    "refresh_token": "REFRESH_TOKEN"
}

You can now make authenticated requests on the API using the access token you received. Note that the access token obtained has a short validity. You will very likely need to refresh it at one point.

3. Refreshing the access token

Upon expiration of the access token obtained above, you will need to use the refresh token to get an new access token. To do this you need a POST request looking like this:

curl --location --request POST 'https://auth.infoflora.ch/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id=CLIENT_ID' \
--data-urlencode 'client_secret=CLIENT_SECRET' \
--data-urlencode 'refresh_token=REFRESH_TOKEN'
  • CLIENT_ID is the id of the client you registered ;
  • CLIENT_SECRET is the secret associated to the client you registered ;
  • REFRESH_TOKEN is the refresh token received when exchanging the authorization code for the token on step 2.

If the request is successful, then authorization server will respond with the tokens.

{
    "token_type": "bearer",
    "expires_in": 3600,
    "access_token": "ACCESS_TOKEN",
    "refresh_token": "REFRESH_TOKEN"
}

Getting a token using the Client Credentials Flow

Obtaining a token with the Client Credentials Flow is relatively simple.

+---------+                                  +---------------+
|         |                                  |               |
|         |>--(A)- Client Authentication --->| Authorization |
| Client  |                                  |     Server    |
|         |<--(B)---- Access Token ---------<|               |
|         |                                  |               |
+---------+                                  +---------------+

Client Credentials Flow illustrated. Illustration taken from RFC 6749, section 2.3

You will need to send a POST request containing your CLIENT_ID in the request payload and use Basic Auth to submit your CLIENT_SECRET. It is the recommended way to authenticate using the Client Credentials Flow. The request will look like this:

curl --location --request POST 'https://auth.infoflora.ch/oauth2/token' \
--user "CLIENT_ID:CLIENT_SECRET" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=CLIENT_ID'
  • CLIENT_ID is the id of the client you registered ;
  • CLIENT_SECRET is the secret associated to the client you registered ;

If you cannot use Basic Auth to submit your CLIENT_SECRET you also can sent it in your request payload like this:

Including the client credentials in the request-body using the two parameters is NOT RECOMMENDED and SHOULD be limited to clients unable to directly utilize the HTTP Basic authentication scheme (or other password-based HTTP authentication schemes). The parameters can only be transmitted in the request-body and MUST NOT be included in the request URI.

curl --location --request POST 'https://auth.infoflora.ch/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=CLIENT_ID' \
--data-urlencode 'client_secret=CLIENT_SECRET'
  • CLIENT_ID is the id of the client you registered ;
  • CLIENT_SECRET is the secret associated to the client you registered ;

If the request is successful, then authorization server will respond with the tokens.

{
    "token_type": "bearer",
    "expires_in": 3600,
    "access_token": "ACCESS_TOKEN"
}

Accessing the API endpoint whith your token

Once you have obtained your token you can access the endpoints by adding an Authorization header to your request.

GET /api-endpoint-url HTTP/2.0
Host: example.com
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

If you are using curl you can use the following command

curl -X GET "https://obs.infoflora.ch/rest/v4/api-endpoint-url" -H "accept: application/json" -H "authorization: Bearer ACCESS_TOKEN"