= V2 & MAPS Setup in Development =

[[V2Master]] - [[V2Deployment]]

  <<TableOfContents>>

= Introduction =

This pages describe how to setup MAPS and V2 systems such that MAPS is used for authentication management for the V2 system.

Overview of procedure:

 1. Setup MAPS and V2 systems
 1. Bootstrap users on the MAPS and V2 systems
 1. Invite a new V2 user, who confirms login and logs in via MAPS

= Setup Procedure =

== Prerequisites ==

 1. Using webbrick in the rails ''development'' environment
 1. Base directories for MAPS and V2, with the appropriate branches, are checked out
 1. Basic MAPS and V2 settings are configured correctly

== Procedure ==

This procedure assumes the following:

 1. MAPS will be accessible at: [[http://localhost:4000|localhost:4000]], git checkout at directory ~/rails/maps
 1. V2 will be accessible at: [[http://localhost:4010|localhost:4010]], git checkout at directory ~/rails/v2p0

'''Steps'''

 1. Configure MAPS and V2
    * See '''V2MapsConfiguration''' for details

 1. Setup and start MAPS, running on port 4000:

    {{{
cd ~/rails/maps
bundle install
bundle exec rake db:drop db:create db:migrate
rails server -p 4000
    }}}

 1. Setup and start V2, running on port 4010:

    {{{
cd ~/rails/maps
bundle install
bundle exec rake db:drop db:create db:migrate db:seed_fu_without_access_control
rails server -p 4010
    }}}

 1. Clear all localhost:4000 and localhost:4010 cookies in the browser

 1. Register a new admin user in MAPS
    1. Open maps: http://localhost:4000
    1. Click menu: '''Login'''
    1. Click link in form: '''Register'''
    1. Enter form information:
       * First name: ''your first name''
       * Last name: ''you last name''
       * Company: '''SoftXS GmbH'''
       * Email: '''maps``@softxs.ch''' -- Ideally use an email address that works. The address maps@softxs.ch works
       * Password: '''12345678''' -- Passwords must be at least 8 characters long
       * Password confirmation: '''12345678'''
    1. Press '''Register'''
    1. MAPS will now attempt to send an email to the email address. The email will contain a URL for confirming the address
    1. To get the confirmation URL do one of the following:
       * Receive the email with the link
       * Look in ~/rails/maps/log/development.log for a copy of it.
       * Get the ''confirmation_token'' from the database with:
         * '''select first_name, last_name, authentication_token from users;'''
       * The confirmation URL should be constructed to look like the following (where the final value is the authentication_token from the database):
       * '''http://localhost:4000/users/confirmation?confirmation_token=3xoqsqQKNi5sAsoarFpb'''
    1. Open the confirmation link, you will be presented with screen with the following message in blue, at the top:
       * ''Your account was successfully confirmed. You are now signed in.''
    1. Grant the '''root''' role to the admin user, using the rails console:
       {{{
rails console
> u = User.find_by_email('maps@softxs.ch')
> u.add_role :root
> y u.roles # Verify the role is really assigned, should see a login role and a root role
       }}}
    1. Verify the root role is working.
       * Click on the '''SoftXS''' (home) link in the upper left-hand of the navbar
       * The home screen should be displayed and an '''Admin''' menu item should appear on the far right
       * Click on menu '''Admin''' --> '''Single Sign On''' --> '''Clients'''
       * An empty clients list should be displayed
       * Verify there is a button '''+ Create New Client'''

 1. Register the V2 application instance in MAPS
    1. Click on menu '''Admin''' --> '''Single Sign On''' --> '''Clients'''
    1. Click '''+ Create New Client''' button
    1. Enter form data:
       * Name: '''v2p0 on port 4010''' -- Can be anything
       * App:  '''V2``P0_Dev''' -- Must match V2 '''Settings.SXS.SSO.AppID'''
       * App secret: -- Choose one the the following:
         * Accept the random key value, and set V2 '''Settings.SXS.SSO.App``Secret''' to match
         * Insert the V2 '''Settings.SXS.SSO.App``Secret''' value
       * Press '''Save'''

 1. Login to V2, using a local identity, and invite a new user
    1. Select one of the following email addresses to use, which are all configured as local identities in V2 and have the password '''12345678'''
       * '''ah@softxs.ch'''
       * '''ds@softxs.ch'''
       * '''tn@softxs.ch'''
    1. Give the selected local_identity user the root role, using the rails console:
       {{{
> u = User.find_by_email('ah@softxs.ch') # Use the selected email address
> u.add_role :root
> y u.roles # Verify the role is really assigned, should see a login role and a root role       }}}
    1. Open V2: http://localhost:4010/local_login and login:
       * The '''Local Login Page''' should be displayed
       * Login using the selected email address and the password '''12345678'''
       * Verify the ''Login'' menu changes it title to the email address and now has sub-entries for ''Logout'' and ''App. Profile''
       * Verify that there is also an '''Admin''' menu to the left of the ''email menu''
    1. Invite a new user.
       * You should use the ''User Invitation'' and '''not''' the ''Admin Invitation'' (which is accessed via menu Admin --> Invitations)
       * Click on ''email menu'' --> '''App. Profile'''
       * The user's application profile will be displayed
       * Click on the '''Invite Someone''' link in ''Quick Links'' box
       * A '''New Invitation''' form will be displayed. Enter form data:
         * Email address:  ''Your email address'' -- Do '''not''' use one of the local identity email addresses. Try and use a valid email address
         * First name:     ''Your first name''
         * Last name:      ''Your last name''
         * Company name:   '''SoftXS GmbH'''
         * Subject:        '''Test subject'''
         * Message:        '''Test message'''
       * Click button '''Save & Send''' button
    1. V2 will now attempt to send an email to the email address. The email will contain a URL for confirming the new user and setting a password
    1. To get the confirmation URL do one of the following:
       * Receive the email with the link
       * Look in ~/rails/v2p0/log/development.log for a copy of it.
       * Get the confirmation_token from the database with:
         * '''select first_name, last_name, authentication_token from users;'''
       * The URL should be constructed to look like the following (where the final value is the authentication_token from the database):
         * http://localhost:4010/invitation_landing?token=caeO6HujcSTTcWjtWJiRFQ
    1. Open the confirmation link, you should be redirected to MAPS (e.g. ''localhost:4000'') and a user profile form should be displayed
       * If you get a ''too many redirects'' error then one of the following could be wrong:
         * You forgot to clear cookies at the start
         * You used one of the local identity user's email address for the invitation
       * In the browsers URL field you should see a very long URL which contains the CGI parameter ''return_to=http...'' (basically the V2 home page)
       * On the right hand side the form should be filled in with the user's name, etc.
       * Enter a password and confirmation password
       * Click button '''Save'''
       * You should be redirected to V2 and be logged in