LenAuth Features Plugin opportunities and advantages as for Moodle administrator or its user

• Free Open-Source module, Install and use it, not everything in the world is measured by money, you should also do something helpful for others;
• Easy installation, Dearchive and upload plugin files in /auth/lenauth/ folder;
• Settings detailed description, This page contains detailed instructions with screenshots;
• Russification, this plugin has at least two localizations: the Russian and English one;
• Retrieve avatar, option for automatic upload avatar (profile image) from social profile to Moodle profile;
• Button's personal text, You can write your text in buttons/links if the output template allows doing it. For example, 'Login using vk.com', etc;
• Services enable/disable., If you don't need a definite social network (for example Yahoo isn't popular in Russia), you can disable it;
• Several output templates, Choose the button output template you like;
• Flexible settings, Complete assembly of core authorization in Moodle;
• Logos localization: Yandex and VK has as Russian logotypes, and international ones, you can setup output localization of these logotypes;
• Setup buttons output order: You are free to shape the order output of authorization buttons/links;
• OAuth1 and OAuth2 Yahoo support: If your Yahoo application still uses OAuth1, you can enable support for this protocol version, you can also use the new protocol OAuth2

Operating principle / how LenAuth works Configure additional users profile fields for more correct work of some social networks

It's better to describe OAuth-authorization operation principle in applications for your understanding, first of all. It's quite simple:

1. Application registration in a corresponding social network
2. Special keys receiving (hash lines like dfs78dgksnvm6s99s......)
3. Special request formation with the usage of corresponding keys to the respective social network web service on OAuth protocol
4. Token receiving and its validation
5. Information receiving (response) from social network web service in a special form (name, surname, date of birth, id in a corresponding social network, gender, email, etc.)

LenAuth build requests and parse responses from web services, seems like everything is easy. But not to all of them. Some social networks web services rules prohibit email, family name return. Why, they are the once we identify whether a student has a profile in your Moodle base.

But! All web services return users id in social networks. Thus for more correct plugin work it is necessary to set conformities of the additional student profile fields with the corresponding LenAuth fields. It allows to write these ids to database, and identify user uniqueness with its help. Plugin does it automatically.

LenAuth Plugin installation and setting Detailed steps of plugin installation on your Moodle

Requirements: correctly working Moodle 2.6.5+

Download link: LenAuth 1.2.4 (official Moodle repository)

Plugin upload by FTP

Download plugin from the official plugins Moodle repository. Load lenauth folder in FTP (for example, with the help of FileZilla program) in auth folder of your Moodle website.

Plugin activation in Moodle

Moodle has wired-in check of new modules, so that when you load new plugin by FTP, the system will automatically ask you to activate it.

Enabling in settings

In Administration widget choose Site administration → Plugins → Authentication → Manage authentication.

Enabling in settings

This section presents the full list of all available authentication ways in Moodle, including LenAuth. It's disabled by default, but it should be enabled.

Setting

After you enable the plugin in settings, it'll appear in your menu Site administration → Plugins → Authentication → LenAuth.

Start LenAuth configuration

You can configure the plugin after its installation, activation and enabling. But first of all you have to create OAuth applications, it's written below how to do it.

OAuth applications setting Descriptions how to make applications

• Facebook
• Google
• Yahoo
• Twitter
• VK
• Yandex
• Mail.ru

Facebook is the largest social network in the world, its daily audience is about 700 million users all over the world, and the total amount of users is 1.3 billion people. You should have Facebook account.

• 1. Registration
• 2. Setting
• 3. Data copying
• 4. LenAuth

You should have Facebook account.

1. Register as Facebook developer. This procedure is non-committal; this is the Facebook rule for OAuth-applications development. The developer console will be available after registration.
2. Application platform (type) — choose Website
3. In a pop-up fill in Display Name, Category (for example, Education), do not touch the rest, press Create App ID

Go to the application you created from developer console. Here you can edit all the application settings:

