<commit_before>== Discourse CAS sso app

This app acts as a CAS SSO for instances of discussion tool Discourse. It can connect any number of discourse instances*
to a single cas URL/host.

In addition to doing authentication part it also can use the extra groups attibute of the cas data to control login/account
create to members of certain groups.  Deny overrides Allow in the configureation.

*All discourse instances need to use the same sso secret which is not a great thing. If you control all instances is the
risk is a little bit less but not great.

==Perquisites
 * Functioning CAS server that returns username and email address
 * CAS server is using SSL (for testing you can disable this see [here][1])
 * Read through the first post of [this][2] the Official Single-Sign-On for Discourse

==How it works when setup is:

 1. You hit the login button on your discourse site or the site is set to require login to access.
 2. Discourse packages a payload up containing the url of the discourse site to return to and and light encryption key.
 3. Your browsers is now redirected to the SSO url configured in discourse and the above package is sent allong.
 4. The discourse_cas_sso app receives the package and stores it and redirects you to the CAS server.
 5. When you return to the discourse_cas_sso app there is a package of data from the CAS that lets discourse_cas_sso know that you are logged and at minimum your email address and username.
 6. The email address and username along with other information is packaged up using the encryption key send by discourse and sent back to the discourse using the return url from the original package.
 7. Discourse uses this information to either log the person in by matching the email address or creates a new user with this information and logs them in.


= Configuration

==CAS server setup
===Required Values
You CAS server will need to return at minimum a username and a email address.  
===Optional Values
If you want to use the groups and/or the photo functionality the server will also need to return those values

==cas_sso application setup.
There are two places that you need to enter configuration information.  The first is in config/configation/defaults.rb .
There you will need to set the

* configatron.sso.secret to the value that was set in the discourse(s) instance you are useing
These are the name of the attribute in the cas data. This is particular to you configuration
and you will need to talk to your CAS adminstrator to find out what they are and possibly to active sending them.
* configatron.cas.email_attribute - CAS attribute containing user's e-mail. Example: 'mail' or 'UserPrincipalName'
* configatron.cas.name_attribute - CAS attribute containing user's username. Example: 'nickname' or 'Name'
* configatron.cas.attributes_hash = location that omniauth-cas stores the above two attributes.  Example: :extra or :info
* configatron.cas.avatar_enabled - Specifies whether avatars should be consumed and provided to Discourse.
* configatron.cas.avatar_url_attribute - CAS attribute containing user's photo. Example: 'jpegPhoto'
* configatron.cas.avatar_force_update_attribute -  Discourse parameter specifying whether avatar should be re-downloaded if cached. Discourse does not re-download avatars that have already been downloaded from the same URL. See: https://github.com/discourse/discourse/pull/2670

You will also need to set the cas server host in config/initializers/omniauth.rb

Run the migration.  It will add a db (sqlite) to be used for the eventual SLO support.

Edit the application.html.erb layout file to meet your organizations needs.  Bootstrap is available.


Optional settings config/configation/defaults.rb
You can activate the groups filtering and turn on or off the checking of the allow and deny groups independently. In the case you are using Active Directory as the backend to a Jasig CAS server the groups information will be in the form of LDAP groups.  You mileage may vary with other combinations.  You may also have to get your CAS administrator to activate sending groups information.  The name of the attribute used to access the groups is based on the above configuration also.

You will also want to change the login failure.html.erb page and the application.html.erb layout to suit your organization.

= Thanks
Avatar/photo functionality was written by @jankaltoun .
 

= Unfinished
At this point there is no action an the CAS server sending out SLO requests when user logs out of cas or their session
ends.  To do this will require that discourse adds a /sso/logout that accepts the payload that was sent in the original
sso request.  This will log out just the single session attached to that cas TGT and ST. At this point I do not think
this is possible to do



<commit_msg>Fixed typographical error, changed adminstrator to administrator in README.<commit_after>== Discourse CAS sso app

