Skip to content

Commit 078dce3

Browse files
joshcanhelpjoshcanhelp
committed
Add GH tpls; update README to new format; add CONTRIBUTING; add rubocop to dev env
1 parent 50f73e5 commit 078dce3

File tree

5 files changed

+236
-85
lines changed

5 files changed

+236
-85
lines changed

‎.github/ISSUE_TEMPLATE.md

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
In order to efficiently and accurately address your issue or feature request, please read through the template below and answer all relevant questions. Your additional work here is greatly appreciated and will help us respond as quickly as possible. Please delete any sections or questions below that do not pertain to this request.
2+
3+
For general support or usage questions, please use the [Auth0 Community](https://community.auth0.com/) or [Auth0 Support](https://support.auth0.com.).
4+
5+
### Description
6+
7+
Description of the bug or feature request and why it's a problem. Consider including:
8+
9+
- The use case or overall problem you're trying to solve
10+
- Information about when the problem started
11+
12+
### Prerequisites
13+
14+
* [ ] I have read the [Auth0 contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
15+
* [ ] I have read the [Auth0 Code of Conduct](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
16+
* [ ] Did you check the [documentation](https://auth0.com/docs/quickstart/webapp/rails)?
17+
* [ ] Did you check [Auth0 Community](https://community.auth0.com/tags/rails)?
18+
* [ ] Are you reporting this to the correct repository? This strategy relies on [OmniAuth](https://github.com/omniauth/omniauth) and the [OmniAuth OAuth2](https://github.com/omniauth/omniauth-oauth2) strategy.
19+
* [ ] Are there any related or duplicate [Issues](https://github.com/auth0/omniauth-auth0/issues) or [PRs](https://github.com/auth0/omniauth-auth0/pulls) for this issue?
20+
21+
### Environment
22+
23+
Please provide the following:
24+
25+
* OmniAuth-Auth0 version:
26+
* Ruby version:
27+
* Rails veresion:
28+
* Browser version, if applicable:
29+
* Additional gems that might be affecting your instance:
30+
31+
### Reproduction
32+
33+
Detail the steps taken to reproduce this error and note if this issue can be reproduced consistently or if it is intermittent.
34+
35+
Please include:
36+
37+
- Log files (redact/remove sensitive information)
38+
- Application settings (redact/remove sensitive information)
39+
- Screenshots, if helpful

‎.github/PULL_REQUEST_TEMPLATE.md

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
### Changes
2+
3+
Please describe both what is changing and why this is important. Include:
4+
5+
- Endpoints added, deleted, deprecated, or changed
6+
- Classes and methods added, deleted, deprecated, or changed
7+
- Screenshots of new or changed UI, if applicable
8+
- A summary of usage if this is a new feature or change to a public API (this should also be added to relevant documentation once released)
9+
10+
### References
11+
12+
Please include relevant links supporting this change such as a:
13+
14+
- support ticket
15+
- community post
16+
- StackOverflow post
17+
- support forum thread
18+
- related GitHub issue in this or another repo
19+
20+
### Testing
21+
22+
Please describe how this can be tested by reviewers. Be specific about anything not tested and reasons why. If this library has unit and/or integration testing, tests should be added for new functionality and existing tests should complete without errors.
23+
24+
* [ ] This change adds unit test coverage
25+
* [ ] This change has been tested on the latest version of the platform/language or why not
26+
27+
### Checklist
28+
29+
* [ ] I have read the [Auth0 contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
30+
* [ ] I have read the [Auth0 Code of Conduct](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
31+
* [ ] All existing and new tests complete without errors
32+
* [ ] All code quality tools/guidelines in the [CONTRIBUTING documentation](CONTRIBUTING.md) have been run/followed

‎CONTRIBUTING.md

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Contribution
2+
3+
**Thank you in advance for your contribution!**
4+
5+
Please read [Auth0's contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md) before beginning work on your contribution here.
6+
7+
## Environment setup
8+
9+
The best way we've found to develop gems locally is by using a local setting for your Bundler config. First, checkout the project locally:
10+
11+
```bash
12+
$ pwd
13+
/PROJECT_ROOT/
14+
$ mkdir vendor # if one does not exist
15+
$ echo "/vendor/" >> .gitignore
16+
$ git clone [email protected]:auth0/omniauth-auth0.git vendor/omniauth-auth0
17+
Cloning into 'vendor/omniauth-auth0'...
18+
```
19+
20+
Now, run the following command in your project root directory:
21+
22+
```bash
23+
$ bundle config --local local.omniauth-auth0 /PROJECT_ROOT/vendor/omniauth-auth0
24+
You are replacing the current local value of local.omniauth-auth0, which is currently nil
25+
$ bundle config
26+
Settings are listed in order of priority. The top value will be used.
27+
local.omniauth-auth0
28+
Set for your local app (/PROJECT_ROOT/.bundle/config): "/PROJECT_ROOT/vendor/omniauth-auth0"
29+
```
30+
31+
Finally, add or change the gem include to add a `github:` param:
32+
33+
```ruby
34+
source 'https://rubygems.org'
35+
# ...
36+
# OmniAuth strategy for authenticating with Auth0
37+
gem 'omniauth-auth0', github: 'auth0/omniauth-auth0'
38+
#..
39+
```
40+
41+
Now you should be able to make changes locally and have them reflected in your test app. Keep in mind you'll need to restart your app between changes.
42+
43+
[Great explanation for why this setup works well](https://rossta.net/blog/how-to-specify-local-ruby-gems-in-your-gemfile.html).
44+
45+
## Testing
46+
47+
Tests should be added for additional or modified functionality and all tests should run successfully before submitting a PR.
48+
49+
### Adding tests
50+
51+
All new tests should be added to the `/spec/omniauth` directory. Testing resources, like JSON fixtures, should be added to the `/spec/resources` directory.
52+
53+
### Running tests
54+
55+
Running tests is as simple as:
56+
57+
```bash
58+
$ bundle exec rake spec
59+
```
60+
61+
## Documentation
62+
63+
Documentation for this gem is primarily done at the code level. All new methods should include a docblock at least.
64+
65+
## Code quality tools
66+
67+
Code quality is enforced across the entire gem with Rubocop:
68+
69+
```bash
70+
$ bundle exec rake rubocop
71+
```

‎Gemfile

+1-3
Original file line numberDiff line numberDiff line change
@@ -12,16 +12,14 @@ group :development do
1212
gem 'shotgun'
1313
gem 'sinatra'
1414
gem 'thin'
15+
gem 'rubocop', require: false
1516
end
1617

1718
group :test do
1819
gem 'guard-rspec', require: false
1920
gem 'listen', '~> 3.1.5'
2021
gem 'rack-test'
2122
gem 'rspec', '~> 3.5'
22-
gem 'rubocop', '>= 0.30', platforms: %i[
23-
ruby_19 ruby_20 ruby_21 ruby_22
24-
]
2523
gem 'simplecov'
2624
gem 'webmock'
2725
end

‎README.md

+93-82
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,57 @@
1-
[![Build Status](https://travis-ci.org/auth0/omniauth-auth0.svg)](https://travis-ci.org/auth0/omniauth-auth0)
2-
31
# OmniAuth Auth0
42

5-
This is the official [OmniAuth](https://github.com/intridea/omniauth) strategy for authenticating to [Auth0](https://auth0.com).
3+
An [OmniAuth](https://github.com/intridea/omniauth) strategy for authenticating with [Auth0](https://auth0.com). This strategy is based on the [OmniAuth OAuth2](https://github.com/omniauth/omniauth-oauth2) strategy.
64

7-
## Installing
5+
[![Build Status](https://travis-ci.org/auth0/omniauth-auth0.svg)](https://travis-ci.org/auth0/omniauth-auth0)
6+
[![Gem Version](https://badge.fury.io/rb/auth0.svg)](http://badge.fury.io/rb/auth0)
7+
[![MIT licensed](https://img.shields.io/dub/l/vibe-d.svg?style=flat)](https://github.com/auth0/ruby-auth0/blob/master/LICENSE)
88

9-
Add to your `Gemfile`:
9+
## Table of Contents
1010

11-
```ruby
12-
gem 'omniauth-auth0'
13-
```
11+
- [Documentation](#documentation)
12+
- [Installation](#installation)
13+
- [Getting Started](#getting-started)
14+
- [Contribution](#contribution)
15+
- [Support + Feedback](#support--feedback)
16+
- [Vulnerability Reporting](#vulnerability-reporting)
17+
- [What is Auth0](#what-is-auth0)
18+
- [License](#license)
19+
20+
## Documentation
1421

15-
Then `bundle install`.
22+
- [Ruby on Rails Quickstart](https://auth0.com/docs/quickstart/webapp/rails)
23+
- [Sample projects](https://github.com/auth0-samples/auth0-rubyonrails-sample)
1624

17-
## Usage
25+
## Installation
1826

19-
### Rails
27+
Add the following line to your `Gemfile`:
2028

2129
```ruby
22-
Rails.application.config.middleware.use OmniAuth::Builder do
23-
provider :auth0, ENV['AUTH0_CLIENT_ID'], ENV['AUTH0_CLIENT_SECRET'], ENV['AUTH0_DOMAIN']
24-
end
30+
gem 'omniauth-auth0'
2531
```
2632

27-
Then to redirect to your tenant's hosted login page:
33+
Then install:
2834

29-
```ruby
30-
redirect_to '/auth/auth0'
35+
```bash
36+
$ bundle install
3137
```
3238

33-
### Sinatra
39+
See our [contributing guide](CONTRIBUTING.md) for information on local installation for development.
3440

35-
```ruby
36-
use OmniAuth::Builder do
37-
provider :auth0, ENV['AUTH0_CLIENT_ID'], ENV['AUTH0_CLIENT_SECRET'], ENV['AUTH0_DOMAIN']
38-
end
39-
```
41+
## Getting Started
4042

41-
Then to redirect to your tenant's hosted login page:
43+
To start processing authentication requests, the following steps must be performed:
4244

43-
```ruby
44-
redirect to('/auth/auth0')
45-
```
45+
1. Initialize the strategy
46+
2. Configure the callback controller
47+
3. Add the required routes
48+
4. Trigger an authentication request
4649

47-
> You can customize your hosted login page in your [Auth0 Dashboard](https://manage.auth0.com/#/login_page)
50+
All of these tasks and more are covered in our [Ruby on Rails Quickstart](https://auth0.com/docs/quickstart/webapp/rails).
4851

49-
### Auth parameters
52+
### Additional authentication parameters
5053

51-
To send additional parameters during login you can specify them when you register the provider
54+
To send additional parameters during login, you can specify them when you register the provider:
5255

5356
```ruby
5457
provider
@@ -64,81 +67,89 @@ provider
6467
}
6568
```
6669

67-
that will tell it to send those parameters on every Auth request.
70+
... which will tell the strategy to send those parameters on every Auth request.
6871

69-
Or you can do it for a specific Auth request by adding them in the query parameter of the redirect URL. Allowed parameters are `connection` and `prompt`:
72+
Or you can do it for a specific authentication request by adding them to the query parameters of the redirect URL. Allowed parameters are `connection` and `prompt`:
7073

7174
```ruby
7275
redirect_to '/auth/auth0?connection=google-oauth2'
7376
redirect_to '/auth/auth0?prompt=none'
7477
```
7578

76-
### Auth Hash
79+
### Authentication hash
7780

78-
Auth0 strategy will have the standard OmniAuth hash attributes:
81+
The Auth0 strategy will provide the standard OmniAuth hash attributes:
7982

80-
- provider: the name of the strategy, in this case `auth0`
81-
- uid: the user identifier
82-
- info: the result of the call to /userinfo using OmniAuth standard attributes
83-
- credentials: Auth0 tokens, at least will have an access_token but can eventually have refresh_token and/or id_token
84-
- extra: Additional info obtained from calling /userinfo in the attribute `raw_info`
83+
- `:provider` - the name of the strategy, in this case `auth0`
84+
- `:uid` - the user identifier
85+
- `:info` - the result of the call to `/userinfo` using OmniAuth standard attributes
86+
- `:credentials` - tokens requested and data
87+
- `:extra` - Additional info obtained from calling `/userinfo` in the `:raw_info` property
8588

8689
```ruby
87-
{
88-
:provider => 'auth0',
89-
:uid => 'google-oauth2|this-is-the-google-id',
90-
:info => {
91-
:name => 'John Foo',
92-
:email => '[email protected]',
93-
:nickname => 'john',
94-
:image => 'https://example.org/john.jpg'
95-
},
96-
:credentials => {
97-
:token => 'XdDadllcas2134rdfdsI',
98-
:expires_at => 1485373937,
99-
:expires => true,
100-
:refresh_token => 'aKNajdjfj123nBasd',
101-
:id_token => 'eyJhbGciOiJIUzI1NiIsImN0eSI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBGb28ifQ.lxAiy1rqve8ZHQEQVehUlP1sommPHVJDhgPgFPnDosg',
102-
:token_type => 'bearer',
103-
},
104-
:extra => {
105-
:raw_info => {
106-
:email => '[email protected]',
107-
:email_verified => 'true',
108-
:name => 'John Foo',
109-
:picture => 'https://example.org/john.jpg',
110-
:user_id => 'google-oauth2|this-is-the-google-id',
111-
:nickname => 'john',
112-
:created_at => '2014-07-15T17:19:50.387Z'
113-
}
114-
}
115-
}
90+
{
91+
:provider => 'auth0',
92+
:uid => 'auth0|USER_ID',
93+
:info => {
94+
:name => 'John Foo',
95+
:email => '[email protected]',
96+
:nickname => 'john',
97+
:image => 'https://example.org/john.jpg'
98+
},
99+
:credentials => {
100+
:token => 'ACCESS_TOKEN',
101+
:expires_at => 1485373937,
102+
:expires => true,
103+
:refresh_token => 'REFRESH_TOKEN',
104+
:id_token => 'JWT_ID_TOKEN',
105+
:token_type => 'bearer',
106+
},
107+
:extra => {
108+
:raw_info => {
109+
:email => '[email protected]',
110+
:email_verified => 'true',
111+
:name => 'John Foo',
112+
:picture => 'https://example.org/john.jpg',
113+
:user_id => 'auth0|USER_ID',
114+
:nickname => 'john',
115+
:created_at => '2014-07-15T17:19:50.387Z'
116+
}
117+
}
118+
}
116119
```
117120

118-
### ActionDispatch::Cookies::CookieOverflow issue
121+
## Contribution
119122

120-
If you are getting this error it means that you are using Cookie sessions and since you are storing the whole profile it overflows the max-size of 4K.
123+
We appreciate feedback and contribution to this repo! Before you get started, please see the following:
121124

122-
You can change to use In-Memory store for development as follows:
125+
- [Auth0's contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
126+
- [Auth0's Code of Conduct](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
127+
- [This repo's contribution guide](CONTRIBUTING.md)
123128

124-
# /config/initializers/session_store.rb
125-
CrazyApp::Application.config.session_store :cache_store
129+
## Support + Feedback
126130

127-
# /config/environments/development.rb
128-
config.cache_store = :memory_store
129131

130-
## Documentation
132+
- Use [Community](https://community.auth0.com/) for usage, questions, specific cases.
133+
- Use [Issues](https://github.com/auth0/omniauth-auth0/issues) here for code-level support and bug reports.
134+
- Paid customers can use [Support](https://support.auth0.com/) to submit a trouble ticket for production-affecting issues.
135+
136+
## Vulnerability Reporting
131137

132-
For more information about [auth0](http://auth0.com) contact our [documentation page](http://docs.auth0.com/).
138+
Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues.
133139

134-
## Issue Reporting
140+
## What is Auth0?
135141

136-
If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues.
142+
Auth0 helps you to easily:
137143

138-
## Author
144+
- implement authentication with multiple identity providers, including social (e.g., Google, Facebook, Microsoft, LinkedIn, GitHub, Twitter, etc), or enterprise (e.g., Windows Azure AD, Google Apps, Active Directory, ADFS, SAML, etc.)
145+
- log in users with username/password databases, passwordless, or multi-factor authentication
146+
- link multiple user accounts together
147+
- generate signed JSON Web Tokens to authorize your API calls and flow the user identity securely
148+
- access demographics and analytics detailing how, when, and where users are logging in
149+
- enrich user profiles from other data sources using customizable JavaScript rules
139150

140-
[Auth0](https://auth0.com)
151+
[Why Auth0?](https://auth0.com/why-auth0)
141152

142153
## License
143154

144-
This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.
155+
The OmniAuth Auth0 strategy is licensed under MIT - [LICENSE](LICENSE)

0 commit comments

Comments
 (0)