<commit_before># Passport.js Authentication

## Overview

Passport is authentication middleware for Node.js. Extremely flexible and modular, Passport can be unobtrusively dropped in to any Express-based web application. Including Passport.js in the Gluu Server will allow an admin to offer many authentication strategies to end users, including social login at large consumer IDPs like Google, Facebook, etc.

### Why Passport.js Authenticaion

- To create Node-Passport server which will provide social network authentication APIs for Gluu server.
- To create Gluu server interception scripts for authentication of users which will consume Node-Passport server api.


### Specifications

Node-Passport server authenticates users for all the social networks like: google+, facebook, twitter etc. Node-Passport uses passport authentication middleware for social network authentication. All the node js api are secured with JWT(JSON Web Token) so that all the requests to node js server are authenticated and can be trusted by the application.

Gluu server has only one interception script for all the social network providers which will call node js server for authenticating users to respective social network provider. The users will be added to Gluu server if the user does not present in the LDAP server of Gluu and if user does not exists then user will be added to server.

### Sequence Diagram

![Sequence Diagram](../img/passport/sequence_diagram.png "Title")

1. Gluu server calls Node-Passport server for JWT token.
2. Node-Passport server generates a JWT token and provides it in response to Gluu server.
3. Gluu server requests Node-Passport server with JWT token to authenticate user for a social network provider.
4. Node-Passport server will redirect user to social media authentication provider.
5. After successful authentication of user, social network will callback Node-Passport server along with user details and access token.
6. Node-Passport server will redirect user back to Gluu server with user details and access token.
7. Gluu server’s interception script will check if the user exists in LDAP server and if user exists then user will be logged into the system and if not, then it will create new user with the required details and logs user into the system.

## SETUP Passport.js with Gluu

During installation of the Gluu Server select `yes` to install Passport.js when prompted.

1. Click on Manage Custom Scripts under configuration tab on the main menu.
2. Enable passport script in Person Authentication Tab.![Enable passport1](../img/passport/enable-passport.png)
3. Click on update at the end of the page.![update](../img/passport/auth-update.png)
4. Enable uma authorization policy in uma authorization policy tab.![uma-enable](../img/passport/uma-enable.png)
5. Click on update.
6. To set the strategies from Configuration > Manage Authentication > Default Authenticaion
7. Under Default Authenticaion tab, change Authentication mode to passport
8. Change passport support to enabled.![enable-authentication](../img/passport/enable-authentication.png)
9. Once Passport support is enabled and updated, Passport Authentication Method will appear in the next tab.
10. Click on the Passport Authenticaion Method, and set the strategies as follows,The values for Strategy field for common providers are:
	- google for GPlus Authentication
	- twitter for Twitter Authentication
	- linkedin for LinkedIn Authentication
	- github for Github Authentication
	- facebook for Facebook Authentication
11. And then add the strategy details like clientID and clientSecret.
			clientID and clientSecret are details obtained from the provider, after the app is created in the provider form.![setting-strategies](../img/passport/setting-strategies.png)
12. Once the configuration and settings are done, restart the passport service or Gluu Server.
		a. Login to chroot
		b. Enter below command to stop.
		`service passport stop`
		c. Below command to start.
		`service passport start`

!!! Warning
	All the strategies name and Field name should follow the case. As these are case sensitive. ie. Google Strategy should have "google" as the strategy name and clientID should be small "c".
	
### How to create a new app to use for Passport server?

Every provider has different protocols and ways to create the app. We will look at one of the most common providers "facebook" and create a new app.

1. Login to https://developers.facebook.com
2. Click on Add a new App from My Apps dropdown
3. Fill the required details and click the create Create App ID button to create the app.
4. Click on the dashboard menu and get the clientID and clientSecret which can be used with the passport.
5. Click on settings menu and put the domain of your gluu server in the App Domains field.

Note: If there is a filed for Authorized redirect URIs, make sure the Authorized redirect URIs list of your app contains the passport strategy's callback. If your gluu server points to https://example.gluu.org and the strategy is facebook, the list of Authorized redirect URIs should contain https://example.gluu.org/passport/auth/facebook/callback.
Make sure the  Authorized redirect URIs list of your app contains the passport strategy's callback.
If your gluu server points to https://example.gluu.org and the strategy is facebook, the list of Authorized redirect URIs should contain https://example.gluu.org/passport/auth/facebook/callback.
 
