The City Authentication Service v.1.0

Introduction

The City authentication service is a provider that allows outside applications to verify identity and get information about a user. The process involves authenticating a user using OAuth2 and then using the resulting OAuth2 token to get information about a user by calling an API endpoint that requires the token. An application that wants to authenticate with this service requires an OAuth2 application id and secret, which is associated with a City Plugin.

Authentication Scenarios

There are two scenarios with The City that can be used with the authentication service and City Plugin.

Outside Application Authentication

This scenario involves having an external application (that exists completely outside The City) that allows its users to use their City credentials to log into the application. Generally, when a user navigates to the login page of the external application, they are redirected to the The City authentication service login page. The user logs into the Auth service, and is then redirected back to the originating external application. The application then uses information passed back by the authentication service to verify that the user logged in successfully, at which point they would be successfully logged into the external application.

iFrame application

This scenario involves an external application that presents content to a City user within the context of The City. This is accomplished using an IFrame to the external application that is surrounded by The City navigation chrome. Generally, a user would NOT receive a prompt to login into the application if they are already logged into The City. They would instead be logged into the application automatically. The first time the user accesses the application, they will be prompted to approve the application using an approval dialog box. The approval dialog box will inform the user what information will be shared with the application. This happens only on the first access of the plugin by the user.

An example plugin for The City can be found here

Authentication from Outside The City

An application authenticates from the outside by redirecting to The City and following the standard OAuth2 methodology. Then the application calls an API Endpoint with an oAuth2 token to get information about the user.

The process starts by redirecting the user to the following URL:

https://authentication.onthecity.org/oauth/authorize?response_type=code&client_id=XXXXXXXXXXXXXX&redirect_uri=XXXXXXXXXXXXXX&state=XXXXXXXXXXXXXXX&scope=user_basic+user_extended"
Parameters Values Description
response_type code Use a value of code
client_id City Plugin APP_ID The application oAuth2 APP_ID obtained from The City Plugin
redirect_uri City Plugin redirect_uri The application redirect_uri that was supplied to the City Plugin. After user authentication, they will be redirected to this url with the access grant
state any string pass through parameter passed in by the application and passed back by the Auth service
scope user_basic, user_extended, user_permissions, group_content Access level requested by the application

This GET request will return an access grant which can be used to get an access token, which can then be used to get more information about the user. The return will have this format:

https://[redirect_uri]?code=XXXXXXXXXXXXXXXX&state=4834b4ea39b3a593057281687aa228bcd7217a0d9c47499a
Field Description
code Grant token to be used to get access token
state Passed back state value, can be used to check the validity of the redirect at the client side

Once the grant code is obtained, it can be used to get the access token. The client will POST to the following URL:

https://authentication.onthecity.org/oauth/token
Parameters Values Description
grant_type authorization_code the grant type, must be authorization_code
code code grant code returned from the initial call and redirect
client_id City Plugin APP_ID The application oAuth2 APP_ID obtained from The City Plugin
client_secret City Plugin APP_SECRET The application oAuth2 APP_SECRET obtained from The City Plugin
redirect_uri City Plugin redirect_uri The application redirect_uri that was supplied to the City Plugin. After user authentication they will be redirected to this url with the access grant

Once the application id and secret have been created, the following API can be called to get information about the user:

https://authentication.onthecity.org/authorization?access_token=XXXXXXXXXXXXXX

This api call will give you basic information about the User, the information returned is determined by the scope that was asked for by the application. See the section on scopes to see what information is returned from this API call

There are Ruby and PHP oAuth strategies available on The City Github page

Authentication from Inside The City for Iframe Plugin

NOTE: This functionality is currently in Beta, and must be turned on specifically for your account. Please contact The City for more information.

Plugin Configuration

A Church has the ability to create a City Plugin that is local to their City church account. A church created plugin can be used by the City account that has created the plugin but not by any other City account.

To create a City Plugin:

  1. Log in as a City Account Admin
  2. Navigate to the admin side of The City
  3. Click on "API" on the left navigation menu
  4. Click on "Plugins" on the left sub-menu
  5. Click on "+ Create plugin" at the top of the page
  6. Fill in the form fields
    1. Title - field identifying the plugin (Required for outside app and iframe app)
    2. URL - uri for the iFrame on the user side of the City (Required only for iframe app)
    3. Admin URL - uri for the iFrame on the Admin side of The City (Required only for iframe app)
    4. SSL? - Check if SSL is required to access the application from the iFrame (Always true after Dec 1, 2015 outside of sandbox)
    5. File - icon file for the plugin (used in the navigation menu for the plugin) (Optional for iframe app)
    6. Callback URI - the URI to redirect the user to after they have authenticated with the Auth service (Required for outside app and iframe app)
  7. Click the "Create" button
  8. Once successfully created, click on the "edit" link next to the plugin in the plugin list
  9. The OAuth2 App ID and Secret will be listed near the bottom of the screen

