Third party authentication

Graphileon allows authentication with third party authentication providers that use the Oauth 2.0 protocol.

Currently the following authentication providers are supported: Google, Facebook, Okta (over Oauth 2.0) and Twitter.

Third party authentication allows Graphileon to receive (current) user information from another web service called Provider or Authenticator (ex Google, Facebook, Okta) in which the user is already registered (with name, email, picture etc) and logged-in. This removes the need for manual user registration using a form, manual login with password, user authorisation (rights) management in Graphileon and allows for seamless registration and login.

To implement 3rd party authentication Graphileon uses the Node.js library Passport.js that allows easy integration of new providers or authentication protocols.

Third party authentication

How it works

Most people already use web services like Google, Facebook, Twitter etc. which require user account registration and often times the user is already logged in to one or more of these services.

Graphileon can be registered into one (or multiple) of these services for authentication purposes. A user who is logged in into Google, for example, can use the button "Sign in with Google" in Graphileon and so allows Graphileon to receive the Google profile information (name, email(s), picture and others). An internal Graphileon account will be created for this user (or an existing one will be used) based on the received data without the need for manual registration or the use of passwords.

We call a Profile the user's data received from an authentication provider. This consist usually in full name, email, a unique id (generated by the provider to identify the user), profile picture etc.

Setup

Graphileon configuration

Choose a label/name

You must choose a label (name) for the authentication method/provider that will be used to identify it inside the application. The name must contain only characters: a-z, A-Z, 0-9, _. You can choose names like google, facebook, okta or something more relevant for the use case. Your chosen authentication label will be marked <auth-label> in this documentation.

`config.json` setup

Start editing Graphileon's config.json.

Make sure you have the authentication group inside the config.json file or add it to match this structure:

    "authentication": {
        "default": false,
        "<auth-label>": {
            "enabled": true,
            "type":"<authentication-type>",
            "createAccounts": false,
            "audience": "<provided-by-authentication-platform>",
            "clientID": "<provided-by-authentication-platform>",
            "clientSecret": "<provided-by-authentication-platform>"
        }
    }

Inside authentication you can add configuration for multiple authentication providers but they must have different labels (<auth-label>).

Key	Description	Type	Possible values
`default`	Authenticator that will be used automatically when Graphileon is loaded in the browser. This makes the log-in/sign-in process seamless for the user as Graphileon will not show a login screen. This process assumes the user is already logged in into the Provider's platform. If not, the user will be redirected to the login screen of the Provider. If the user does not login into the Provider but tries to load Graphileon again within a minute the login screen will be shown.	`string` / `false`	`false` / `<auth-label>`
`<auth-label>`	Configuration for an Authentication Provider	`object`
`<auth-label>.enabled`	`true` if you want to make this authentication method available or to `false` to disable it (temporarily)	`boolean`	`true`/`false`
`<auth-label>.type`	Specifies what type of authentication to be used	`string`	`facebook`, `google`, `okta`, `twitter`
`<auth-label>.createAccounts`	If set to `true` enables `sign-up` process. A new Graphileon account will be created when a user (with Provider account) uses with this authentication method without having an existing Graphileon account linked to this Profile. When set to `false` and the Profile received from the Provider does not match any Graphileon account the authentication will fail and the user will not be logged in.	`boolean`	`true` / `false`
`<auth-label>.audience`	URL to the Authentication Provider (see `Provider configuration`). Used only for Okta configuration	`string`
`<auth-label>.clientID`	Identifier of Graphileon generated by the Authentication Provider in the setup process (see `Provider configuration`)	`string`
`<auth-label>.clientSecret`	Secret key generated by the Authentication Provider in the setup process (see `Provider configuration`)	`string`

Provider configuration

In order to allow user data exchange Graphileon must be registered as an application in the provider's administration panel.

Before you start configuring Graphileon in Authentication Provider administration panel make sure you have set up basic configuration for Graphileon and that you can load the application in the browser.