## INSTALLATION

!!! note
	The node installation is already installed when passport is selected during the installation of Gluu 3.0.0 CE Server.
	
Node-Passport server requires npm and NodeJS to be installed on the system.

For installing node and npm please refer to [this guide](https://nodejs.org/en/download/package-manager/).

Clone the repository and move to server directory and hit:

`npm install`

This will install all the dependencies of the server. To start the server move to the server directory and hit

`node app`

### JWT

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with HMAC algorithm) or a public/private key pair using RSA.

JSON Web Tokens consist of three parts separated by dots (.), which are:
- Header
- Payload
- Signature

Therefore, a JWT typically looks like the following.
xxxxx.yyyyy.zzzzz

All the three parts are then Base64Url encoded to form JSON Web Token.

The output is three Base64 strings separated by dots that can be easily passed in HTML and HTTP environments, while being more compact compared to XML-based standards such as SAML.

The following shows a JWT that has the previous header and payload encoded, and it is signed with a secret.

If you want to play with JWT and put these concepts to practice, you can use jwt.io Debugger to decode, verify and generate JWTs.


### Example of encoded and decoded JWT

![JWT](../img/passport/jwt.png "Title")

Whenever the user wants to access a protected route or resource, it should send the JWT, here in our case in route url. Therefore the route or api call should look like the following.

https://urltorouteorresource/JWT

This is a stateless authentication mechanism as the user state is never saved in the server memory. The server's protected routes will check for a valid JWT in the API parameter, and if there is a valid token, the user will be allowed.


### What data will be persist?

All the data that are received from the social network like name, email etc will be stored. If all the required details for creating a user are not available from the social network then user will be asked to enter all the required details. Currently email is the only required field.


### How Node-Passport server will fit in Gluu server?
<commit_msg>fixed images<commit_after># Passport.js Authentication

## Overview

Passport is authentication middleware for Node.js. Extremely flexible and modular, Passport can be unobtrusively dropped in to any Express-based web application. Including Passport.js in the Gluu Server will allow an admin to offer many authentication strategies to end users, including social login at large consumer IDPs like Google, Facebook, etc.

### Why Passport.js Authenticaion

- To create Node-Passport server which will provide social network authentication APIs for Gluu server.
- To create Gluu server interception scripts for authentication of users which will consume Node-Passport server api.


### Specifications

Node-Passport server authenticates users for all the social networks like: google+, facebook, twitter etc. Node-Passport uses passport authentication middleware for social network authentication. All the node js api are secured with JWT(JSON Web Token) so that all the requests to node js server are authenticated and can be trusted by the application.

Gluu server has only one interception script for all the social network providers which will call node js server for authenticating users to respective social network provider. The users will be added to Gluu server if the user does not present in the LDAP server of Gluu and if user does not exists then user will be added to server.

### Sequence Diagram

![Sequence Diagram](/img/passport/sequence_diagram.png "Title")

1. Gluu server calls Node-Passport server for JWT token.
2. Node-Passport server generates a JWT token and provides it in response to Gluu server.
3. Gluu server requests Node-Passport server with JWT token to authenticate user for a social network provider.
4. Node-Passport server will redirect user to social media authentication provider.
5. After successful authentication of user, social network will callback Node-Passport server along with user details and access token.
6. Node-Passport server will redirect user back to Gluu server with user details and access token.
7. Gluu server’s interception script will check if the user exists in LDAP server and if user exists then user will be logged into the system and if not, then it will create new user with the required details and logs user into the system.

## SETUP Passport.js with Gluu

During installation of the Gluu Server select `yes` to install Passport.js when prompted.

