Configuring the Server Connection

이 모듈의 configuration은 Administration Module 이나 SITE_DIR/config/people/feeds.ini file을 edit 하셔야 합니다. 여러분의 directory 시스템에 connect 하기 위해서는 여러 방법들이 사용될 수 있습니다.

• RETRIEVER_CLASS allows you to determine the mechanism for retrieving the data. Current options include:
  • LDAPPeopleRetriever - uses a standard LDAP server. You can configure the various fields if your values differ from defaults
  • ADPeopleRetriever - a subclass of the LDAP retriever that has preconfigured mappings for Active Directory
  • DatabasePeopleRetriever - connects to an external database server. This controller assumes that people are mapped to a single row and that the various fields are stored in single (definable) columns
• PERSON_CLASS allows you to set a different class name for the returned user objects when searching. This class must be a subclass of the Person class. This allows you to write custom behavior to handle the data in your directory service.

Configuring the Detail Fields

서버 세팅이 끝났으면 여러분 서버와 detail view 와의 field mapping을 해야 합니다. 디폴트로는 LDAP으로 세팅 돼 있습니다. 만약에 nonstandard directory를 사용하신다면 혹은 자체 필드들을 가지고 있는 데이터베이스와 연결하신다면 이것들이 어떻게 display 될지에 대해 customize 하셔야 합니다.

이 필드들은 SITE_DIR/config/people/page-detail.ini file 에 configured 됩니다. 각 필드는 섹션별로 configured 됩니다. (섹션 이름은 unique 해야 합니다.) 섹션의 순서는 detail view의 순서와 같습니다. 각 섹션안에는 어떻게 display 될지에 대해 설정할 수 있는 여러 value들을 넣을 수 있습니다.

• label - (required) A text label for the field. Can include HTML tags.
• attributes - (required) Array of fields to put in the contents (should map the the field names in your backend system)
• format - (optional) A string for vsprintf to format the attributes. Only needed if more than one attribute is provided.
• type - (optional) One of “email” or “phone”. Used to format and generate links.
• module - (optional) Creates a link to a another module and uses that module’s linkForValue method to format the result. See the section on Module Interaction for more details.
• section - (optional) If this field belongs to a section, the name of that section
• parse - (optional) A function which will be run on the value before display. Generated with create_function. Gets the argument “$value” and returns the formatted output.

Configuring Display Options

아래 있는 옵션들은 people 모듈을 appearence 하는데 관련된 것들입니다.

• BOOKMARKS_ENABLED - (optional) If set to true, a link to bookmarked entries will appear. Note that if you have not bookmarked any entries, this link will not appear until an entry is bookmarked. Defaults to true.
• CONTACTS_SUBTITLE_NEWLINE - (optional) Set to true to display contacts subtitles on a new line. Defaults to false.
• SEARCH_TIP - (optional) A string to be shown near the search bar providing a tip about searching. By default this string is empty, and not shown.

Configuring the Fixed Entries

이 모듈은 모듈 인덱스 페이지에서 directory entry들의 리스트를 보이게 할 수 있습니다. 그리고 SITE_DIR/config/people/contacts.ini를 수정함으로서 이 리스트의 content를 update 하실 수 있습니다. 각 entry는 섹션의 0-indexed 형식으로 숫자화 되서 다뤄집니다. 각 섹션은 4개의 value들이 있습니다. 이것들은 listItem template 과 매핑돼 있죠. 이것들은 URL 리스트를 표시하기 때문에 phone number 를 가지지 못합니다. 다만 어떤 URL 이라도 올 수 있습니다.

• title - The Name of the entry as it’s shown to the user
• subtitle - The subtitle, typically the phone number for phone entries.
• url - The link it should point to, use tel:XXXXXXXX links for phone numbers
• class - The CSS class of the item, such as phone, map, email

[admissions]
title = "Admissions"

[0]
title    = "Admissions Main Number"
subtitle = "(617-555-0001)"
url      = "tel:6175550001"
class    = "phone"

[1]
title    = "Admissions Hotline"
subtitle = "(617-555-0002)"
url      = "tel:6175550002"
class    = "phone"

[0]
title    = "Static Entry 1"
subtitle = "(617-555-0001)"
url      = "tel:6175550001"
class    = "phone"

[1]
title    = "Admissions"
group    = "admissions"

Configuration

링크모듈의 display 에 영향을 줄 수 있는 몇가지 configuration 값들이 있습니다.

display_type - home module 과 비슷합니다. 리스트나 스프링 보드를 사용하실 수 있습니다.

