diff options
Diffstat (limited to 'docs/content/doc/features')
| -rw-r--r-- | docs/content/doc/features/authentication.en-us.md | 194 | ||||
| -rw-r--r-- | docs/content/doc/features/authentication.zh-cn.md | 18 | ||||
| -rw-r--r-- | docs/content/doc/features/authentication.zh-tw.md | 18 | ||||
| -rw-r--r-- | docs/content/doc/features/localization.en-us.md | 18 | ||||
| -rw-r--r-- | docs/content/doc/features/localization.zh-cn.md | 18 | ||||
| -rw-r--r-- | docs/content/doc/features/localization.zh-tw.md | 18 | ||||
| -rw-r--r-- | docs/content/doc/features/webhooks.en-us.md | 103 | ||||
| -rw-r--r-- | docs/content/doc/features/webhooks.zh-cn.md | 18 | ||||
| -rw-r--r-- | docs/content/doc/features/webhooks.zh-tw.md | 18 |
9 files changed, 423 insertions, 0 deletions
diff --git a/docs/content/doc/features/authentication.en-us.md b/docs/content/doc/features/authentication.en-us.md new file mode 100644 index 0000000000..37a0d6fa87 --- /dev/null +++ b/docs/content/doc/features/authentication.en-us.md @@ -0,0 +1,194 @@ +--- +date: "2016-12-01T16:00:00+02:00" +title: "Authentication" +slug: "authentication" +weight: 10 +toc: true +draft: false +menu: + sidebar: + parent: "features" + name: "Authentication" + weight: 10 + identifier: "authentication" +--- + +--- +name: Authentication +--- + +# Authentication + +## LDAP (Lightweight Directory Access Protocol) + +Both the LDAP via BindDN and the simple auth LDAP share the following fields: + +- Authorization Name **(required)** + - A name to assign to the new method of authorization. + +- Host **(required)** + - The address where the LDAP server can be reached. + - Example: `mydomain.com` + +- Port **(required)** + - The port to use when connecting to the server. + - Example: `389` for LDAP or `636` for LDAP SSL + +- Enable TLS Encryption (optional) + - Whether to use TLS when connecting to the LDAP server. + +- Admin Filter (optional) + - An LDAP filter specifying if a user should be given administrator + privileges. If a user account passes the filter, the user will be + privileged as an administrator. + - Example: `(objectClass=adminAccount)` + - Example for Microsoft Active Directory (AD): `(memberOf=CN=admin-group,OU=example,DC=example,DC=org)` + +- Username attribute (optional) + - The attribute of the user's LDAP record containing the user name. Given + attribute value will be used for new Gitea account user name after first + successful sign-in. Leave empty to use login name given on sign-in form. + - This is useful when supplied login name is matched against multiple + attributes, but only single specific attribute should be used for Gitea + account name, see "User Filter". + - Example: `uid` + - Example for Microsoft Active Directory (AD): `sAMAccountName` + +- First name attribute (optional) + - The attribute of the user's LDAP record containing the user's first name. + This will be used to populate their account information. + - Example: `givenName` + +- Surname attribute (optional) + - The attribute of the user's LDAP record containing the user's surname. + This will be used to populate their account information. + - Example: `sn` + +- E-mail attribute **(required)** + - The attribute of the user's LDAP record containing the user's email + address. This will be used to populate their account information. + - Example: `mail` + +**LDAP via BindDN** adds the following fields: + +- Bind DN (optional) + - The DN to bind to the LDAP server with when searching for the user. This + may be left blank to perform an anonymous search. + - Example: `cn=Search,dc=mydomain,dc=com` + +- Bind Password (optional) + - The password for the Bind DN specified above, if any. _Note: The password + is stored in plaintext at the server. As such, ensure that your Bind DN + has as few privileges as possible._ + +- User Search Base **(required)** + - The LDAP base at which user accounts will be searched for. + - Example: `ou=Users,dc=mydomain,dc=com` + +- User Filter **(required)** + - An LDAP filter declaring how to find the user record that is attempting to + authenticate. The `%s` matching parameter will be substituted with login + name given on sign-in form. + - Example: `(&(objectClass=posixAccount)(uid=%s))` + - Example for Microsoft Active Directory (AD): `(&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName=%s)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))` + - To substitute more than once `%[1]s` should be used instead, e.g. when + matching supplied login name against multiple attributes such as user + identifier, email or even phone number. + - Example: `(&(objectClass=Person)(|(uid=%[1]s)(mail=%[1]s)(mobile=%[1]s)))` + +**LDAP using simple auth** adds the following fields: + +- User DN **(required)** + - A template to use as the user's DN. The `%s` matching parameter will be substituted with login name given on sign-in form. + - Example: `cn=%s,ou=Users,dc=mydomain,dc=com` + - Example: `uid=%s,ou=Users,dc=mydomain,dc=com` + +- User Filter **(required)** + - An LDAP filter declaring when a user should be allowed to log in. The `%s` + matching parameter will be substituted with login name given on sign-in + form. + - Example: `(&(objectClass=posixAccount)(cn=%s))` + - Example: `(&(objectClass=posixAccount)(uid=%s))` + +**Verify group membership in LDAP** uses the following fields: + +* Group Search Base (optional) + * The LDAP DN used for groups. + * Example: `ou=group,dc=mydomain,dc=com` + +* Group Name Filter (optional) + * An LDAP filter declaring how to find valid groups in the above DN. + * Example: `(|(cn=gitea_users)(cn=admins))` + +* User Attribute in Group (optional) + * Which user LDAP attribute is listed in the group. + * Example: `uid` + +* Group Attribute for User (optional) + * Which group LDAP attribute contains an array above user attribute names. + * Example: `memberUid` + +## PAM (Pluggable Authentication Module) + +To configure this you just need to set the 'PAM Service Name' to a filename in `/etc/pam.d/`. +If you want it to work with normal Linux passwords, the user running Gitea must have read access to `/etc/shadow`. + +## SMTP (Simple Mail Transfer Protocol) + +This option allows Gitea to log in to your SMTP host as a Gitea user. To configure this, simply set the fields below: + +- Authentication Name **(required)** + - A name to assign to the new method of authorization. + +- SMTP Authentication Type **(required)** + - Type of authentication for use on your SMTP host, PLAIN or LOGIN. + +- Host **(required)** + - The address where the SMTP host can be reached. + - Example: `smtp.mydomain.com` + +- Port **(required)** + - The port to use when connecting to the server. + - Example: `587` + +- Allowed Domains + - Restrict what domains can log in if you're using public SMTP host or SMTP host with multiple domains. + - Example: `gitea.io,mydomain.com,mydomain2.com` + +- Enable TLS Encryption + - Enable TLS encryption on authentication. + +- Skip TLS Verify + - Disable TLS verify on authentication. + +- This authentication is activate + - Enable or disable this auth. + +## FreeIPA + +- In order to log in to Gitea using FreeIPA credentials, you need to create a bind account for Gitea to use: + +- On the FreeIPA server, create a `gitea.ldif` file, replacing `dc=example,dc=com` with your DN, and providing an appropriately secure password: +``` + dn: uid=gitea,cn=sysaccounts,cn=etc,dc=example,dc=com + changetype: add + objectclass: account + objectclass: simplesecurityobject + uid: gitea + userPassword: secure password + passwordExpirationTime: 20380119031407Z + nsIdleTimeout: 0 +``` + +- Import the LDIF (change localhost to an IPA server if needed), you’ll be prompted for your Directory Manager password: +``` + ldapmodify -h localhost -p 389 -x -D \ + "cn=Directory Manager" -W -f gitea.ldif +``` +- Add an IPA group for gitea_users : +``` + ipa group-add --desc="Gitea Users" gitea_users +``` +- Note: If you get an error about IPA credentials, please run `kinit admin` and give your admin account password. + +- Now login to the Gitea as an Administrator, click on "Authentication" under Admin Panel. Then click `Add New Source` and fill in the details, changing all where appropriate to your own domain. diff --git a/docs/content/doc/features/authentication.zh-cn.md b/docs/content/doc/features/authentication.zh-cn.md new file mode 100644 index 0000000000..4ed913320c --- /dev/null +++ b/docs/content/doc/features/authentication.zh-cn.md @@ -0,0 +1,18 @@ +--- +date: "2016-12-01T16:00:00+02:00" +title: "认证" +slug: "authentication" +weight: 10 +toc: true +draft: false +menu: + sidebar: + parent: "features" + name: "认证" + weight: 10 + identifier: "authentication" +--- + +# 认证 + +## TBD diff --git a/docs/content/doc/features/authentication.zh-tw.md b/docs/content/doc/features/authentication.zh-tw.md new file mode 100644 index 0000000000..4dd0248970 --- /dev/null +++ b/docs/content/doc/features/authentication.zh-tw.md @@ -0,0 +1,18 @@ +--- +date: "2016-12-01T16:00:00+02:00" +title: "認證" +slug: "authentication" +weight: 10 +toc: true +draft: false +menu: + sidebar: + parent: "features" + name: "認證" + weight: 10 + identifier: "authentication" +--- + +# 認證 + +## TBD diff --git a/docs/content/doc/features/localization.en-us.md b/docs/content/doc/features/localization.en-us.md new file mode 100644 index 0000000000..1bb7beff82 --- /dev/null +++ b/docs/content/doc/features/localization.en-us.md @@ -0,0 +1,18 @@ +--- +date: "2016-12-01T16:00:00+02:00" +title: "Localization" +slug: "localization" +weight: 10 +toc: true +draft: false +menu: + sidebar: + parent: "features" + name: "Localization" + weight: 20 + identifier: "localization" +--- + +# Localization + +## TBD diff --git a/docs/content/doc/features/localization.zh-cn.md b/docs/content/doc/features/localization.zh-cn.md new file mode 100644 index 0000000000..81de966ea2 --- /dev/null +++ b/docs/content/doc/features/localization.zh-cn.md @@ -0,0 +1,18 @@ +--- +date: "2016-12-01T16:00:00+02:00" +title: "本地化" +slug: "localization" +weight: 10 +toc: true +draft: false +menu: + sidebar: + parent: "features" + name: "本地化" + weight: 20 + identifier: "localization" +--- + +# 本地化 + +## TBD diff --git a/docs/content/doc/features/localization.zh-tw.md b/docs/content/doc/features/localization.zh-tw.md new file mode 100644 index 0000000000..534ff89f42 --- /dev/null +++ b/docs/content/doc/features/localization.zh-tw.md @@ -0,0 +1,18 @@ +--- +date: "2016-12-01T16:00:00+02:00" +title: "在地化" +slug: "localization" +weight: 10 +toc: true +draft: false +menu: + sidebar: + parent: "features" + name: "在地化" + weight: 20 + identifier: "localization" +--- + +# Localization + +## TBD diff --git a/docs/content/doc/features/webhooks.en-us.md b/docs/content/doc/features/webhooks.en-us.md new file mode 100644 index 0000000000..5fad688194 --- /dev/null +++ b/docs/content/doc/features/webhooks.en-us.md @@ -0,0 +1,103 @@ +--- +date: "2016-12-01T16:00:00+02:00" +title: "Webhooks" +slug: "webhooks" +weight: 10 +toc: true +draft: false +menu: + sidebar: + parent: "features" + name: "Webhooks" + weight: 30 + identifier: "webhooks" +--- + +# Webhooks + +Gitea supports web hooks for repository events, you can find it in settings page(`/:username/:reponame/settings/hooks`). All event pushes are POST requests, and we currently support two formats: Gitea and Slack. + +### Event information + +Following shows an example of event information that will be sent by Gitea to Payload URL: + + +``` +X-Github-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 +X-Github-Event: push +X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 +X-Gogs-Event: push +X-Gitea-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 +X-Gitea-Event: push +``` + +```json +{ + "secret": "3gEsCfjlV2ugRwgpU#w1*WaW*wa4NXgGmpCfkbG3", + "ref": "refs/heads/develop", + "before": "28e1879d029cb852e4844d9c718537df08844e03", + "after": "bffeb74224043ba2feb48d137756c8a9331c449a", + "compare_url": "http://localhost:3000/gitea/webhooks/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a", + "commits": [ + { + "id": "bffeb74224043ba2feb48d137756c8a9331c449a", + "message": "Webhooks Yay!", + "url": "http://localhost:3000/gitea/webhooks/commit/bffeb74224043ba2feb48d137756c8a9331c449a", + "author": { + "name": "Gitea", + "email": "someone@gitea.io", + "username": "gitea" + }, + "committer": { + "name": "Gitea", + "email": "someone@gitea.io", + "username": "gitea" + }, + "timestamp": "2017-03-13T13:52:11-04:00" + } + ], + "repository": { + "id": 140, + "owner": { + "id": 1, + "login": "gitea", + "full_name": "Gitea", + "email": "someone@gitea.io", + "avatar_url": "https://localhost:3000/avatars/1", + "username": "gitea" + }, + "name": "webhooks", + "full_name": "gitea/webhooks", + "description": "", + "private": false, + "fork": false, + "html_url": "http://localhost:3000/gitea/webhooks", + "ssh_url": "ssh://gitea@localhost:2222/gitea/webhooks.git", + "clone_url": "http://localhost:3000/gitea/webhooks.git", + "website": "", + "stars_count": 0, + "forks_count": 1, + "watchers_count": 1, + "open_issues_count": 7, + "default_branch": "master", + "created_at": "2017-02-26T04:29:06-05:00", + "updated_at": "2017-03-13T13:51:58-04:00" + }, + "pusher": { + "id": 1, + "login": "gitea", + "full_name": "Gitea", + "email": "someone@gitea.io", + "avatar_url": "https://localhost:3000/avatars/1", + "username": "gitea" + }, + "sender": { + "id": 1, + "login": "gitea", + "full_name": "Gitea", + "email": "someone@gitea.io", + "avatar_url": "https://localhost:3000/avatars/1", + "username": "gitea" + } +} +``` diff --git a/docs/content/doc/features/webhooks.zh-cn.md b/docs/content/doc/features/webhooks.zh-cn.md new file mode 100644 index 0000000000..d3bb4797b0 --- /dev/null +++ b/docs/content/doc/features/webhooks.zh-cn.md @@ -0,0 +1,18 @@ +--- +date: "2016-12-01T16:00:00+02:00" +title: "Webhooks" +slug: "webhooks" +weight: 10 +toc: true +draft: false +menu: + sidebar: + parent: "features" + name: "Webhooks" + weight: 30 + identifier: "webhooks" +--- + +# Webhooks + +## TBD diff --git a/docs/content/doc/features/webhooks.zh-tw.md b/docs/content/doc/features/webhooks.zh-tw.md new file mode 100644 index 0000000000..d3bb4797b0 --- /dev/null +++ b/docs/content/doc/features/webhooks.zh-tw.md @@ -0,0 +1,18 @@ +--- +date: "2016-12-01T16:00:00+02:00" +title: "Webhooks" +slug: "webhooks" +weight: 10 +toc: true +draft: false +menu: + sidebar: + parent: "features" + name: "Webhooks" + weight: 30 + identifier: "webhooks" +--- + +# Webhooks + +## TBD |