Steps for Application Registration
To integrate with the SSO platform, the application needs to be registered in the SSO platform. The steps for the registration and other required tasks are given below:
Step 1 : Get started with Application Registration
Client applications which need to be integrated with the N-DOPTOR SSO system must be registered in the SSO system by using the provided URL.
Following information need to provide in the registration form:
Name | Description |
---|---|
System Name | Name of the application. |
System Name Bangla | Application should be given in Bangla. |
System URL | The application URL is needed from where service will be provided. |
Redirect URL | The Redirect URL is needed. Because after processing n-doptor sso will redirect to this URL. |
Default Page URL | A Default Page URL is needed for the redirection mechanism. |
Logout URL | A Logout URL is needed for the user to logout from the system. |
Mobile No | A Logout URL is needed for the user to logout from the system. |
Email Address | Email Address is needed to get application code for services. |
Notification Medium | Notification Mechanism can be chosen from Mobile No or Email. |
System Icon | An application icon can be provided which is not mandatory. |
After application submissions, N-DOPTOR Administrator will review and verify the submitted applications and can approve or reject them.
Step 2 : Application credentials
If the client application is approved by the System Administrator, an email and a sms will be sent to the respective applications email and phone number.
The email will contain client-id and password for the client which is required to access the N-DOPTOR APIs.
Step 3 : SSO widget
There are numerous benefits to consider when we go for SSO in a platform like N-Doptor:
- After successful approval, the application will be added into the list of the application widget
- If the user is an existing user in SSO, then he/she will be able to login to a newly registered application with the same username and password.
Step 4: Implement SSO login
- To login using SSO, the client application needs to redirect to the SSO Login URL. SSO login URLfor staging: https://n-doptor-accounts-stage.nothi.gov.bd/login
- The client need to send the Base64 encrypted URL of their application at the time of redirection.
Format: SSO_LOGIN_URL?referer=[base64 client application’s url].
Example of SSO login URL for staging:
https://n-doptor-accounts-stage.nothi.gov.bd/login?referer=[base64 client application’s url] - After successful redirection SSO login page will be shown.
- The end user will input the userid (or username) and password and click on submit for login.
- If login is successful, SSO application will generate a compressed, base64 encrypted cookie (array) named ‘_ndoptor’ and send it to the client application.
Client application need to follow the following steps to work with this cookie “_ndortor”:
- First, the cookie need to be uncompressed via gzuncompress
- Secondly, need to decrypt the cookie in base64
- The uncompressed decrypted cookie is in JSON format (Please see below json format). The json should be parsed to make the cookie in array form.
- The cookie will have 2 element
- The first element [‘status’] will be success (in case of successful login).
- The second element [‘user_info’] (array) will have 3 elements
- [‘user’] which will have all the user login information
- [‘employee_info’] will have the user’s information
- [office_info] (array) will contain the user’s assigned offices in associative array format. An officer can be assigned to multiple offices. So [office_info] will have an array with 1 or more elements.
- By using this user info, client application will perform their further internal operations.
JSON Format of Uncompressed Base64 Decrypt Cookie(_ndortor):
{ "status": "success", "user_info": { "user": { "id": 3923, "username": "200000002986", "user_alias": "jafrin", "hash_change_password": "", "user_role_id": 3, "is_admin": 0, "active": true, "user_status": "1", "is_email_verified": 1, "email_verify_code": "", "verification_date": "2019-05-22T00:00:00+00:00", "ssn": "", "force_password_change": false, "last_password_change": "2021-02-02T13:35:33+00:00", "created": "2016-05-31T11:52:24+00:00", "modified": "2021-05-30T16:17:23+00:00", "created_by": "", "modified_by": "", "photo": "", "employee_record_id": 77858 }, "employee_info": { "id": 77858, "name_eng": "Mr. Md. Hasanuzzaman", "name_bng": "মোঃ হাসানুজ্জামান", "father_name_eng": "Md. Moniruzzaman", "father_name_bng": "Md. Moniruzzaman", "mother_name_eng": null, "mother_name_bng": null, "date_of_birth": "1983-01-10T00:00:00+00:00", "nid": "19832611293228300", "bcn": "", "ppn": "", "personal_email": "fowewa1824@revutap.com", "personal_mobile": "01855008702", "is_cadre": 2, "employee_grade": 0, "joining_date": null, "default_sign": 0 }, "office_info": [ { "id": 25458, "employee_record_id": 77858, "office_id": 65, "office_unit_id": 5121, "office_unit_organogram_id": 12643, "designation": "সিনিয়র সফটওয়্যার ইঞ্জিনিয়ার new test", "designation_level": 6, "designation_sequence": 6, "office_head": 1, "is_admin": false, "incharge_label": "", "joining_date": "2019-11-16T00:00:00+00:00", "last_office_date": null, "status": true, "show_unit": 0, "designation_en": "", "unit_name_bn": "ই-সার্ভিস", "office_name_bn": "এ্যাকসেস টু ইনফরমেশন (এটু্আই) প্রোগ্রাম", "unit_name_en": "E-Service", "office_name_en": "Access to Information Programme", "protikolpo_status": 0 } ] } }
Step 5: Implement SSO logout
- Before logout from the sso, client application need to delete the cookie.
- To logout using SSO, the client application needs to redirect to the SSO Logout URL.SSO logout URL for staging: https://n-doptor-accounts-stage.nothi.gov.bd/logout
- The client need to send the Base64 encrypted URL of their application at the time of redirection.
Format: SSO_LOGIN_URL?referer=[base64 client application’s url].
Example of SSO logoutURL for staging: https://n-doptor-accounts-stage.nothi.gov.bd/logout?referer=[base64 client application’s url]
Quickstarts for Developer
Step-by-step guides to quickly integrate n-doptor into your application.
1.1 Laravel Integration
If the client application is in Laravel (version > 7.0), the SSO team released a package. Package:https://packagist.org/packages/ndoptor/integration-sso-laravel Here is the installation process:
1.1.1 Installation
You can install the package via composer:
composer require ndoptor/integration-sso-laravel
Laravel 7.x and above
The package will automatically register itself, so you can start using it immediately.
1.1.2 Configuration
After installing the package, need to update or add these lines on .env file
composer require ndoptor/integration-sso-laravel
- LOGIN_SSO_URL= [LOGIN URL PROVIDED FROM THE SSO SERVICE PROVIDER]
- LOGOUT_SSO_URL= [LOGOUT URL PROVIDED FROM THE SSO SERVICE PROVIDER]
Update web.php in routes directory
- Remove Auth::routes();, if exists.
Use jisf.auth for N-DOPTOR SSO authentication
Route::middleware([‘jisf.auth’])->group(function () { /// here your authentication route });
2.1 CakePHP Integration
If the client application is in cakePHP framework.
Described Repo : https://gitlab.com/ndoptor/integration-sso-cakephp
2.1.1 Process
- copy config/ndoptor.php in config folder Update config/ndoptor.php with this value
return [ 'ndoptor' => [ 'enable' => true, 'api_domain' => 'http://n-doptor-api-stage.nothi.gov.bd/', 'login_sso_url' => 'http://n-doptor-accounts-stage.nothi.gov.bd/login', 'logout_sso_url' => 'http://n-doptor-accounts-stage.nothi.gov.bd/logout', ] ];
- If you do not want to use SSO just change enable => true to enable => false in config/ndoptor.php file
- Add below line in config/bootstrap.php in try block Configure::load(‘ndoptor’, ‘default’);
- Copy src/Controller/NDoptorController.php in src/Controller/ folder
- Extend your application main controller in src/Controller/NDoptorController.php file like class NDoptorController extends EFileController
- Remove the login & logout route if it exists.
- Add below routes in config/routes.php file
$builder->get('/login', ['controller' => 'NDoptor', 'action' => 'showLoginForm'], 'show_login'); $builder->get('/login_response', ['controller' => 'NDoptor', 'action' => 'loginResponse'],'login_response'); $builder->get('/logout', ['controller' => 'NDoptor', 'action' => 'logout'], 'logout');
You can change your authentication process in loginResponse method at
src/Controller/NDoptorController.php /// your authentication process here START // ... your authentication process ... // // your authentication process here END