GSD oAuth Configuration

[Since 2.2.0]

Available OAuth providers

The REST API can be configured to work with following OAuth providers:

  • Google
  • Facebook
  • Windows Live
  • Apple ID

RestApi OAuth configuration

To enabling OAuth login your api-config.yml should include needed providers (those providers are configurable in DF RestApi configuration ). You can configure it based on the example below.

1
2
3
4
5
6
7
oAuthProviders: # Array of enabled oauth providers.        
    -
        name: Facebook
    -
        name: Google1 
    -
        name: WindowsLive

To check the entire configuration file please go here api-config.yml

Registering RestApi application in OAuth providers

To register RestApi to work with one of above OAuth providers one has to follow a custom instruction provided by given OAuth provider.
OAuth callback url schema: https://$yourDomain:$yourPort/$yourDbAlias/v1/$providerNameLowerCase/callback

Many dbs registered on one port!

If you have many databases configured for one RestApi, callback for every database with proper database alias should be registered. If you have only one database configured with RestApi without alias, '$yourDbAlias' should be left as empty.

Setting OAuth clients credentials

Every OAuth provider should be configured in DOCUframe. To configure OAuth provider one has to open RestApi menu and choose Login proivders option

Screenshot


To add a provider right click on the list. Select the type for the provider (for Google can be Google, for facebook Facebook). This name is important, it must be used in RestApi configuration as a provider name. In DOCUframe you can register many providers of a given type (e.q. facebook or google) with different clientId and clientSecret keys. However, one particular RestApi instance can use only one configuration for a given provider type. Therefore, in DOCUframe name property was introduced. Last step is to configure of additional data.

Screenshot

It is possible to define a default DOCUframe user for a Provider. It means that, when a new user is connecting via RestApi to a database, he will have a DOCUframe user automatically assigned. If the default assignment is not enough, it is possible to extend the configuration with an event:

1
2
3
4
5
6
7
INT xRestApi_DBCreateInit_xRestApiUserProvider( 
         xRestApiUserProvider userObject, 
         xRestApiProviderConfig providerConfig, 
         STRING userUuid, 
         STRING name, 
         STRING surname, 
         STRING email )

In this event the userObject is already locked.

The fields "userUuid", "name", "surname", "email" are provided from OAuth provider.

Google, Facebook, WindowsLive additional data configuration

In field additional data add a JSON object with clientId and clientSecret fields with your credentials. For example:

1
2
3
4
{
    "clientId":"yourClientId",
    "clientSecret":"yourClientSecret"
}

You can obtain clientId and clientSecret from OAuth provider. For more info see following link: Google example As a result of a configuration complete object should look like

Apple ID additional data configuration

In field additional data add a JSON object. For example:

1
2
3
4
5
6
7
{
    "clientId": "Service ID Identifier",
    "serverAddress": "External addess of your server (ex.: https://api.gsd.pl)",
    "teamId": "Team ID of your Accout",
    "keyIdentifier": "ID of p8 certificate",
    "keyPath": "path to the p8 certificate"
}

Prerequisites

  • You should be enrolled in Apple Developer Program.
  • Please have a look at Apple documentation related to "Sign in with Apple" feature.
  • You should create App ID and Service ID in your Apple Developer Account.
  • You should generate private key for your Service ID in your Apple Developer Account.

The information's can be obtained from Apple Developer Account:

  • clientId - 'Certificates, Identifiers & Profiles' => 'Identifiers' => 'Services ID' => 'Identifier'
  • serverAddress - the address of your server must be https
  • teamId - 'Membership' => 'Team ID'
  • keyIdentifier - 'Certificates, Identifiers & Profiles' => 'Keys' => 'Key ID'
  • keyPath - 'Certificates, Identifiers & Profiles' => 'Keys' => 'Download'

OAuth Login

There are 4 types of login:

  • 1) Normal DOCUframe user, which is using DOCUframe Username and DOCUframe Web password
  • 2) NOT DOCUframe user, which is using external Login provider (Google or Facebook)
  • 3) Normal DOCUframe user, which is using external Login provider (Google or Facebook)
  • 4) NOT DOCUframe user, which is using DOCUframe custom authentication (For example: contact person email and custom password)

Case 1

Standard case handled by standard login path.

Case 2 and 3

Example

Get request
1
2
3
4
GET http://localhost:8080/v1/auth/${providerName}

Request Headers:
appkey: 123

To login using this flow one has to make an api call on path v1/auth/${providerName} (according to api documentation). This request will start OAuth flow. You will be redirected to OAuth provider page in order to validate your OAuth credentials. After successfully credentials validation you should get response from RestApi. If this is a first time login you should get a response with dfUuid:

Response
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{  
   "status":{  
      "internalStatus":"0",
      "statusMessage":"No DF user assing to this account, please assign DF user",
      "debugMessage":"No DF user assing to this account, please assign DF user"
   },
   "data":{  
      "dfUuid":"ab65f6f7-0611-452a-9a0d-9ea39a0d5c6b"
   }
}

Next step is to make a v1/extLogin (according to api documentation) request with above dfUuid, DOCUframe user and DOCUframe web password.

Example

Post request
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
POST http://localhost:8080/v1/extLogin

POST data:
{
"user": "GSDWebservice",
"pass": "aab185a0b33d014157e1519445587d1f",
"dfUuid": "ab65f6f7-0611-452a-9a0d-9ea39a0d5c6b",
"appNames": ["GSD-RestApi"]
}

Request Headers:
appkey: 123
Content-Type: application/json

This request assigns provided user(in case 2 there will be a GSDWebservice, in case 3 it can be any other DOCUframe user) with given OAuth provider uid. As a response you should get a valid session in the context of provided user credential. Next time when you make a OAuth login request you should get a sessionId response immediately.

Response
1
2
3
4
5
6
7
8
9
{  
   "status":{  
      "internalStatus":"0",
      "statusMessage":"ok"
   },
   "data":{  
      "sessionId":"99d86976-5fdf-4e21-b02c-68cf287f6a06"
   }
}

Case 4

In order to login to DOCUframe using custom authentication one has make a request on path v1/auth/df and provide username and password for not DOCUframe user as well as appNames for example:

Example

Post request
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
POST http://localhost:8080/v1/auth/df

POST data:
{
    "user": "AnsprechPartner",
    "pass": "aab185a0b33d014157e1519445587d1f", 
    "appNames": ["GSD-RestApi"]
}

Request Headers:
appkey: 123
Content-Type: application/json
Response
1
2
3
4
5
6
7
8
9
{  
   "status":{  
      "internalStatus":"0",
      "statusMessage":"ok"
   },
   "data":{  
      "sessionId":"99d86976-5fdf-4e21-b02c-68cf287f6a06"
   }
}