INACTIVE

Census has been decommissioned as of January 2022. It is no longer used by any Turing application.

---

Census - An Identity Manager

Census serves as a central location for identity management and authentication across the Turing School community.

Table of Contents

• Onboarding Tips
  • Heroku
  • FAQ
• Requirements
  • Ruby on Rails
  • Environment Variables
  • Paperclip gem
• Installation
• API Endpoints
• Register an Application
  • Gems
• Roles
  • Permissions
  • Flags
• Maintainer
  • Original Contributors
• Contribute
• License

Onboarding tips

Heroku

• staging: census-app-staging and login-staging.turing.edu
• production: turing-census and login.turing.edu
• Other teams will use the staging app for their staging environment. Switching between environments requires configuring the oauth gem oauth endpoint. Install the gem via:

gem 'omniauth-census', git: "https://github.com/turingschool-projects/omniauth-census"

• There will be two apps connected to the same repository, staging auto deploys from the staging branch, and production auto deploys from master.

FAQ

• What's up with these tokens?
  • Be aware that app specific tokens expire every 90 days. Doorkeeper provides a way to grab a refresh token so your session isn't interupted. If your app requires programatic access on behalf of the app (as opposed to on behalf of a specific user) token refresh logic will need to be included.

Requirements

Environment Variables

Census is built to expect a certain number of environment variables. We suggest using something like Figaro to set them securely.

You will need an AWS S3 Bucket, Access Key ID, a Secret Access Key and an AWS region defined. Use the AWS SDK gem to get started.

Environment Variables:

SALT # used for salting email invite tokens. Can be any random string.
MY_EMAIL # used for testing purposes. Can be any email.
S3_BUCKET_NAME # Not needed in development
AWS_ACCESS_KEY_ID # Not needed in development
AWS_SECRET_ACCESS_KEY # Not needed in development
AWS_REGION # Not needed in development

Paperclip Gem

Census uses the Paperclip gem in order to upload user profile photos. To ensure testing and development works, ImageMagick must be installed and Paperclip must have access to it.

If you're on Mac OS X, you'll want to run the following with Homebrew:

brew install imagemagick

Other services

Census depends on Enroll's API to fetch Cohort data. This access is performed via a GraphQL client pointed at ENROLL_GRAPHQL_ENDPOINT (defaulted to having Enroll running on localhost:3001 and authorized via the API_AUTH_SECRET env var. Census tests mock out this dependency.

Installation

To install, clone down the project and run the following commands:

bundle install
bundle exec rake db:{create,migrate}

To run development locally, use the command:

rails server

To get some helpful user accounts to play around in development:

bundle exec rake db:seed

This will create the following users, all with the password password:

• An Admin user with the email admin@example.com
• A Student with an email of j.s@example.com
• A Student with an email of a.s@example.com
• A Student with an email of b.g@example.com

More info in seeds.rb

API Endpoints

To hit the Census API, you need to send an access_token as a param. This is the token that you get back with the users credentials during the OAuth handshake. That will look something like user_credentials['token'] depending on the variable that you use to store the response.

To receive a user by name:

GET 'https://census-app-staging.herokuapp.com/api/v1/users/by_name?q=[NAME]'

To receive all users by cohort:

GET 'https://census-app-staging.herokuapp.com/api/v1/users/by_cohort?cohort_id=<ID>'

You can use the api/v1/cohorts endpoint to find cohort ids.

To receive a user by ID:

GET 'https://census-app-staging.herokuapp.com/api/v1/users/:id'

To receive all users:

GET 'https://census-app-staging.herokuapp.com/api/v1/users/'

To receive your own user credentials:

GET 'https://census-app-staging.herokuapp.com/api/v1/user_credentials'

To receive a user's credentials by github username:

GET 'https://census-app-staging.herokuapp.com/api/v1/find_by_github?q=github_username'

The user endpoints return JSON in this format:

{
  "id": 55,
  "first_name": "Channa",
  "last_name": "Golan",
  "cohort": "1608-BE",
  "image_url": "https://census-app-staging.herokuapp.com/images/original/missing.png",
  "email": "Channa.Golan@example.com",
  "slack": "channa55",
  "twitter": "chanana",
  "linked_in": "channa-golan",
  "git_hub": "golen5000",
  "groups": [],
  "roles": [
    "active student"
  ]
}

To receive all cohorts:

GET 'https://census-app-staging.herokuapp.com/api/v1/cohorts'

The cohort endpoints return JSON in this format:

[{"id"=>30, "name"=>"1608-BE", "created_at"=>"2017-02-23T16:38:39.134Z", "updated_at"=>"2017-02-23T16:38:39.134Z", "status"=>"active"},
 {"id"=>31, "name"=>"1606-FE", "created_at"=>"2017-02-23T16:38:39.145Z", "updated_at"=>"2017-02-23T16:38:39.145Z", "status"=>"finished"}]

Register an Application

Census uses Devise, Doorkeeper and cancancan to manage authentication and authorization.

To Get a token, register your app through Census and then make a request:

Source here.

Developers can use any HTTP library to make the request (such as Faraday) or use Census::Client.generate_token from the client gem.

conn.post do |req|
  req.url '/oauth/token'
  req.params['grant_type'] = 'client_credentials'
  req.params['client_id'] = ENV['CENSUS_CLIENT_ID'] #=> provided by census interface
  req.params['client_secret'] = ENV['CENSUS_SECRET_ID'] #=> provided by census interface
end

This request will generate a token for your application.

Gems

omniauth-census can be used to configure oauth in application. See its README for instructions on how to use it against different Census environments.

Roles

Some roles are just a flag for querying, others define your permissions on the site. Below is a list of all the currently available roles.
Note that the staging server is messy and roles may be incorrect for some users. Contact an admin if you need to change your permissions.
Roles are changed according to cohort status. For example, when an active cohort is moved to finished, all the "active student"s in that cohort will be moved to "graduated." "Removed" and "exited" students roles will not be effected.

Permissions

• Admin

  • Can crud all aspects of users.
  • Can manage applications
  • Can make applications including the admin scope

• Staff / Active Student / Graduated / Mentor

  • Can read and update their own personal info.
  • Can join public groups.
  • Can read cohort information (view cohort pages).
  • Can manage applications

• Enrolled

  • Can read and update their own personal info.
  • Can read cohort information (view cohort pages).

• Exited / Removed

  • Can't do anything

Flags

• Instructor

Running in a Docker container

Want to run this app without all the pain?! Get on the Docker train!

1. Install Docker for Mac
2. cd into this project's root folder
3. Run docker network create turing-network
4. Run docker-compose up --build
5. wait
6. Run docker-compose exec website rake db:create db:schema:load db:test:prepare
7. visit 0.0.0.0:3010
8. You're running on Docker

CI and Deployment

The app builds on CircleCI and auto deploys green staging branches to staging and green master branches to production.

License

Census is released under the MIT License.