[0]
title = "This is link 1"
url   = "http://example.com/urlforlink1"
icon  = "link1_icon.png"

[1]
title = "This is link 2"
url   = "http://example.com/urlforlink2"
icon  = "" ; link 2 does not have an icon

[2]
title = "This is link 3"
url   = "http://example.com/urlforlink3"
icon  = "link3_icon.png"

[admissions]
title = "Admissions"

[0]
title    = "Admissions Main Number"
subtitle = "(617-555-0001)"
url      = "tel:6175550001"
class    = "phone"

[1]
title    = "Admissions Hotline"
subtitle = "(617-555-0002)"
url      = "tel:6175550002"
class    = "phone"

[0]
title    = "Static Entry 1"
subtitle = "(617-555-0001)"
url      = "tel:6175550001"
class    = "phone"

[1]
title    = "Admissions"
group    = "admissions"

Configuring Content Feeds

SITE_DIR/config/MODULE/feeds.ini file에 원하는 만큼의 feed 를 정의 하세요. 각 feed 는 section에 의해 표현됩니다. 그 섹션의 이름은 모듈의 page를 의미합니다. 이곳에는 configure 할 몇가지 property들이 있습니다.

• TITLE - The title of the feed. This is shown in the list and in the navigation bar
• CONTENT_TYPE - the type of content. Values include:
  • html - Static html text that is included in the CONTENT_HTML property
  • html_url - Fetch HTML content from the BASE_URL property.
  • rss - Fetch RSS content from the BASE_URL property. Will retrieve the content from the first item in the feed. Good for CMS’s that expose their content via RSS. Ensure that this feed contains the full content and not just a link

Creating Groups of Content

• NOTE - Creation of content groups is not supported in the admin console at this time.

You can create groups of content in order to organize similar content into categories. Creating content groups involves the following steps:

유사한 콘텐트를 하나의 카테고리에 묶기 위해 콘텐트의 group을 만들 수 있습니다. 아래와 같이 group을 생성하시면 됩니다.

1. SITE_DIR/config/MODULE/feedgroups.ini 파일을 생성한다.
2. 그룹 이름을 feedgroups.ini 의 section 안에 넣는다. 스페이스나 특수문자가 없는 alpha numeric 소문자이어야 한다.
   
3. 섹션에는 TITLE option이 있어야 한다. 이것은 그룹의 title을 나타낸다. 옵션으로 DESCRIPTION value를 넣을 수 있다. 이것은 그룹의 리스트 top에 보여질 내용이다.
   
4.  SITE_DIR/config/MODULE/feeds-groupname.ini  파일을 만든다. groupname is the short name of the group you created in feedgroups.ini. This file should be formatted like feeds.ini with each entry being a uniquely indexed section.
   
5. 이 그룹을 사용하기 위해 eeds.ini. 안에 entry를 할당한다. 그룹의 short name 값으로 GROUP 값을 넣는다. 옵션으로 TITLE을 넣을 수 있다. 이것은 eedgroups.ini 안에서 group title 대신에 쓰이게 된다.
   
   

feeds.ini file에는 groups와 content entry 들이 있을 겁니다. 이것들은 section의 순서대로 display 될 겁니다. 만약 1개의 그룹만이 있다면 그 그룹이 display 될 겁니다.

아래는 SITE_DIR/config/MODULE/feedgroups.ini 예제입니다. 각 그룹은 TITLE이 있는 section 입니다. 여러분이 원하는 만큼의 그룹을 만들 수 있습니다.

[applying]
TITLE = "Applying to Universitas"
DESCRIPTION = ""

[visiting]
TITLE = "Visiting"
DESCRIPTION = ""

SITE_DIR/config/MODULE/feeds-applying.ini.  아래는 applying group 예제입니다. feeds.ini file처럼 format 됐습니다.

[admissions]
TITLE = "Admissions"
SUBTITLE = ""
SHOW_TITLE = 0
CONTENT_TYPE = "html_url"
BASE_URL = "http://universitas.modolabs.com/admissions"
HTML_ID = "node-2"

SITE_DIR/config/MODULE/feeds.ini. 

[applying]
TITLE = "Applying to Universitas"
GROUP = "applying"

[visiting]
TITLE = "Visiting"
GROUP = "visiting"

[othercontent]
TITLE = "Other Content"
SUBTITLE = ""
SHOW_TITLE = 0
CONTENT_TYPE = "html_url"
BASE_URL = "http://www.example.com/othercontent"
HTML_ID = "html-id"

Configuration

