OAuth2 Authentication

OAuth2 Authentication

OAuth2 Authentication

Sign up for a free trial account

To implement any AfriGIS web services protected by OAuth2, sign up for a free trial account by contacting [email protected]. Assistance is available from the 24-hour Call Centre, should it be required.

Three ‘random’ strings, for each API to be accessed, will be provided: an App Client ID and App Client Secret as well as an API Key.  These will be explained in more detail below.

OAuth2 process

APIs are now deployed to a cloud provider and make use of OAuth2 for authentication and authorisation.  There is a 2-step process to follow:

  1. Obtain an access token that is valid for 1 hour
  2. Call the API with this access token and an API key

 

Obtain an OAuth2 access token

Credentials in header

Make a POST request to https://auth.afrigis.services/oauth2/token in Client Credentials mode.

Use Basic Authentication, with the App Client ID as the username and the App Client Secret as the password.

Set the Content-Type to application/x-www-form-urlencoded with a single parameter grant_type set to client_credentials.

The response will be JSON, from which the access_token can be extracted, as in the example below:

{
    “access_token”: “eyJraWQiOiJXcURTMHRaZ2lQb1wvZnVVWVhnaEVYK21USXRLN25oOFBtT0U1eWw2Zmk4Zz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI3dmJsbXZsNm11OWxnc29vcTJhZnB1YjlzcyIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoicGxhY2VzXC9nZW9jb2RlLXJlYWQgcGxhY2VzXC9yZXZlcnNlZ2VvY29kZS1yZWFkIHBsYWNlc1wvYXV0b2NvbXBsZXRlLXJlYWQgcGxhY2VzXC9kZXRhaWxzLXJlYWQiLCJhdXRoX3RpbWUiOjE2MjM2NTkxMDcsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5ldS13ZXN0LTEuYW1hem9uYXdzLmNvbVwvZXUtd2VzdC0xX1ZlbnJsRjBsQyIsImV4cCI6MTYyMzY2MjcwNywiaWF0IjoxNjIzNjU5MTA3LCJ2ZXJzaW9uIjoyLCJqdGkiOiIyY2ZkMjhjMy1mYTdkLTRhYWEtODY3My0wNzYxZmQ4ZWI5MzUiLCJjbGllbnRfaWQiOiI3dmJsbXZsNm11OWxnc29vcTJhZnB1YjlzcyJ9.PBTrcx6EJ4JHQKzoXQeEMbymT-a4IXuB5hImsxyl284rU_VTb2ryIuE9VQWzBDQjhxkWXUEmntGQaHMre9xyjeDNb4xPsRVE8FyugdFOmJqcXh0W69kLjk44qbLI0CPGRQmTd0w6NhISDhUJzmJHZMNzNn5aA0rrhSfW2fqxZHPKEcWzAy3_USbh7ExOrC1cfmMv6xPXf1xL-b0BKlEcF4AWAYoaT7-v9rWUJ3ZLBQv4IEsQMj-HBZnPX3jk8gAk8ozHoU735yBxWfRAuInUd5UnqIq7xD13koC3tqSTAJz9lS4uEV7wNZXRrGsSTyH9ekVUrXcNb-FrlsuIX5mjRw”,
    “expires_in”: 3600,
    “token_type”: “Bearer”
}
Credentials in body

When making a request to the token endpoint, include the following parameters in the x-www-form-urlencoded format in the request body:

grant type(Required). Specifies the type of OIDC grant you are requesting. Valid values – client_credentials

client_id (Optional). Not required if you include the app client ID in the Authorization header. You must include this parameter if you are using client_secret_post authorization with client_secret

client_secret(Optional). Not required when you provide the client secret in the Authorization header. Valid values – The app client secret, if the app client has one, for client_secret_post authorization.

Example Request Body:

1 grant_type=client_credentails

2 &client_id=yourAppClientID

3 &client_secret=yourAppClientSecret

Note that the access_token expires after 3600 seconds i.e., 1 hour, after which your application must renew the token.

Call the API using Request parameters in header

Now make a GET, POST or other request to the provided endpoint, starting with https://afrigis.services/

The value of the access_token (starting with eyJ…, ending with …jRw in the example above) should be placed in the Authorization HTTP header, along with a prefix of  “Bearer ” (the word Bearer followed by a space then the access_token) i.e.

Authorization: Bearer eyJ…..jRw

Add another HTTP header: x-api-key with the API Key provided by AfriGIS.

Error messages

There are some common error messages that might be encountered when accessing the AfriGIS services.

{
    “message”: “The incoming token has expired”
}

Most will be self-explanatory like the one above, but if one similar to the below is encountered:

<access_token> not a valid key=value pair (missing equal-sign) in Authorization header: ‘Bearer <access_token>

 

then double check that the API path after the Base URL is 100% correct, e.g.:

https://afrigis.services/geocode/<incorrect_path_here>/api/v3/address

Exceptions to OAuth2 Authentication: AfriGIS Data and Maps

Lastly, there are a few exceptions to the AfriGIS OAuth2 authentication.  This is relevant to AfriGIS data and mapping products. These products follow slightly different authentication methods.  Follow the link below for their documentation.

References to APIs using OAuth2