1. Click on Manage Custom Scripts under configuration tab on the main menu.
2. Enable passport script in Person Authentication Tab.![Enable passport1](/img/passport/enable-passport.png)
3. Click on update at the end of the page.![update](/img/passport/auth-update.png)
4. Enable uma authorization policy in uma authorization policy tab.![uma-enable](/img/passport/uma-enable.png)
5. Click on update.
6. To set the strategies from Configuration > Manage Authentication > Default Authenticaion
7. Under Default Authenticaion tab, change Authentication mode to passport
8. Change passport support to enabled.![enable-authentication](/img/passport/enable-authentication.png)
9. Once Passport support is enabled and updated, Passport Authentication Method will appear in the next tab.
10. Click on the Passport Authenticaion Method, and set the strategies as follows,The values for Strategy field for common providers are:
	- google for GPlus Authentication
	- twitter for Twitter Authentication
	- linkedin for LinkedIn Authentication
	- github for Github Authentication
	- facebook for Facebook Authentication
11. And then add the strategy details like clientID and clientSecret.
			clientID and clientSecret are details obtained from the provider, after the app is created in the provider form.![setting-strategies](/img/passport/setting-strategies.png)
12. Once the configuration and settings are done, restart the passport service or Gluu Server.
		a. Login to chroot
		b. Enter below command to stop.
		`service passport stop`
		c. Below command to start.
		`service passport start`

!!! Warning
	All the strategies name and Field name should follow the case. As these are case sensitive. ie. Google Strategy should have "google" as the strategy name and clientID should be small "c".
	
### How to create a new app to use for Passport server?

Every provider has different protocols and ways to create the app. We will look at one of the most common providers "facebook" and create a new app.

1. Login to https://developers.facebook.com
2. Click on Add a new App from My Apps dropdown
3. Fill the required details and click the create Create App ID button to create the app.
4. Click on the dashboard menu and get the clientID and clientSecret which can be used with the passport.
5. Click on settings menu and put the domain of your gluu server in the App Domains field.

Note: If there is a filed for Authorized redirect URIs, make sure the Authorized redirect URIs list of your app contains the passport strategy's callback. If your gluu server points to https://example.gluu.org and the strategy is facebook, the list of Authorized redirect URIs should contain https://example.gluu.org/passport/auth/facebook/callback.
Make sure the  Authorized redirect URIs list of your app contains the passport strategy's callback.
If your gluu server points to https://example.gluu.org and the strategy is facebook, the list of Authorized redirect URIs should contain https://example.gluu.org/passport/auth/facebook/callback.
 
## INSTALLATION

!!! note
	The node installation is already installed when passport is selected during the installation of Gluu 3.0.0 CE Server.
	
Node-Passport server requires npm and NodeJS to be installed on the system.

For installing node and npm please refer to [this guide](https://nodejs.org/en/download/package-manager/).

Clone the repository and move to server directory and hit:

`npm install`

This will install all the dependencies of the server. To start the server move to the server directory and hit

`node app`

### JWT

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with HMAC algorithm) or a public/private key pair using RSA.

JSON Web Tokens consist of three parts separated by dots (.), which are:
- Header
- Payload
- Signature

Therefore, a JWT typically looks like the following.
xxxxx.yyyyy.zzzzz

All the three parts are then Base64Url encoded to form JSON Web Token.

The output is three Base64 strings separated by dots that can be easily passed in HTML and HTTP environments, while being more compact compared to XML-based standards such as SAML.

The following shows a JWT that has the previous header and payload encoded, and it is signed with a secret.

If you want to play with JWT and put these concepts to practice, you can use jwt.io Debugger to decode, verify and generate JWTs.


### Example of encoded and decoded JWT

![JWT](/img/passport/jwt.png "Title")

Whenever the user wants to access a protected route or resource, it should send the JWT, here in our case in route url. Therefore the route or api call should look like the following.

https://urltorouteorresource/JWT

This is a stateless authentication mechanism as the user state is never saved in the server memory. The server's protected routes will check for a valid JWT in the API parameter, and if there is a valid token, the user will be allowed.


### What data will be persist?

All the data that are received from the social network like name, email etc will be stored. If all the required details for creating a user are not available from the social network then user will be asked to enter all the required details. Currently email is the only required field.


### How Node-Passport server will fit in Gluu server?

{'fraction_non_alphanumeric': 0.04650281165097618, 'fraction_numerical': 0.00492828710431541, 'mean_word_length': 4.376358695652174, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 7, 'https://': 14, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5636586', 'n_tokens_mistral': 3968, 'n_tokens_neox': 3795, 'n_words': 2333}