1. In the menu on the right proceed to the Settings
2. In the small menu on the top go to tab Advanced option should be active (Yes)
3. Client OAuth Login (Yes)
4. Enter in box Valid OAuth redirect URIs URL from LenAuth plugin that is like http://your-moodle-address.com/auth/lenauth/redirect.php?auth_service=facebook
5. Click Save Changes button

You can also do an extended application setting. It allows you to beautifully arrange an application page from the first student login, and he/she will see the application name, its description and your company/educational institution logo. If you want an extended setting, go to App Details in the left menu and fill in necessary blanks there.

You should know your App ID and App Secret to activate your Facebook application.

In the right menu go to Dashboard, field App Secret is hidden by default, press Show to show it.

Go to created applications for Moodle authorization from your applications list.

Here you have to copy two parameters: App ID and App Secret

Google is the largest search engine in the Internet with a great amount of services, including own social network.

• 1. Registration
• 2. Setting
• 3. Data copying
• 4. LenAuth

You should have Google account.

1. Go to developers console.
2. Click Create Project
3. Wait a bit while Google unfold the project
4. You will be automatically redirected to the project settings
5. Go to APIs & auth → Credentials in the left-side menu
6. In OAuth block click Create new Client ID
7. In pop-up window Create Client ID check the following values: Application type: Web application, Authorized javascript origins: empty, Authorized redirect URI: LenAuth link hint in Google block like http://your-moodle-address.com/auth/lenauth/redirect.php?auth_service=google
8. Click Create Client ID
9. Google will redirect you to OAuth-data page after activation

Go to Google developer console (your projects list), here you can get all your projects data.

Go to the created application from the developer console

1. In the right menu choose APIs & auth → Consent screen
2. Choose EMail Address
3. Enter Product name (project name, for example, Students authorization through social networks)
4. Description — more detailed application description
5. Category — application category, choose Others
6. Icon 16×16 — small logo

IMPORTANT! At Google developers console in your project settings you need to go to section APIs & auth → APIs, here you need to activate Google+ API: at list Browse APIs find the item Google+ API and in column Status click on the button OFF (to activate API), the button will change a color to green, and the item will move to the list Enabled APIs.

You can also set advanced settings to make an application input page more clear and beautiful. Just spend time once and forgive forever.

You should have two required parameters: Client ID and Client Secret, You can find them in the project menu at the left in APIs & auth → Credentials

Project ID as an additional not required parameter from Overview section

Copy Client ID, Client Secret

Copy appropriate settings in Google settings of LenAuth plugin block

Yahoo! is the second popular search engine in US and Canada. The most popular service is YahooMail and Flickr.

• 1. Registration
• 2. Setting
• 3. Data copying
• 4. LenAuth

You should have a Yahoo! registered account.

Go to new application creation form at Yahoo developers console (YDN).

1. Application Name — your application name, for example, Students Authorization via social networks
2. Application Type — Web-based
3. Description — your application description
4. Home Page URL — your website home page with Moodle
5. Access Scopes — This app requires access to private user data
6. Callback Domain — enter it from LenAuth Yahoo! settings block hint
7. VERY IMPORTANT!
   Select APIs for private user data access — checkbox Social Directory (Profiles) and inside it choose Read/Write Public and Private
8. Terms of Use — check it
9. Create App

Now you can use OAuth1 both with OAuth2 protocols, just select the version in LenAuth Yahoo settings!

Go to Yahoo! developer console (your projects list), here you can obtain data on all your projects.

Enter in created application from the developer console

1. Go to the tab Details of your application top menu
2. Application setting is divided into blocks on this page. Too much information should be filled in in order to do an application input page more explicit and beautiful

Go to the tab APIs and Services in your application console

Go to the tab Settings: in the top menu of your application: two upper parameters are those you are needed

Copy Application ID, Consumer Key, Consumer Secret from point 3

Copy corresponding settings in Yahoo! LenAuth plugin settings section.

Twitter is a popular social service of short instant messaging.

• 1. Registration
• 2. Setting
• 3. Data copying
• 4. LenAuth

You should have Twitter account.

Go to the new application creation form.

1. Name — your application name, for example, Students authorization via socials
2. Description — your application description
3. Website — home page of your website with Moodle
4. Callback URL — enter it from the Twitter setting block of LenAuth plugin hint
5. Checkbox Yes, I agree
6. Create your Twitter application