This app acts as a CAS SSO for instances of discussion tool Discourse. It can connect any number of discourse instances*
to a single cas URL/host.

In addition to doing authentication part it also can use the extra groups attibute of the cas data to control login/account
create to members of certain groups.  Deny overrides Allow in the configureation.

*All discourse instances need to use the same sso secret which is not a great thing. If you control all instances is the
risk is a little bit less but not great.

==Perquisites
 * Functioning CAS server that returns username and email address
 * CAS server is using SSL (for testing you can disable this see [here][1])
 * Read through the first post of [this][2] the Official Single-Sign-On for Discourse

==How it works when setup is:

 1. You hit the login button on your discourse site or the site is set to require login to access.
 2. Discourse packages a payload up containing the url of the discourse site to return to and and light encryption key.
 3. Your browsers is now redirected to the SSO url configured in discourse and the above package is sent allong.
 4. The discourse_cas_sso app receives the package and stores it and redirects you to the CAS server.
 5. When you return to the discourse_cas_sso app there is a package of data from the CAS that lets discourse_cas_sso know that you are logged and at minimum your email address and username.
 6. The email address and username along with other information is packaged up using the encryption key send by discourse and sent back to the discourse using the return url from the original package.
 7. Discourse uses this information to either log the person in by matching the email address or creates a new user with this information and logs them in.


= Configuration

==CAS server setup
===Required Values
You CAS server will need to return at minimum a username and a email address.  
===Optional Values
If you want to use the groups and/or the photo functionality the server will also need to return those values

==cas_sso application setup.
There are two places that you need to enter configuration information.  The first is in config/configation/defaults.rb .
There you will need to set the

* configatron.sso.secret to the value that was set in the discourse(s) instance you are useing
These are the name of the attribute in the cas data. This is particular to you configuration
and you will need to talk to your CAS administrator to find out what they are and possibly to active sending them.
* configatron.cas.email_attribute - CAS attribute containing user's e-mail. Example: 'mail' or 'UserPrincipalName'
* configatron.cas.name_attribute - CAS attribute containing user's username. Example: 'nickname' or 'Name'
* configatron.cas.attributes_hash = location that omniauth-cas stores the above two attributes.  Example: :extra or :info
* configatron.cas.avatar_enabled - Specifies whether avatars should be consumed and provided to Discourse.
* configatron.cas.avatar_url_attribute - CAS attribute containing user's photo. Example: 'jpegPhoto'
* configatron.cas.avatar_force_update_attribute -  Discourse parameter specifying whether avatar should be re-downloaded if cached. Discourse does not re-download avatars that have already been downloaded from the same URL. See: https://github.com/discourse/discourse/pull/2670

You will also need to set the cas server host in config/initializers/omniauth.rb

Run the migration.  It will add a db (sqlite) to be used for the eventual SLO support.

Edit the application.html.erb layout file to meet your organizations needs.  Bootstrap is available.


Optional settings config/configation/defaults.rb
You can activate the groups filtering and turn on or off the checking of the allow and deny groups independently. In the case you are using Active Directory as the backend to a Jasig CAS server the groups information will be in the form of LDAP groups.  You mileage may vary with other combinations.  You may also have to get your CAS administrator to activate sending groups information.  The name of the attribute used to access the groups is based on the above configuration also.

You will also want to change the login failure.html.erb page and the application.html.erb layout to suit your organization.

= Thanks
Avatar/photo functionality was written by @jankaltoun .
 

= Unfinished
At this point there is no action an the CAS server sending out SLO requests when user logs out of cas or their session
ends.  To do this will require that discourse adds a /sso/logout that accepts the payload that was sent in the original
sso request.  This will log out just the single session attached to that cas TGT and ST. At this point I do not think
this is possible to do




{'fraction_non_alphanumeric': 0.03577706545341743, 'fraction_numerical': 0.0026884500051700963, 'mean_word_length': 4.291028446389497, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4955005', 'n_tokens_mistral': 2436, 'n_tokens_neox': 2310, 'n_words': 1490}