Skip to content

Commit

Permalink
Merge pull request #35 from sammyskills/make-oauth
Browse files Browse the repository at this point in the history 
Dev: Make command to create new OAuth
  • Loading branch information
@datamweb
datamweb authored Apr 18, 2023
2 parents 01de7b1 + e8804a8 commit 8b82c5b
Show file tree
Hide file tree
Showing 4 changed files with 536 additions and 51 deletions.
237 changes: 186 additions & 51 deletions docs/add_other_oauth.md
View file
Original file line number Diff line number Diff line change
@@ -1,35 +1,202 @@
# Add New OAuth To Shield OAuth
# Adding New OAuth To Shield OAuth

As you know, `Shield OAuth` supports `Google OAuth` and `Github OAuth` by default. But you can connect any server that offers `OAuth` to it.
It is very simple, first, create a file named `NewOAuth` in path `app\Libraries\ShieldOAuth`. Existence of extension `OAuth` is mandatory in creating each new class. For example, if you want to add Yahoo, you should create a file named `YahooOAuth` in path `app\Libraries\ShieldOAuth`.
Shield OAuth supports *Google OAuth* and *Github OAuth* out-of-the-box and also provides an easy way to connect any server that offers **OAuth** to it. This guide explains how to achieve this.

Implement methods `makeGoLink($state)`, `fetchAccessTokenWithAuthCode($allGet)`, `fetchUserInfoWithToken()` and `setColumnsName(string $nameOfProcess, $userInfo)` according to the documents of each server.
- [Adding New OAuth to Shield OAuth](#adding-new-oauth-to-shield-oauth)
- [Setup Instruction](#setup-instruction)
- [Command Setup](#command-setup)
- [Manual Setup](#manual-setup)

`NewOAuth` have only one requirement: they must extends `Datamweb\ShieldOAuth\Libraries\Basic\AbstractOAuth`.
## Setup Instruction

The `AbstractOAuth` defines four methods for `NewOAuth`:
### Command Setup

1. `makeGoLink($state)` In this method, you need to create a link to transfer the user to the new provider. The output of this method is a `string` in the form of URL. For example, regarding Yahoo, you can follow the instructions available [here](https://developer.yahoo.com/oauth2/guide/flows_authcode/#step-2-get-an-authorization-url-and-authorize-access) to create this link.

2. `fetchAccessTokenWithAuthCode($allGet)` In this method, you should try to get the value of `access_token` according to the code received from the previous method. The output of this method is of `void`. For Yahoo, you can see the description [here](https://developer.yahoo.com/oauth2/guide/flows_authcode/#step-4-exchange-authorization-code-for-access-token). Everything is ready, just replace.
1. Run the following command. This command handles steps 1 - 3 of *Manual Setup*.

3. `fetchUserInfoWithToken()` In this method, you try to receive user information (including first name, last name, email, etc) according to the token code set in the previous step.The output of this method is a `object` of user info(email, name, ...). See [here](https://developer.yahoo.com/oauth2/guide/OpenID2) for more details about Yahoo.
```console
php spark make:oauth Example
```

4. `setColumnsName(string $nameOfProcess, $userInfo)` In this method, you set the fields received from each service OAuth to be recorded in each column of the table.
> **Note** The name of the new OAuth you want to create doesn't need to contain the `OAuth` suffix. The command will automatically add it to the class name for you.
This command will automatically generate new files *ExampleOAuth.php*, *ShieldOAuthLang.php* in the **app/Libraries/ShieldOAuth**, **app/Language/en** paths respectively and also update the *ShieldOAuthConfig.php* file in the **app/Config** path.

> **Note** The *ShieldOAuthConfig.php* file must be present in your **app/Config** path for this command to run successfully. So ensure that you have run the `make:oauthconfig` command first, as stated [here](install.md#set-keys).
2. Configure the files.

```php
// updated file - app/Config/ShieldOAuthConfig.php
<?php
public array $oauthConfigs = [
// ..
'example' => [
'client_id' => 'Get this from the OAuth server',
'client_secret' => 'Get this from the OAuth server',

'allow_login' => true
],
];

```

```php
// new file - app/Libraries/ShieldOAuth/ExampleOAuth.php
<?php

declare(strict_types=1);

namespace App\Libraries\ShieldOAuth;

use Datamweb\ShieldOAuth\Libraries\Basic\AbstractOAuth;

class ExampleOAuth extends AbstractOAuth
{
private static $API_CODE_URL = '';
private static $API_TOKEN_URL = '';
private static $API_USER_INFO_URL = '';
private static $APPLICATION_NAME = 'ShieldOAuth';

protected string $token;
protected string $client_id;
protected string $client_secret;
protected string $callback_url;

public function __construct(string $token = '')
{
// your code here
}

public function makeGoLink(string $state): string
{
// your code here
return '';
}

public function fetchAccessTokenWithAuthCode(array $allGet): void
{
// your code here
}

I have given an example for Yahoo below:
public function fetchUserInfoWithToken(): object
{
// your code here
return json_decode('');
}

- [Writing Class Yahoo OAuth](#writing-class-yahoo-oauth)
- [Add Keys To Config File](#add-keys-to-config-file)
- [Add lang file](#add-lang-file)
public function setColumnsName(string $nameOfProcess, object $userInfo): array
{
// your code here
return [];
}
}
```

> See [YahooOAuth](#yahoooauth-example-class) example for full code.
## Writing Class Yahoo OAuth
### Manual Setup

Create a file in path `app\Libraries\ShieldOAuth\YahooOAuth.php` with the following contents.
1. Create a file *ExampleOAuth* in the **app/Libraries/ShieldOAuth** path with the following contents. The **OAuth** suffix is mandatory in creating each new class. For example, if you want to add Yahoo, you should create a file named **YahooOAuth**.

```php
<?php

declare(strict_types=1);

namespace App\Libraries\ShieldOAuth;

use Datamweb\ShieldOAuth\Libraries\Basic\AbstractOAuth;

class ExampleOAuth extends AbstractOAuth
{
private static $API_CODE_URL = '';
private static $API_TOKEN_URL = '';
private static $API_USER_INFO_URL = '';
private static $APPLICATION_NAME = 'ShieldOAuth';

protected string $token;
protected string $client_id;
protected string $client_secret;
protected string $callback_url;

public function __construct(string $token = '')
{
// your code here
}

public function makeGoLink(string $state): string
{
// your code here
return '';
}

public function fetchAccessTokenWithAuthCode(array $allGet): void
{
// your code here
}

public function fetchUserInfoWithToken(): object
{
// your code here
return json_decode('');
}

public function setColumnsName(string $nameOfProcess, object $userInfo): array
{
// your code here
return [];
}
}
```

> See [YahooOAuth](#yahoooauth-example-class) example for full code.
2. **Config Setup** Add the new OAuth config keys to the **app/Config/ShieldOAuthConfig.php** file.

```php
<?php
public array $oauthConfigs = [
//...
'example' => [
'client_id' => 'Get this from the OAuth server',
'client_secret' => 'Get this from the OAuth server',

'allow_login' => true
],
//...
];

```

3. **Language setup** Add the following values to the **app/Language/en/ShieldOAuthLang.php** file. Create the file if it doesn't exist.

```php
return [
// ...
'Example' => [
'not_allow' => 'Now you can\'t login or register with Example!',
'example' => 'Example',
],
// ...
];
```

4. **Translations** Depending on the requirements of your application, you can translate the language file using the same keys, in as many languages as possible. See [CodeIgniter docs](https://codeigniter.com/user_guide/outgoing/localization.html#creating-language-files) for more information. Also note that the file name for each language must be **ShieldOAuthLang.php**.

## Available Methods

Your new *OAuth* file/class has just one requirement. It must extend `Datamweb\ShieldOAuth\Libraries\Basic\AbstractOAuth`. The abstract class `AbstractOAuth` implement methods `makeGoLink($state)`, `fetchAccessTokenWithAuthCode($allGet)`, `fetchUserInfoWithToken()` and `setColumnsName(string $nameOfProcess, $userInfo)`, which should be built according to the documentation of each server.

The `AbstractOAuth` defines four methods for your usage:

1. `makeGoLink($state)` In this method, you need to create a link to transfer the user to the new provider. The output of this method is a `string` in the form of URL. For example, regarding Yahoo, you can follow the instructions available [here](https://developer.yahoo.com/oauth2/guide/flows_authcode/#step-2-get-an-authorization-url-and-authorize-access) to create this link.
2. `fetchAccessTokenWithAuthCode($allGet)` In this method, you should try to get the value of `access_token` according to the code received from the previous method. The output of this method is of `void`. For Yahoo, you can see the description [here](https://developer.yahoo.com/oauth2/guide/flows_authcode/#step-4-exchange-authorization-code-for-access-token). Everything is ready, just replace.
3. `fetchUserInfoWithToken()` In this method, you try to receive user information (including first name, last name, email, etc) according to the token code set in the previous step.The output of this method is a `object` of user info(email, name, ...). See [here](https://developer.yahoo.com/oauth2/guide/OpenID2) for more details about Yahoo.
4. `setColumnsName(string $nameOfProcess, $userInfo)` In this method, you set the fields received from each service OAuth to be recorded in each column of the table.

## YahooOAuth Example Class

```php
<?php

declare(strict_types=1);
Expand Down Expand Up @@ -88,15 +255,15 @@ class YahooOAuth extends AbstractOAuth
],
'http_errors' => false,
]);

} catch (Exception $e) {
die($e->getMessage());
}

$token = json_decode($response->getBody())->access_token;
$this->setToken($token);
}

protected function fetchUserInfoWithToken(): object
{
// send request to API URL
Expand Down Expand Up @@ -138,37 +305,5 @@ class YahooOAuth extends AbstractOAuth

return $usersColumnsName;
}

}

```

## Add Keys To Config File
For each new OAuth service you create, you must add the following values in file `Config\ShieldOAuthConfig.php`. For Yahoo, it is as follows.

```php
public array $oauthConfigs = [
//...
'yahoo' => [
'client_id' => 'from yahoo ...',
'client_secret' => 'from yahoo ...',

'allow_login' => true
],
//...
];
```

## Add lang file
For each new OAuth service you create, you must add the following values in file `Language\en\ShieldOAuthLang.php` and `Language\fa\ShieldOAuthLang.php`. For Yahoo, it is as follows.

```php
return [
// ...
'Yahoo' => [
'not_allow' => 'Now you can\'t login or register with Yahoo!',
'yahoo' => 'Yahoo',
],
// ...
];
```
Loading

0 comments on commit 8b82c5b

Please sign in to comment.