DatabaseAuthentication authority는 여러 configuration value들을 가지고 있습니다. 모두 optional 입니다. 아래 value들이 데이터베이스에 연결하는데 영향을 미치는 것들입니다.

• DB_TYPE - database system은 PDO를 통해 mysql과 sqlite를 지원합니다. 
• DB_HOST - used by db systems that are hosted on a server
• DB_USER - used by db systems that require a user to authenticate
• DB_PASS - used by db systems that require a password
• DB_DBNAME - used by db systems that require a database
• DB_FILE - used by db systems the use a file (i.e. sqlite).

위 값들 중 빠진 값들은 SITE_DIR/config/site.ini에서 connectivity settings 을 가져와서 디폴트로 사용할 겁니다. 데이터베이스에 query를 어떻게 할지에 대한 여러 옵션들이 있습니다. 이 때 유저와 그룹 모두를 사용할 필요는 없습니다. 한가지만 필요하면 그걸 사용하시면 됩니다.

아래 값들은 데이터가 위치한 데이터베이스 테이블의 authority를 나타냅니다 :

• DB_USER_TABLE - (users) The name of the table that stores the user records. This table should at least have fields for userID, password and email. It can also have fields for first/last name or full name. Each row should contain a single user entry
• DB_GROUP_TABLE (groups) The name of the table that stores group information. It should have fields for shortname and group id. Each row should contain a single group entry.
• DB_GROUPMEMBERS_TABLE - (groupmembers) The name of the table that stores the members of each group, it should have a field for the group name/id and the userID of the user. Each row should contain an entry that contains the group name and userID. The system will search for members that match the group name.

아래 값들은 어떤 필드들을 사용할지에 대해 authority에 알려 줍니다. :

• DB_USER_USERID_FIELD (userID)- stores the userID in the user table. For systems that use the email address as the key, you should include the email field
• DB_USER_PASSWORD_FIELD (password) -stores a hashed value of the user’s password. See DB_USER_PASSWORD_HASH for possible hashing algorithms (Default is md5)
• DB_USER_EMAIL_FIELD (email) - stores the email in the user table
• DB_USER_FIRSTNAME_FIELD (empty) - stores the first name of user. Won’t be used unless it is specified
• DB_USER_LASTNAME_FIELD (empty) - stores the last name of user. Won’t be used unless it is specified
• DB_USER_FULLNAME_FIELD (empty) - stores the full name of user. Won’t be used unless it is specified
• DB_GROUP_GROUPNAME_FIELD (group) - stores the short name of the group in the group table
• DB_GROUP_GID_FIELD - (gid) - stores the group id of the group in the group table. Should be numerical
• DB_GROUPMEMBER_GROUP_FIELD (gid) - which field to use when looking up groups in the group member table. This is typically the same value as the group name or gid field
• DB_GROUPMEMBER_USER_FIELD (userID) - which field to use when looking up user in the group member table. This is typically either the userID or the email
• DB_GROUPMEMBER_AUTHORITY_FIELD - If present you can store the authority index in this field. This allows the system to map group members to other authorities.

다른 값들은 어떻게 그룹 멤버쉽이 키가 되는지를 알려줍니다.

• DB_GROUP_GROUPMEMBER_PROPERTY - (gid) - This is not stored in the database, but refers to which field will be used to look up group information in the group member table. Valid values are gid or group (i.e. the shortname) gid is the default.
• 
  

암호 해싱 방법과 관련한 값들도 있습니다.

• DB_USER_PASSWORD_HASH (md5) - This is a string that represents a valid hashing function. It indicates what

  hashing algorithm is used to store the password. See hash_algos() for a list of valid hashing algorithms. Keep in mind that available algorithms may differ by PHP version and platform. You can also use the hmac_ prefix to use the hmac signing method (i.e. hmac_sha1). This requires setting the DB_USER_PASSWORD_KEY value.

• DB_USER_PASSWORD_KEY (empty) - Necessary if you use the more secure hmac variant hashing algorithms. This uses a shared key to sign the value using hash_hmac

• DB_USER_PASSWORD_SALT_BEFORE (empty) - If present this string will be prepended to any string as a salt value before hashing. This is useful if you are using fixed salts.

• DB_USER_PASSWORD_SALT_AFTER (empty) - If present this string will be appended to any string as a salt value before hashing. This is useful if you are using fixed salts.

• DB_USER_PASSWORD_SALT_FIELD_BEFORE (empty) - If present the value of this field for the user will be prepended to any string as a salt value before hashing. This is useful if you are using variable salts.

