README

This a IP Access redirect package for IPv4 & IPv6. The purpose is to allow or deny access to the Laravel routes by IP address. It is able to allow certain IPs (IPv4 or IPv6) to access default files or envirioments, and redirect non-authorized IPs or Users to an external URL, while letting whitelisted IPs to have access to the entire site or to a special Envirionment.

Requirements

• PHP ^8.0
• Laravel 8.x – 13.x (illuminate/contracts)
• Laravel Nova ^4.0|^5.0 (optional — only required when using the Nova IP management feature)

Installation

You can install the package via composer:

composer require marshmallow/ip-access

And publish the service provider (and config):

php artisan vendor:publish --provider="Marshmallow\IpAccess\IpAccessServiceProvider"

This is the contents of the published config file:

return [

    // ENABLE IP ACCESS
    'enabled' => env('IPACCESS_ENABLED', true),

    // ENV TO CHECK IP ADDRESS FOR
    'whitelist_env' => env('IPACCESS_ENV', 'production'),

    // WHITELIST IPs GET ACCESS TO ENV
    'whitelist' => [
        'range' => [
            '127.0.0.*',
        ],
        'list' => [
            '127.0.0.1',
        ]
    ],

    // ROUTES THAT BYPASS THE IP CHECK (see "Disable lock for routes and webhooks")
    'except' => [
        //
    ],

    // ACCESS DENIED RESPONSE SETTINGS
    'redirect_to'      => env('IPACCESS_DENIED_URL', null),
    'response_status'  => env('IPACCESS_DENIED_STATUS', 403),
    'response_message' => env('IPACCESS_DENIED_MESSAGE', 'Access not Allowed'),

    // ACCESS PATH FOR LOGGING (reports denied requests to Sentry when bound)
    'access_path_enabled'  => env('IPACCESS_PATH_ENABLED', false),
    'access_path' => env('IPACCESS_PATH', '/ip-access'),

    // KEEP TRACK OF THE IP ADDRESSES USING NOVA
    'use_nova' => true,
];

Optional

These are the optional .env variables to set up:

    # ENABLED
    IPACCESS_ENABLED=true

    # ENV THAT IS CHECKED BY IP e.g. staging
    IPACCESS_ENV=production

    # ADDIOTNAL IP LIST
    IPACCESS_WHITELIST="127.0.0.1,123.456.789.12"   # SEPERATED BY ,

    # URL TO REDIRECT TO:
    IPACCESS_DENIED_URL="https://marshmallow.dev"

    # IF URL NOT SET
    IPACCESS_DENIED_STATUS=403                      # REDIRECT STATUS
    IPACCESS_DENIED_MESSAGE="Not allowed"           # REDIRECT STATUS MESSAGE

Disable lock for routes and webhooks

If you are testing webhooks on an ip locked envoirment you need to open up your application so the webhooks won't be blocked. You can do this by adding values in the config array except. Below you will find a few examples.

Just open up a route

Add a url to the array to just open it up. If this route is matched, the package will just let the request through.

'except' => [
    'webhook/*',
],

Open up with a secret

If you want to open up the route but want to require the request to have a secret, you can do so by adding some settings to the except array.

Via headers

'except' => [
    'webhook/*' => [
        'secret' => [
            'source' => 'header',
            'key' => 'x-webhook-secret',
            'value' => 'TEST_SECRET_HEADER',
        ],
    ],
],

/** This request will be allowed by the config above. */
Http::withHeaders([
  "x-webhook-secret" => "TEST_SECRET_HEADER"
])->get("https://marshmallow.dev/webhook/is/open");

Via body/query string

'except' => [
    'webhook/*' => [
        'secret' => [
            'source' => 'body',
            'key' => 'secret',
            'value' => 'TEST_SECRET_BODY',
        ],
    ],
],

/** These requests will be allowed by the config above. */
Http::get("https://marshmallow.dev/webhook/is/open?secret=TEST_SECRET_BODY");
Http::get("https://marshmallow.dev/webhook/is/open", [
  "secret" => "TEST_SECRET_BODY"
]);
Http::post("https://marshmallow.dev/webhook/is/open", [
  "secret" => "TEST_SECRET_BODY"
]);

Usage with Laravel Nova

If you want to keep track of the ip addresses that have access using Laravel Nova you need to follow the following steps.

To add an check for IP access in Nova, add the following to NovaServiceProvider:

Gate::define('viewNova', function ($user) {
    return IpAccess::hasBackofficeAccess();
}

Update your config file

Set use_nova to true in config/ip-access.php.

return [
    'use_nova' => true,
];

Run migrations

You need to run the migrations after you've update the config file so we have the tables we need to store the ip addresse.

php artisan migrate

Publish the Nova resource

The last step is publishing the Nova resource so you can manage all ip address in your Laravel Nova installation.

php artisan marshmallow:resource IpAccess IpAccess

Uninstall

Once your application is done and you are going to publish your application to production for the whole world to see, you can delete this package. You don't need it anymore and its always good practice to keep your code clean. Run the command below to uninstall this package. This command will delete the config file. Delete the nova resource, delete the migration record, delete the ip_accesss database table and remove the package from your composer file. You will have to review and commit the changes in you GIT repository yourself.

php artisan ip-access:uninstall

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• LTKort
• Stef van Esch
• All Contributors

License

The MIT License (MIT). Please see License File for more information.