You have to know the Base URI of Graphileon, meaning the URL that users use to load Graphileon in the browser (ex: http://my-graphileon.my-company.com). Make sure you use the appropriate HTTP scheme (http:// or https://) when you are asked to enter it.

Google

Go to https://console.developers.google.com/

1. Create a new project

You can select an already existing project and omit this step.

On the top left of the page click on the current project's name or Select a project.

Click on New project (top right of the window).

Give a name to the project (ex: Graphileon).

Optionally select an organisation for this project.

Click Create.

Make sure this new project is selected on the top left of the page, otherwise select it.

2. Setup the OAuth consent screen

In the left side menu select OAuth consent screen.

Create a consent screen according to your usage.

This is the page that Google users see when they are asked to allow Graphileon to use their data.

3. Create OAuth credentials

In the left side menu select Credentials.

On the top click + Create credentials and select OAuth client ID.

For application type select Web application.

Use a meaningful name for Name (ex: graphileon-authentication).

For the Authorised JavaScript origins field set Graphileon's Base URI. You can add both http://... and https://... if you use both protocols.

For Authorised redirect URIs field enter: http://<graphileon-base-uri>/api/authentication/<auth-label>/callback and https://<graphileon-base-uri>/api/authentication/<auth-label>/callback (if you use HTTPS).

Click Save.

4. Set the credentials in Graphileon

A window will appear containing ClientID and Client secret. Set these values in Graphileon's config.json file for their appropriate configuration keys and save the file.

audience key is not used for Google authentication so you can delete this key.

Example of configuration:

    "authentication": {
        "default": false,
        ...// other authentication methods (optional)
        "google": {
            "enabled": true,
            "type":"google",
            "createAccounts": false,
            "clientID": "<provided-by-authentication-platform>",
            "clientSecret": "<provided-by-authentication-platform>"
        }
    }

Save config.json.

Restart Graphileon server and reload it in the browser.

If no user is logged in you should see the Sign-in with Google button on the login screen.

Facebook

Go to https://developers.facebook.com/.

1.Create a new Facebook application

You can select an already existing application and omit this step.

On the top right, click My apps and (+) Create App.

Enter the Display name of the application (ex: 'Graphileon login') and (your) contact email.

Click Create App ID.

2.Set up application

On the left side menu click Settings and Basic.

In App domains field type the Graphileon's Base URI (without protocol http:// or https://).

Save changes

On the top of this page you can find App ID and App secret which are the ClientID and ClientSecret values that need to be configured in Graphileon's config.json.

3.Setup FB login

On the left-side menu click on Dashboard.

Find the Facebook login panel and click Set Up.

On the left-side menu, under Facebook login click on Settings.

In the Valid OAuth Redirect URIs enter <graphileon-base-url>/api/authentication/<auth-label>/callback.

Save changes.

4.Set the credentials in Graphileon

Set up ClientID and Client secret (taken form the Settings -> Basic page on top) in Graphileon's config.json file for their appropriate configuration keys and save the file.

audience key is not used for Facebook authentication so you can delete this key.

Example of configuration:

    "authentication": {
        "default": false,
        ...// other authentication methods (optional)
        "facebook": {
            "enabled": true,
            "type":"facebook",
            "createAccounts": false,
            "clientID": "<provided-by-authentication-platform>",
            "clientSecret": "<provided-by-authentication-platform>"
        }
    }

Restart Graphileon server and reload it in the browser.

If no user is logged in you should see the Sign-in with Facebook button on the login screen.

5. Make the feature available to everybody else

These are the basic steps needed to setup Graphileon to authenticate with Facebook.

Next you need to take the necessary steps to move the Facebook app into live mode which require you to set up other fields as per your case: Privacy Policy, Terms of service URL, Category etc.

Read more at: https://developers.facebook.com/docs/apps/#development-mode and https://developers.facebook.com/docs/facebook-login/

Okta

Go to your Okta administration panel.

1. Create a new application

From the top menu select Applications.

Click the green + Add application button.

Choose Web and Next.

Pick a suggestive name for this application and Done.

The new application has been created.

2. Setup OAuth

From the top menu select Applications.

In the applictions list click the name of the app that Graphileon corresponds to (created at 1. Create a new application).

Choose the General tab and Edit.

In the section Login redirect URIs add two URI: http://<graphileon-base-uri>/api/authentication/<auth-label>/callback and https://<graphileon-base-uri>/api/authentication/<auth-label>/callback.

Set Login initiated by to App Only.

Save changes.

On the bottom of this screen you can find ClientID and Client sercret values needed for Graphileon's config.json.

3.Set the credentials in Graphileon

Start editing Graphileon's config.json.

Set up ClientID and Client secret (see 2. Setup OAuth) in Graphileon's config.json file for their appropriate configuration keys.

Set audience key as the base URI for your Okta service/portal (ex: https://dev-123456.okta.com").

Save config.json.

Example of configuration:

    "authentication": {
        "default": false,
        ...// other authentication methods (optional)
        "okta": {
            "enabled": true,
            "type":"okta",
            "createAccounts": false,
            "audience": "https://dev-123456.okta.com",
            "clientID": "<provided-by-authentication-platform>",
            "clientSecret": "<provided-by-authentication-platform>"
        }
    }

Restart Graphileon server and reload it in the browser.

If no user is logged in you should see the Sign-in with Okta button on the login screen.

Twitter

Go to https://developer.twitter.com/en/apps

1. Create a new application and setup OAuth

On the top-right click Create an App.

Enter the App name, Application description, Website URL as the Base URL of Graphileon and check Enable Sign in with Twitter.

For Callback URLs enter: http://<base-url>/api/authentication/<auth-label>/callback and https://<base-url>/api/authentication/<auth-label>/callback.

The field Tell us how this app will be used is also required.

Click Create (twice).

2. Setup Graphileon

In the tab Keys and Tokens of the Twitter's application details (at https://developer.twitter.com/en/apps) you will find the API key and API secret key that need to be copied in Graphileon's config.json.

Start editing Graphileon's config.json.

Enter clientID as the API key and clientSecret as API secret key in Graphileon's config.json file.

audience key is not used for Twitter authentication so you can delete this key

Example of configuration:

    "authentication": {
        "default": false,
        ...// other authentication methods (optional)
        "twitter": {
            "enabled": true,
            "type":"twitter",
            "createAccounts": false,
            "clientID": "<provided-by-authentication-platform>",
            "clientSecret": "<provided-by-authentication-platform>"
        }
    }

Save config.json.

Restart Graphileon server and reload it in the browser.

If no user is logged in you should see the Sign-in with Twitter button on the login screen.

Actions

An authentication method can be used by accessing the following URL: //<graphileon-url>/api/authentication/<auth-label>.

When a user IS NOT logged in it will try to find and login a Graphileon user with the Authenticator's Profile. If no user is found and createAccount is set to true in config.json a new Graphileon user is created and logged-in.

When a user IS logged in it will create a new IA_Profile node using the current Authenticator's Profile and link it to the currently logged in user inside Graphileon. This will allow the current user to login next time using this authentication method.

Profile Node

When a Graphileon user is linked to an Authenticator profile a (IA_Profile)-[:FOR]->(IA_User) pattern is created inside the Graphileon application store.

IA_User is the Graphileon user node and IA_Profile is the authentication profile node with the following structure:

	{
	  "_json": "{...}",
	  "_raw": "{...}",
	  "authentication": "<auth-label>",
	  "displayName": "John Doe",
	  "emails": [{"value": "john@email.com", "type": "<email-type>"}],
	  "id": "<authenticators-unique-id>",
	  "name": {"fullName": "John Doe", "familyName": "Doe","givenName": "John"},
	  "provider": "<auth-type>",
	  "username": "<username-for-authenticator>",
	  "photos": [{"value": "<url-of-photo>"}]
	}

Key	Description	Type
`_raw`	Contains all the raw data received as Profile from the Provider.	`object`
`_json`	Contains the `_raw` Profile data parsed into a JSON structure. Use this structure to access custom data that the Authenticator provides and is not into the default Profile structure.	`object`
`authentication`	Configured name of the authentication used (`<auth-label>`)	`string`
`displayName`	Full name of user (used for display purposes)	`string`
`emails`	List of user's emails	`array` or `object`
`id`	Unique id generated by Authenticator for this profile/user.	`integer` or `string`
`name`	Full, family and given names	`object`
`provider`	Provider type (`google`, `facebook`, `okta`, `twitter` etc.)	`string`
`username`	Unique username chosen by the user	`string`
`photos`	A list of URL's to the user's profile photos. It is omited if the user has no profile photos.	`array` or `objects`

Using Profile data in Graphileon

All the current user's authentication profiles are accessible from (@).user.profiles.

An authentication profile is accessible at (@).user.profiles.<auth-label>.

Getting started Configuration Setup third party authentication

Third party authentication

How it works

Setup

Graphileon configuration

Choose a label/name

config.json setup

Provider configuration

Google

1. Create a new project

2. Setup the OAuth consent screen

3. Create OAuth credentials

4. Set the credentials in Graphileon

Facebook

1.Create a new Facebook application

2.Set up application

3.Setup FB login

4.Set the credentials in Graphileon

5. Make the feature available to everybody else

Okta

1. Create a new application

2. Setup OAuth

3.Set the credentials in Graphileon

Twitter

1. Create a new application and setup OAuth

2. Setup Graphileon

Actions

Profile Node

Using Profile data in Graphileon

`config.json` setup