Go to Twitter developers console (your projects list), here you can obtain data concerning all your projects.

Go to the created application from developers console

1. Go to tab Settings of application's top menu
2. Here is a few information that have already been entered during application creation. Mark the option Allow this application to be used to Sign in with Twitter
3. Also you can set an application icon in Application Icon section. All it is needed to do is to put your company logo.
4. We advise you to feed information about your company in Organization section: Organization name and Organization website (not necessarily your Moodle address)

Go to the tab Keys and Access Tokens of the application top menu

Here you will need 2 required and one not required parameter for OAuth Twitter setting: Consumer Key (API Key), Consumer Secret (API Secret)

Not required parameter — is an Application ID, you can get it manually from browser address bar, for example, your application URL in Twitter developer console looks like https://apps.twitter.com/app/1234567/keys, 1234567 accordingly (in this case) is needle parameter.

Copy Consumer Key, Consumer Secret and not required, but recommended application ID

In LenAuth Twitter setting block copy appropriate settings

VK.com is the biggest social network in Europe, its daily audience comprises around 60 million users, mostly from Russia.

• 1. Registration
• 2. Setting
• 3. Data copying
• 4. LenAuth

You should have VK.com registered account.

1. Go to the link application creation.
2. Enter friendly for students name Title (for example, «Authorization thought Saint Petersburg Polytechnic University social networks»)
3. Category Website
4. Site address: http://your-moodle-address.com
5. Base domain: your-moodle-address.com (without http://)
6. Click Connect Site

Go to your applications list, here you can obtain data on all your applications.

Go to the created application from developer console — tab link Settings. Her you can edit all application settings:

1. Title — friendly name for students, for example, Authorisation though social networks
2. Description — more detailed application description
3. Category — application category, choose Other
4. 16×16 Icon — small logo

You can also edit more detailed settings to make an application input page more clear and beautiful. Just spend time once and forgive forever.

In order to connect VKontakte application to Moodle (LenAuth) only two parameters are needed: Application ID, Secure key

Go to the tab Settings in the application top menu: two top parameters are what you need

You need to copy two parameters from point 3 Application ID and Secure key

Copy appropriate settings in VK.com (VKontakte) settings block of LenAuth plugin

Yandex is the fourth in the world and the first in Russia search engine with more than 50 services, except the search directly. Yandex has more than 100 million users.

• 1. Registration
• 2. Setting
• 3. Data copying
• 4. LenAuth

The most important thing is that you should have a registered Yandex account (it's enough to have a Yandex mail box). Here is a description to register at English Yandex — Yandex.com, this is not the same as Yandex.ru

Register your OAuth-application

Application setting will be required during registration. It can be as minimum (for example, to check the application working capacity together with LenAuth), also as extended with your educational center logo and description for beautiful visualization and students' support while authorization.

Such fields as Title, Description, Link to icon and Link to client site are on your discretion

In Scopes field select Yandex.Username and set out 2 options (User name and gender, Email address)

In Callback URL you should enter the meaning that is indicated in LenAuth plugin hint for Yandex that looks like http://your-moodle-address.com/auth/lenauth/redirect.php?auth_service=yandex

Go to your application list, here you can obtain all your applications data.

Go into created application. Here you can edit all applications settings:

1. Title of application — this is how your application is called, for example «Authorization through Polytechnic University social networks»
2. Description of application — is a more detailed application description. It will also appear at the first student login. Just describe what the application do to inform the one who login what does he/she do, and what are the reasons for this.
3. Link to icon — is the file path with your company logo, for example. It will also be reflected at the first student login.
4. Link to client website — your website address, not CallBack URL
5. Scopes — if selected Yandex.Passport API, two options will appear: Access to username, full name and gender, Access to email address
6. Callback URL — http://your-moodle-address/auth/lenauth/redirect.php?auth_service=yandex

Go to created application for Moodle authorization from your application list.

Here you need to to copy two parameters: ID and Password

This page also contains all information about your application without editing function.

Go to LenAuth settings in your ( address is http://your-moodle-address.com/admin/auth_config.php?auth=lenauth ), proceed to Yandex settings and fill in the first two fields.

You have to copy ID and Password to your Yandex settings section at LenAuth.

Mail.ru — is the biggest Russian service that provides mailboxes and search engine. Mail.Ru has only Russian interface, so some words here are in Russian language.

• 1. Registration
• 2. Setting
• 3. Data copying
• 4. LenAuth

You must have a registered Mail.Ru account.

1. Start the website registration process at Платформа@Mail.Ru
2. The first step is a necessity to read and accept Mail.Ru user rules/terms. Check the option Я принимаю правила использования Платформа@Mail.Ru (I accept terms) and click Продолжить (Continue)
3. The second step is the website initial configuration: Название (title, for example, Authorization through Mail.Ru SPSU ITMO) and Адрес главной страницы (website address of your Moodle)
4. The third step not required but recommended — you are proposed to download a special file receiver.html and upload it to website root. If you dont want to do it — click the link Продолжить (continue), and on the next step click the link Пропустить (Admit)

Go to your websites list (список Ваших сайтов), Here you can edit all application settings.

Go to the created application:

1. Название (title) — the name how your application called, for example, «Authorization through Mail.Ru SPSU»
2. Адрес сайта (website address) — your website address where Moddle and LenAuth are installed
3. Иконка для списков и Картинка для диалогов (Icon for lists and Picture for dialogs) — icon and logo of your organization/educational institution for website visualization in Mail.Ru. It's very important to observe the following simple rules:
   For icons:
   1. Size 16x16px
   2. GIF or PNG formats
   3. Icon should be static, it's prohibited to use animated pictures
   4. Icon should be unique and do not repeat other icons from the applications catalog
   For logos:
   1. Size 120x60px
   2. JPG format
   3. White background is prohibited to use (including partial)
   4. Application name on logo should be posted legibly
4. Адрес страницы receiver.html — not required, but recommended parameter — location receiver.html

On the same page of your website in Platforma@Mail.Ru 3 parameters are presented: ID, Приватный ключ (private key), Секретный ключ (Secret key).

Go to your LenAuth settings of your Moodle and in a corresponding block enter ID, Приватный ключ (private key), Секретный ключ (secret key).

Buttons output on Moodle website How to output ready buttons template on your Moodle website

You have to correct your current Moodle template to output links/buttons students will press for authorization.

How to know current Moodle template? For this you should move to ADMINISTRATION → Site administration → Appearance → Themes → Theme selector (or the theme name will be in the same menu in Theme selector). If you entered in Theme selector, the theme name in Information column will be shown.

For example, your current theme name is Clean (this is a basic theme in Moodle 2.7.2 base on CSS framework Bootstrap), then your working folder on Moodle FTP is /theme/clean(in case if current theme is clean)/layout. Working php-files of new websites output are Inside layout folder. Usually output files are called like this: frontpage.php, general.php, columns3.php, columns2.php, columns1.php

Insert code can be found in administration panel of plugin in styles table of Output settings in column Theme PHP-code. For example, for LenAuth smooth-w64-classic-circle buttons output template it's necessary to insert code in the right place:
<?php if ( file_exists( $CFG->dirroot . '/auth/lenauth/out.php' ) ) : include_once $CFG->dirroot . '/auth/lenauth/out.php'; echo auth_lenauth_out::getInstance()->lenauth_output('smooth-w64-classic-circle'); endif; ?>

Also you can output buttons via HTML-code. At LenAuth admin screen above PHP-code for theme click Static HTML, new window will open with static HTML-code. Notice that after change OAuth-application settings, you need to update static HTML-code in your theme.

ATTENTION! Some socials has different logos for Russian and International users, for example, Yandex and VK.com. By default is International logos. If you want Russian logos, you need to select Russian logos at settings.

Social buttons templates Here all possible button types and its descriptions are shown

The plugin allows several buttons templates from just text links to beautiful buttons/links with logos of socials. You can see and test it at LenAuth admin screen in section «Output settings». In this table, for clarity, shown only two buttons/links: Facebook and Twitter. It styles in the table is as live style (margins, width).

Extended settings All about unordinary plugin settings

«Main settings» section

1. User prefix: Each student that has signed in through LenAuth has its own internal ID, also any Moodle user should have their username, in other words, login for entry. Prefix does user login as (Prefix)+(ID in LenAuth). This login is assigned to student during registration through LenAuth, he/she can change it later. We advise to keep the login prefix as lenauth_user_.
2. Default country: Not all social networks OAuth-providers return user country of residence. Therefore, if most of your students represent a definite country, you can set this country by default, and it will be automatically set while student registration. He/she can always change it.
3. International logos / Russian logos: some Russian services that has not only Russian users has an own international logos, for example, Yandex and VK.com (VKontakte)
4. User can reset/change an internal password:This option is extremely important, as user do not set the password while registration by default and the system can admit the user only through LenAuth checking his data in Moodle database. Therefore, if you want to give users an opportunity to «get rid» of sign in ONLY with LenAuth, and to sign in with an ordinary sign in form with login and password, turn on this option.
5. Moderate new users: new users will have to confirm their email and they will receive a Moodle system mail with the special link. Account will be activated as user click on the link.

«Buttons settings» section

In LenAuth administration panel each style has two button types: Facebook and Twitter — This is the example of button location and style (with spaces and location you configured). You can approximately assume how a definite button style will be looked like on your Moodle website.

1. Buttons location: two options are available
   1. Inline: buttons will follow each other abreast
   2. Block: Buttons will be presented in a list under each other (sometimes on a whole width of the button area)
2. Width (0 = auto): each button width (CSS-property width). Not for all button templates is available!;
3. Margin top (px): margin-top of each button in pixels (CSS-property margin-top);
4. Margin right (px): margin-right of each button in pixels (CSS-property margin-right);
5. margin bottom (px): margin-bottom of each button in pixels (CSS-property margin-bottom);
6. Margin left (px): margin-left of each button in pixels (CSS-property margin-left);

«Buttons area settings» section

Buttons area — is an invisible section/block (div) with css-class lenauth-buttons, where buttons are located. It's like a buttons «cover». It can have the same features as buttons have (margins and location).

1. Area location: two options are available
   1. Inline: button area will have line feature that means that buttons will not spread on a whole parental area width
   2. Block: button area will be in an ordinary condition on the whole width of the parental area
2. Width (0 = auto): buttons area width (CSS-property width);
3. Margin top (px): margin-top of buttons area in pixels (CSS-property margin-top);
4. Margin right (px): margin-right of buttons area in pixels (CSS-property margin-right);
5. Margin bottom (px): margin-bottom of buttons area in pixels (CSS-property margin-bottom);
6. Margin left (px): margin-left of buttons area in pixels (CSS-property margin-left);

Settings with the help of your theme additional CSS

All buttons have similar HTML-structure: «area-cover» (buttons area, usually it is div) with css-class lenauth-buttons. There is ul list inside it without css-classes and li list elements. There is a link a with its css-classes inside each list element. Different elements can be inside the link, it depends on the concrete buttons output style. Accordingly, HTML-structure has this type:

<div class="lenauth-buttons some-additional-classes-if-needed">
    <ul>
        <li>
            <a class="twitter-or-facebook-or-yahoo some-additional-classes-if-needed">some-content</a>
        </li>
        <li>
            <a class="twitter-or-facebook-or-yahoo some-additional-classes-if-needed">some-content</a>
        </li>
        .......
    </ul>
</div>

If you are not enough with those features that LenAuth settings offer, you can edit CSS of your current theme in Moodle. Don't forget that in some cases, probably, it'll be needed to use additional CSS-property !important.

Possible system errors description Do not afraid of system errors, they can be and have their own descriptions and codes. The main thing is to understand what kind of error it is

Moodle as most similar system has its own «catching exceptions» system (errors system). Such errors can be as «native» (integrated in system and those that appear during working with the system directly without plugin), also as additional, that is Moodle developers foresee possible problems and, if they happen, warn about these errors. Error text appears in English.