diff options
| author | Frédéric Guillot <fred@kanboard.net> | 2014-06-30 21:52:02 -0300 |
|---|---|---|
| committer | Frédéric Guillot <fred@kanboard.net> | 2014-06-30 21:52:02 -0300 |
| commit | 06d0b7048ebcdfdf6e24eec3ac7dc8fb0327dd6f (patch) | |
| tree | eb006b4c560781186f1debd2437c02edf6008878 /docs | |
| parent | f70ac7d65fa0e7f1e6a9559242d9c141ba5c9eb3 (diff) | |
Merge pull-request: Github authentication #162
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/github-authentication.markdown | 62 |
1 files changed, 62 insertions, 0 deletions
diff --git a/docs/github-authentication.markdown b/docs/github-authentication.markdown new file mode 100644 index 00000000..ef99bb80 --- /dev/null +++ b/docs/github-authentication.markdown @@ -0,0 +1,62 @@ +GitHub Authentication
+=====================
+
+Requirements
+------------
+
+- OAuth GitHub API credentials (available in your [Settings > Applications > Developer applications](https://github.com/settings/applications))
+
+How does this work?
+-------------------
+
+The GitHub authentication in Kanboard uses the [OAuth 2.0](http://oauth.net/2/) protocol, so any user of Kanboard can be linked to a GitHub account. When that is done, they no longer need to manually login with their Kanboard account, but can simply automatically login with their GitHub account.
+
+How to link a GitHub account
+----------------------------------
+
+1. Login to Kanboard with the desired user
+2. Go to the **Edit user** page and click on the link **Link my GitHub Account**
+3. You are redirected to the GitHub **Authorize application** form, authorize Kanboard by clicking on the button **Accept**
+4. Finally, you are redirected to Kanboard and now your user account is linked to your GitHub account
+5. During the process, Kanboard has updated your full name and your email address based on your GitHub profile, if either of those are publically available
+6. Log out of Kanboard and you should be able to login directly with GitHub by clicking on the link **Login with my GitHub Account**
+
+Installation instructions
+-------------------------
+
+### Setting up OAuth 2.0
+
+If you know what you're doing, you can directly go to the ["Register a new OAuth application"](https://github.com/settings/applications/new) site, set everything up and skip to [Setting up Kanboard](#setting-up-kanboard) below.
+
+Summarizing the [official GitHub documentation](https://developer.github.com/guides/basics-of-authentication/#registering-your-app):
+
+- Open your [**Settings**](https://github.com/settings), select [**Applications**](https://github.com/settings/applications) from the sidebar and click on [**Register new application**](https://github.com/settings/applications/new) on the top, next to where it says **Developer applications**
+- Fill out the form with whatever values you like, only the **Authorization callback URL** _must_ be: **http://YOUR_SERVER/?controller=user&action=gitHub**
+
+### Setting up Kanboard
+
+Either create a new `config.php` file or copy and rename the `config.default.php` file and set the following values:
+
+```php
+// Enable/disable GitHub authentication
+define('GITHUB_AUTH', true);
+
+// GitHub client id (Copy it from your settings -> Applications -> Developer applications)
+define('GITHUB_CLIENT_ID', 'YOUR_GITHUB_CLIENT_ID');
+
+// GitHub client secret key (Copy it from your settings -> Applications -> Developer applications)
+define('GITHUB_CLIENT_SECRET', 'YOUR_GITHUB_CLIENT_SECRET');
+
+```
+
+Notes
+-----
+**Important:** _*Never*_ store your GITHUB_CLIENT_ID or GITHUB_CLIENT_SECRET in GitHub or somewhere with full public access in general!
+
+Kanboard uses these information from your public GitHub profile:
+
+- Full name
+- Public email address
+- GitHub unique id
+
+The GitHub unique id is used to link the local user account and the GitHub account.
|