Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve repo documentation #312

Merged
merged 7 commits into from
Jan 31, 2019
Merged

Improve repo documentation #312

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ca73e03
Remove examples, create CONTRIBUTING, add TOC to readme
joshcanhelp Jan 4, 2019
237b3d7
Final missing pieces in README; move troubleshooting to docs page
joshcanhelp Jan 4, 2019
d0bf011
move state validation note to docs; added missing PR for state valida…
joshcanhelp Jan 4, 2019
c393308
Move all examples to docs site
joshcanhelp Jan 4, 2019
dc66bfd
Merge branch 'master' into improve-repo-documentation
joshcanhelp Jan 30, 2019
ecf94bd
PR feedback
joshcanhelp Jan 31, 2019
6aa2e08
PR feedback
joshcanhelp Jan 31, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 3 additions & 4 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,16 +104,15 @@
## [5.1.0](https://github.com/auth0/auth0-PHP/tree/5.1.0) (2018-03-02)
[Full Changelog](https://github.com/auth0/auth0-PHP/compare/5.0.6...5.1.0)

[State validation](https://auth0.com/docs/protocols/oauth2/oauth-state) was added in 5.1.0 for improved security. By default, this uses session storage and will happen automatically if you are using a combination of `Auth0::login()` and any method which calls `Auth0::exchange()` in your callback.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moved to the Troubleshooting section of the SDK docs

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd keep a small mention of it. Normally when people find an error the first thing is go check what changed (on the changelog). You could link the troubleshooting section in here as well.

**Notes on this release:**

If you need to use a different storage method, implement your own [StateHandler](https://github.com/auth0/auth0-PHP/blob/master/src/API/Helpers/State/StateHandler.php) and set it using the `state_handler` config key when you initialize an `Auth0` instance.

If you are using `Auth0::exchange()` and a method other than `Auth0::login()` to generate the Authorize URL, you can disable automatic state validation by setting the `state_handler` key to `false` when you initialize the `Auth0` instance. It is **highly recommended** to implement state validation, either automatically or otherwise
[State validation](https://auth0.com/docs/protocols/oauth2/oauth-state) was added for improved security. Please see our [troubleshooting page](https://auth0.com/docs/libraries/auth0-php/troubleshooting) for more information on how this works and potential issues.

**Closed issues**
- Support for php-jwt 5 [\#210](https://github.com/auth0/auth0-PHP/issues/210)

**Added**
- Added XSRF State Storage / Validation [\#214](https://github.com/auth0/auth0-PHP/pull/214) ([cocojoe](https://github.com/cocojoe))
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing the main PR here ... no label previously

- Adding tests for state handler; correcting storage method used [\#228](https://github.com/auth0/auth0-PHP/pull/228) ([joshcanhelp](https://github.com/joshcanhelp))

**Changed**
Expand Down
24 changes: 24 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
## Contributing

We provide and maintain SDKs for the benefit of our developer community. Feedback, detailed bug reports, and focused PRs are appreciated. Thank you in advance!

When contributing to this SDK, please:

- Maintain the minimum PHP version (found under `require.php` in `composer.json`).
- Code to the [PSR-2 standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md).
- Write tests and run them with `composer test`.
- Keep PRs focused and change the minimum number of lines to achieve your goal.

To run tests on the SDK, you'll need to create a `.env` file in the root of this package with the following entries:

- `DOMAIN` - Auth0 domain for your test tenant
- `APP_CLIENT_ID` - Client ID for a Regular Web Application within your test tenant
- `APP_CLIENT_SECRET` - Client Secret for a Regular Web Application within your test tenant
- `NIC_ID` - Client ID for a test Non-Interactive Client Application
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A note in case of a future refactor. Since you're using the "CLIENT" word for other constants, might as well use it here and be more descriptive. In the end these are just names one should easily see and remember. e.g. NON_INTERACTIVE_CLIENT_ID

- `NIC_SECRET` - Client Secret for a test Non-Interactive Client Application
- `GLOBAL_CLIENT_ID` - Client ID for your tenant (found in Tenant > Settings > Advanced)
- `GLOBAL_CLIENT_SECRET` - Client Secret for your tenant (found in Tenant > Settings > Advanced)

This file is automatically excluded from Git with the `.gitignore` for this repo.

We're working on test coverage and quality but please note that newer tenants might see errors (typically `404`) for endpoints that are no longer available. Another common error is a `429` for too many requests.
Loading