From ceccc3aaab2940ef80c9074c1d3db86c8f90a695 Mon Sep 17 00:00:00 2001 From: Joe <jmader@jmader.com> Date: Tue, 12 Nov 2013 19:34:22 -0500 Subject: [PATCH] Update README.md --- README.md | 71 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 47 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 6597192..af0ef68 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,76 @@ ## Redmine omniauth google -This plugin is used to authenticate in redmine through Google. +This plugin is used to authenticate Redmine users using Google's OAuth2 provider. ### Installation: -Choose folder /plugins, make command +Download the plugin and install required gems: ```console +cd /path/to/redmine/plugins git clone https://github.com/twinslash/redmine_omniauth_google.git +cd /path/to/redmine +bundle install ``` -Update gems and restart rails server. +Restart the app +```console +touch /path/to/redmine/tmp/restart.txt +``` ### Registration -To make possible to authenticate via Google you must first to register application in Google - -* Go to the [registration](https://code.google.com/apis/console) link. -* Press "API Access" in left menu bar. -* Click the button "Create an OAuth 2.0 client ID". -* When registering specify application name, for example, Redmine Oauth Google. -* In section "Your site or hostname" choose mode http, in the text input box enter your domain. For example: www.example.com or localhost -* Press the button "Create client ID". - -The registrations is complete. +To authenticate via Google you must first register your redmine instance via the Google Cloud Console + +* Go to the [registration](https://cloud.google.com/console) link. +* Click your Project's name +* Click "APIs & Auth" +* Click "Registered Apps" +* Click "Register App" +* Type a name for the application, e.g. "My Redmine" +* Select "Web Application" as the Platform +* Click "Register" +* Click "OAuth 2.0 Client ID" +* Enter "https://mydomain.com/redmine/oauth2callback", where "mydomain.com/redmine" is the domain / path for your redmine instance. *** The plugin will not work without this setting *** +* Click "Generate" +* Save the Client ID and Client Secret for the configuration of the Redmine plugin (see below) ### Configuration -To make plugin to work properly - -* Login as administrator. In top menu select "Administration". Choose menu item Plugins. In plugins list choose "Redmine Omniauth Google plugin". Press "Configure". -* Fill Сlient ID & Client Secret by corresponding values, obtained by Google. -* Put the check "Oauth authentification", to make it possible to login through Google. Click Apply. Users can now to use apportunity to login via Google. +* Login as a user with administrative privileges. +* In top menu select "Administration". +* Click "Plugins" +* In plugins list, click "Configure" in the row for "Redmine Omniauth Google plugin" +* Enter the Сlient ID & Client Secret shown when you registered your application via Google Cloud Console. +* Check the box near "Oauth authentication" +* Click Apply. + +Users can now to use their Google Account to log in to your instance of Redmine. Additionaly * Setup value Autologin in Settings on tab Authentification ### Other options -By default, all domains are allowed to authenticate through Google. -To limit login through Google for other domains you have to fill allowed domains in the text box field the "Allowed domains". Domains must be separated by newlines. For example: +By default, all user email domains are allowed to authenticate through Google. +If you want to limit the user email domains allowed to use the plugin, list one per line in the "Allowed domains" text box. + +For example: ```text onedomain.com otherdomain.com ``` -### Work process +With the above configuration, only users with email addresses on the domains "onedomain.com" and "otherdomain.com" will be allowed to acccess your Redmine instance using Google OAuth. + +### Authentication Workflow + +1. An unauthenticated user requests the URL to your Redmine instance. +2. User clicks the "Login via Google" buton. +3. The plugin redirects them to a Google sign in page if they are not already signed in to their Google account. +4. Google redirects user back to Redmine, where the Google OAuth plugin's controller takes over. -User goes to the login page (sign in) and clicks the button with Google image. The plugin redirects him to Google where user enters his the еmail & password from Google. Google redirects user back to plugins controller. Then the following cases: -1. If auto registration is enabled, user is redirected to 'my/page' -2. In other case user account is created and waited for admin activation +One of the following cases will occur: +1. If self-registration is enabled (Under Administration > Settings > Authentication), user is redirected to 'my/page' +2. Otherwse, the an account is created for the user (referencing their Google OAuth2 ID). A Redmine administrator must activate the account for it to work. -- GitLab