• DB_USER_PASSWORD_SALT_FIELD_AFTER (empty) - If present the value of this field for the user will be appended to any string as a salt value before hashing. This is useful if you are using variable salts.

How it Works

Using Default Values

여러분의 reference database를 include 하고 싶으시면 아래와 같이 정의된 테이블의 모든 디폴트 값을 사용할 수 있습니다.

CREATE TABLE users (userID varchar(64), password varchar(32), email varchar(64), 
firstname varchar(50), lastname varchar(50));
CREATE TABLE groups (`group` varchar(16), gid int);
CREATE TABLE groupmembers (gid int, authority varchar(32), userID varchar(64)); 

Setting up Authentication

Authentication은 유저의 identity를 설립하는 프로세스입니다. 이 identity의 설립은 유저가 username과 password를 제공하면서 가능합니다. 프레임워크는 그 유저이름과 패스워드를 받아서 central authority를 통해서 credential을 test 하게 됩니다. 만약 authority가 credential에 적합하면 유저는 로그인 되고 관련된 서비스나 개인 정보를 사용할 수 있게 됩니다.

쿠로고 프레임워크에 의한 Authentication는 한개 이상의 authentication authorities를 통해서 제공 됩니다. 각 authority는 기존의 authentication system에 connect 하기 위해 configure 돼 있습니다. 여러분 사이트의 필요에 따라 여러분은 거기에 맞는 private self-hosted authentication system (like an LDAP/Active Directory or database system) or a public system (Twitter, Facebook, Google) 들을 사용하실 수 있습니다. 또한 standard authentication services (Google Apps) 같이 외부에서 제공되는 서비스를 사용해서 hybrid로 접근할 수도 있습니다. 간단하게 deploy 하려면 external service 필요없이 flat-file based system을 사용할 수도 있습니다.

각 authority는 아래와 같이 다양한 서비스를 제공할 수 있습니다.

• User authentication - either through a direct login/password form or through an external system based on OpenID or OAuth
  
• User attributes - At minimum authorities should supply id, name and email information. Some authorities can provide this information to any user in their system, however others can only provide this information on the logged in user
• Group information and membership - Some authorities will also contain information on groups which allow you to logically organize users. Some authorities are designed to only contain users from their own domains, while others have the ability to utilize users from other authorities in their membership

이 모든 서비스를 다 제공할 필요는 없을 겁니다. 하나의 authority는 authentication과 information을 제공하고 다른 것은 group information을 제공하고 이렇게 여러 방법으로 사용될 수도 있습니다. 만약 여러분이 여러분의 authorization schemes에 group을 지정하지 않았다면 group information은 필요 없게 되겠죠.

Configuration

PasswdAuthentication authority 는 standard에 2개의 value만이 추가 됩니다.

• PASSWD_USER_FILE - a path to the user file. This file can be placed anywhere, but it is recommended to place it in the DATA_DIR folder which is mapped to SITE_DIR/data. i.e. If you use the DATA_DIR constant it should not be in quotes: DATA_DIR”/users”
  
  
• PASSWD_GROUP_FILE - a path to the group file. This file can be placed anywhere, but it is recommended to place it in the DATA_DIR folder which is mapped to SITE_DIR/data. i.e. If you use the DATA_DIR constant it should not be in quotes: DATA_DIR”/groups”

Format of the user file

이 user file은 전형적인 유닉스의 passwd 파일과 그 구조가 비슷합니다.

각 라인은 single user를 말합니다. 빈 줄이나 #로 시작하는 줄은 무시될 겁니다. 각 라인에는 : 로 구분되는 field들이 있습니다. 필드의 순서는 아래와 같습니다.

1. userID - a short name for the user
2. password - an md5 hash of the user’s password (unix users can use md5 -s “password” to generate a hash)
3. email - the email address of the user
4. full name - the full name of the user

Format of the group file

그룹 파일도 유닉스의 그룹파일과 아주 비슷합니다.

각 라인은 single group을 나타냅니다. 빈 줄이나 #로 시작하는 줄은 무시됩니다. 각 라인에서 각 필드들은 : 로 구분 됩니다.

그 필드들의 순서는 아래와 같습니다.

1. group - a short name for the group
2. gid - a numerical id for the group
3. members - a comma separated list of users. Each user is represented by their username/email. If the user is from another authority you should enter it as authority|userID

Usage

이 authority를 사용하는 것은 몇개의 account 만을 다룰 때 유용할 겁니다. 예를 들어 간단하게 username과 password를 가지고 몇개의 모듈만 protect 하기를 원하는 경우가 이것에 해당 될 겁니다.