Once the plugin is successfully created, it must be installed to apply it to your account.

  1. Log in as a City Account Admin
  2. Navigate to the admin side of The City
  3. Click on "Plugins" on the left navigation menu
  4. Find the created Plugin in the "Available Church Plugins" section of The City
  5. Click "Install"
  6. Fill in the form fields
    1. Name - Name users will see in the navigation menu (Required for outside app and iframe app)
    2. Status - choose the status of the plugin (Required for outside app and iframe app)
      1. Live - all users can see the plugin in their City navigation menu
      2. Sandbox - only "staff" users can see the plugin in their City navigation menu
      3. Off - no users can see it in their City navigation menu
    3. Group Assignment - assign the plugin to a group so only users in that group will have access to the application (Optional for iframe app)
  7. Click the "Create" button

Plugin Implementation

Once a registered iFrame application is installed by a City Admin on a particular City, it can be accessed by Users from inside The City. The application will present its content to The City user inside an iFrame, while the City Navigation chrome will continue to be present.

In this case, the App Definition in The City includes a URL to the third party app that The City will open in the iFrame. The City will generate an HTTP post to the specified URL and will post encrypted information about the User along with an oAuth token. The City will essentially take care of the authorization process on behalf of the 3rd party application. The App Definition will also have a scope(s) defined as part of the application that will determine what information gets passed to the application itself as part of the post parameters.

The following parameters will be posted to the third party application:

  • city_data - encrypted JSON structure of information about the User
  • city_data_iv - initialization vector for decrypting the encrypted JSON data

Once Decrypted, the city_data JSON structure contains the following information (this is an example):


{"oauth_token"=>"a0398b2408d07e2a05441ce4cefca1be20735e3e7e5f212bbaeb0d6d228c97eb",
  "user_id"=>23838500,
  "subdomain"=>"local",
  "global_user_id"=>91145572,
  "account_id"=>1}

The token can be used to call additional City APIs to find more information about the user. See the section on scopes to see what an API call will return.

Example Ruby Code to Decrypt City Data passed to iFrame application:

  def decrypt_city_data(city_data, city_data_iv)
    if city_data.present?
      string_to_decrypt = Base64.urlsafe_decode64(city_data)
      iv = Base64.urlsafe_decode64(city_data_iv)
      json_data = city_decrypt(string_to_decrypt, THE_CITY_APP_SECRET.first(32), iv)
      return ActiveSupport::JSON.decode(json_data)
    else
      return {}
    end
  end

  def city_decrypt(encrypted_data, key, iv, cipher_type = "AES-256-CBC")
    aes = OpenSSL::Cipher::Cipher.new(cipher_type)
    aes.decrypt
    aes.key = key
    aes.iv = iv if iv != nil
    aes.update(encrypted_data) + aes.final
  end
There are Ruby, Node, and PHP plugins available on The City Github page that will decrypt the posted parameters.

Plugin iFrame resizing

The City uses an iFrame to present content from a different application while maintaining the City navigation chrome that renders around the iFrame. The iFrame has a fixed width of 786px. The height of the iFrame can be adjusted by the external application by using the JavaScript window.postMessage function for cross domain communication. More information on this method can be found here: postMessage

The only message that is valid is a integer number, which will be used to scale the height of the iFrame window. All other messages will be ignored.

Here is some code that can be used to resize the iFrame window: Example iFrame Code

There is an additional library available on The City Github page here

Scopes

The APIs that are accessible and the information they returned are governed by the currently available OAuth2 scopes in The City. The following is the current list of scopes and what functionality/data is allowed with each scope:

Scope APIs Values
user_basic https://authentication.onthecity.org/authorization?access_token=XXXXXXXXXXXXXXX
https://api.onthecity.org/me
global_user_id, user_id, first_name, last_name profile_picture, account_id
user_extended https://authentication.onthecity.org/authorization?access_token=XXXXXXXXXXXXXXX
https://api.onthecity.org/me
user_basic fields + email, gender, birthdate
user_public_addresses https://authentication.onthecity.org/authorization?access_token=XXXXXXXXXXXXXXX
https://api.onthecity.org/me
a users listed public addresses
user_private_addresses https://authentication.onthecity.org/authorization?access_token=XXXXXXXXXXXXXXX
https://api.onthecity.org/me
a users listed private and public addresses
user_permissons https://authentication.onthecity.org/authorization?access_token=XXXXXXXXXXXXXXX
https://api.onthecity.org/me/permissions
user_extended fields + admin_privileges
group_content https://api.onthecity.org/me/permissions
https://api.onthecity.org/me/groups

https://api.onthecity.org/groups/{ID}/{content_type} (POST - create)

https://api.onthecity.org/{content_type} /{ID} (GET - show)
https://api.onthecity.org/{content_type} /{ID} (POST - update)
https://api.onthecity.org/{content_type} /{ID} (DELETE - destroy)

{content_type} = topics, events, needs, prayers
groups a user is in, plus the ability to view and create a users content (you will NOT be able to view other's content, i.e., responses)