Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Status
subtletrue
colourGreenBlue
title>= v0.7

Starting with v0.7, Giles has a two part authentication mechanism. First, it requires applications to send an OpenId app token (supplied by Google) generated by Giles for a specific app) and the token of an identity provider to authenticate a user. Giles then generates a shorter-lived authentication token specifically for Giles that can be used to use Giles' REST Api . In addition, in on behalf of a user.

To register an application with Giles:

  1. Login as administrator. 
  2. Go to "Apps" in the main menu and click on the "Register App" button.
  3. Enter a name for the application you are registering and select what identity provider your app is using.
  4. Click register.

On the next page, Giles will present you with an access token for your app. Make sure to copy it and keep it safe! Once you leave this page, there is no way to retrieve the token from Giles again. For security reasons, Giles does not store access tokens.

Warning

Never share Giles access tokens and keep them safe. Anyone with an access token can use Giles API on your app's behalf.


Status
colourYellow
titleOpenId
 In order to be able to authenticate users via an OpenId Connect token, in addition to the steps described above, any application also needs to be registered with Giles first.to register their client id. To do this, go to Giles' system config page and add the client id (not the secret!) that your OpenId provider (currently Google) generated for your application to the list of registered client ids. If you try to authenticate a user with an OpenId token of an unregistered application, Giles will respond with:

Code Block
{
  "errorCode" : "401",
  "errorMsg" : "AUDIENCE_MISMATCH"
}

Retrieve Giles authentication token

...

An application can retrieve a new Giles authentication token for a user by making a POST request to the following url:

/rest/token

Giles will expect an OpenId token app token (generated as described above) in the POST Authorization header prefixed with "token":

Authorization:   token yourOpenIDTokenyourAppsAccessToken

The body of your request should contain form-data with a parameter called "providerToken" that contains the token for the user your app is trying to authenticate (e.g. the GitHub token of a user).

If successful, we will get the following response:

...

An invalid or missing token, will result in the following response:. The provider key/value pair tells you if there was an issue with the Giles app token or the token of your identity provider.

Code Block
{
  "provider" : "APP_TOKEN_GILES",
  "errorCode" : "401",
  "errorMsg" : "Missing or invalid token."
}

With the returned Giles authentication token, you can now use Giles' REST Api.

Warning

Keep in mind that API tokens are user-specific and are used for authorization. This means that you need to request an API token for each of your users. API tokens contain information about a user and are used to assign uploads to the correct user.

Expired Giles Tokens

When sending an expired Giles token, the following response is returned:

...