Writing a new application to is quite easy since the whole implementation is following the RFC 6749 for OAuth 2.0

Here is a nice tutorial for OAuth 2.0

General discussion regarding implementation is handled on google group IITB SSO. If you're devleoping with SSO, please join the group for queries and discussion

Registering application

  • To register an application open this link
  • Provide a nice name to your application, write a brief description and add a cool little logo
  • Unless your application is entirely client based (like JS), use Client Type: confidential and Authorization grant type: authorization code
  • Add a list of redirect URIs. Redirect URIs are the URLs where your client will be redirected to after authorization. Let's say you have entered http://www.example.com/authorization/
  • Click Submit! That's it, you've registered an application. You can access your applications at list of applications

Authorization workflow

  • To authenticate a client, add some button to your webpage for login like Login With SSO
  • By clicking to that button, your client should be redirect to
     http://gymkhana.iitb.ac.in/sso/oauth/authorize/?client_id=YOUR_CLIENT_ID&response_type=code&scope=basic&redirect_uri=REDIRECT_URI&state=some_state
    scope, redirect_uri and state are optional here. state can be anything, it will be returned back to you after authorization. You can use this to rememeber your client. redirect_uri should be from redirect uri you registered for app. If nothing is provided here then first redirect uri will be assumed to be default. From now onwards we'll call it REDIRECT_URI. scope is a string of space separated scopes.
      Available scopes are
    • basic: It includes your user id from SSO server (not the ldap id)
    • profile: Your first_name and last_name and type
    • picture: Your profile picture
    • sex: You sex - Male, Female or Other
    • ldap: Your ldap username and email
    • phone: Your contact number including additional numbers
    • insti_address: Your address inside institute
    • program: Your roll number, department, course, joining year and graduation year
    • secondary_emails: Your alternate emails
    • send_mail: Allow application to send you email via SSO
    If nothing is provided in scope parameter then basic scope will be assumed.
    Now your client will see something similar to this image
  • If client has denied your request you'll get REDIRECT_URI?error=access_denied else you'll get REDIRECT_URL?state=some_state&code=AUTHORIZATION_CODE. AUTHORIZATION_CODE will be an alpha-numeric code
  • Or ignore all above points and use our widget. Check widget section on top

Token Exchange

    Now assuming that you've received AUTHORIZATION_CODE after client has authorized itself. AUTHORIZATION_CODE is short lived code. You need to redeem it quickly to get access_token
  • Make a request for token exchange to http://gymkhana.iitb.ac.in/sso/oauth/token/. You're HTTP request will look like
    POST /sso/oauth/token/ HTTP/1.1
    Host: gymkhana.iitb.ac.in
    Authorization: Basic AUTHENTICATION_TOKEN
    Content-Type: application/x-www-form-urlencoded; charset=UTF-8
    
    
    code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI&grant_type=authorization_code
    
    AUTHENTICATION_TOKEN is base64 of CLIENT_ID:CLIENT_SECRET. Here code, redirect_uri and grant_type are compulsory
  • Now assuming you've created a valid http request here, you'll now get access_token and refresh_token as json
    {
        "access_token" : "access_token",
        "token_type" : "Bearer",
        "expires_in" : "36000",
        "refresh_token" : "refresh_token",
        "scope" : "basic"
    }
    
    access_token and refresh_token are both alpha-numeric strings
    access_token are short living tokens and will expire in 10 hours. refresh_token are long living tokens and you should save them in your database for future purpose.
    scope is space separated list of scopes that client has granted to you. You should also save these scope in your database for reference purpose.
    At this point you should also create session for your client on your website since client is authenticated now

Refreshing Token

    Since access_token will expire quickly, you need to generate new access_token with refresh_token
  • Refreshing token is similar to token exchange with (almost) same http request to server. Only your post data will changed and new post data will be refresh_token=REFRESH_TOKEN&grant_type=refresh_token
  • The response JSON will be almost same with only access_token and refresh_token both changed. You need to update your refresh_token in database

Revoking Token

  • To revoke client access, create the following http request
    POST /sso/oauth/revoke_token/ HTTP/1.1
    Host: gymkhana.iitb.ac.in
    Content-Type: application/x-www-form-urlencoded; charset=UTF-8
    
    
    token=TOKEN&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&token_type_hint=TOKEN_TYPE
    
    Here TOKEN can be access_token or refresh_token
    token_type_hint is optional. TOKEN_TYPE should be either access_token or refresh_token

Before reading this section, go through basic section once

Accessing API

    By now you have created API, got access_token and authenticated user. But still you don't know who the user is? For that purpose you need to access user resources API. Currently API is limited to few user resources only and in future we're planning to expand it a lot.
    User data is stored at sso server. And as an application developer you should encourage users to update their data there.
  • Available user resources are:
    • basic: Basic resource includes id only. You need to have basic scope for this
    • first_name: First name of the user. You need to have profile scope for this
    • last_name: Last name of the user. You need to have profile scope for this
    • type: Type of user. ex: ug, pg, dd etc. You need profile scope for this
    • username: LDAP username of the user. You need to have ldap scope for this
    • profile_picture: Profile picture of user. This will be a URL. You need to have picture scope for this
    • sex: Sex of the user. It can be Male, Female or Other. You need to have sex scope for this
    • email: LDAP email (username@iitb.ac.in) of the user. You need to have ldap scope for this
    • mobile: Mobile includes mobile number of client fetched from LDAP. You need to have phone scope for this
    • roll_number: Roll number includes roll number of client fetched from LDAP. You need to have program scope for this
    • contacts: Phone resource includes all the contact number provided by client. You need to have phone scope for this
    • insti_address: This resource includes user's room number and hoste number. You need insti_address scope for this
    • program: Program includes user's joining year, (expected) graduation year, department and degree. You need to have program scope for this
    • secondary_emails: This resource includes user's emails other than default ldap email. You need to have secondary_emails scope for this
  • To access user's resources make a GET request to http://gymkhana.iitb.ac.in/sso/user/api/user/?fields=RESOURCE_LIST. fields is optional parameter and by default it includes basic fields. RESOURCE_LIST is comma-separated list of user resources. You should include access_token in request header as
    GET /sso/user/api/user/ HTTP/1.1
    Host: gymkhana.iitb.ac.in
    Authorization: Bearer ACCESS_TOKEN
    
  • The output for http://gymkhana.iitb.ac.in/sso/user/api/user/?fields=first_name,last_name,type,profile_picture,sex,username,email,program,contacts,insti_address,secondary_emails,mobile,roll_number will look like (assuming you've enough scopes)
    {
      "id": 1,
      "username": "username",
      "first_name": "First Name",
      "type": "TYPE",
      "profile_picture": "/sso//path/to/profile_picture_file"
      "last_name": "Last Name",
      "sex": "SEX",
      "email": "username@iitb.ac.in",
      "mobile": "0123456789",
      "roll_number": "123456789",
      "program": {
        "id": 1,
        "department": "DEPARTMENT",
        "department_name": "FULL_DEPARTMENT_NAME",
        "join_year": 2012,
        "graduation_year": 2016,
        "degree": "DEGREE",
        "degree_name": "FULL_DEGREE_NAME"
      },
      "secondary_emails": [
        {
          "id": 1,
          "email": "user_email@gmail.com"
        }
      ],
      "contacts": [
        {
          "id": 1,
          "number": "9876543210"
        }
      ],
      "insti_address": {
        "id": 1,
        "room": "room_number",
        "hostel": "HOSTEL",
        "hostel_name": "FULL_HOSTEL_NAME",
      }
    }
    
    Here you'll get only resources permitted by user in scope.
  • DEPARTMENT list:
    • DEPARTMENT_NAME: FULL_DEPARMENT_NAME
    • AE: Aerospace Engineering
    • ANIM: Animation
    • ASC: Application Software Centre
    • AGP: Applied Geophysics
    • ASI: Applied Statistics and Informatics
    • BME: Biomedical Engineering
    • BB: Biosciences and Bioengineering
    • BIOTECH: Biotechnology
    • CASDE: Centre for Aerospace Systems Design and Engineering
    • CDEEP: Centre for Distance Engineering Education Programme
    • CESE: Centre for Environmental Science and Engineering
    • CFDVS: Centre for Formal Design and Verification of Software
    • CPS: Centre for Policy Studies
    • CRNTS: Centre for Research in Nanotechnology and Science
    • CTARA: Centre for Technology Alternatives for Rural Areas
    • CUSE: Centre for Urban Science and Engineering
    • CSRE: Centre of Studies in Resources Engineering
    • CHE: Chemical Engineering
    • CH: Chemistry
    • CLE: Civil Engineering
    • CLS: Climate Studies
    • CC: Computer Centre
    • CSE: Computer Science & Engineering
    • CEP: Continuing Education Programme
    • CORRSCI: Corrosion Science and Engineering
    • DSCE: Desai Sethi Centre for Entrepreneurship
    • ES: Earth Sciences
    • ET: Educational Technology
    • EE: Electrical Engineering
    • ESE: Energy Science and Engineering
    • HSS: Humanities & Social Science
    • IITBMRA: IITB-Monash Research Academy
    • IDC: Industrial Design Centre
    • IDC: Industrial Design Centre
    • IEOR: Industrial Engineering and Operations Research
    • IM: Industrial Management
    • IxD: Interaction Design
    • KReSIT: Kanwal Rekhi School of Information Technology
    • MS: Material Science
    • MMM: Materials, Manufacturing and Modelling
    • MM: Mathematics
    • ME: Mechanical Engineering
    • MEMS: Metallurgical Engineering & Materials Science
    • MVD: Mobility and Vehicle Design
    • NCAIR: National Centre for Aerospace Innovation and Research
    • NCM: National Centre for Mathematics
    • PHE: Physical Education
    • PH: Physics
    • PMS: Physics, Material Science
    • PC: Preparatory Course
    • RE: Reliability Engineering
    • SJMSOM: Shailesh J. Mehta School of Management
    • SAIF: Sophisticated Analytical Instrument Facility
    • SCE: Systems and Control Engineering
    • TCTD: Tata Center for Technology and Design
    • VISCOM: Visual Communication
    • WRCB: Wadhwani Research Centre for Bioengineering
  • DEGREE list:
    • DEGREE: FULL_DEGREE_NAME
    • BTECH: Bachelor of Technology
    • MTECH: Master of Technology
    • DD: B.Tech. + M.Tech. Dual Degree
    • MSC: Master of Science
    • PHD: Doctor of Philosophy
    • BDES: Bachelor of Design
    • MDES: Master of Design
    • MPHIL: Master of Philosophy
    • MMG: Master of Management
    • MSEx: M.S. (Exit Degree)
    • MtechEx: Master of Technology (Exit Degree)
    • MtechPhDDD: M.Tech. + Ph.D. Dual Degree
    • PC: Preparatory Course
    • VS: Visiting Student
    • MPhilEx: Master of Philosophy (Exit Degree)
    • MScEx: Master of Science (Exit Degree)
    • MScMTechDD: M.Sc. + M.Tech. Dual Degree
    • MScPhDDD: M.Sc. + Ph.D. Dual Degree
    • MPhilPhDDD: M.Phil. + Ph.D. Dual Degree
    • EMBA: Executive MBA
    • FYBS: Four Year BS
    • IMTECH: Integrated M.Tech.
    • MSCBR: Master of Science By Research
    • TYMSC: Two Year M.Sc.
    • FYIMSC: Five Year Integrated M.Sc.
    • DIIT: D.I.I.T.
    • DIITEx: D.I.T.T. (Exit Degree)
  • HOSTEL list:
    • HOSTEL: FULL_HOSTEL_NAME
    • 1: Hostel 1
    • 2: Hostel 2
    • 3: Hostel 3
    • 4: Hostel 4
    • 5: Hostel 5
    • 6: Hostel 6
    • 7: Hostel 7
    • 8: Hostel 8
    • 9: Hostel 9
    • 10: Hostel 10
    • 11: Hostel 11
    • 12: Hostel 12
    • 13: Hostel 13
    • 14: Hostel 14
    • 15: Hostel 15
    • 16: Hostel 16
    • tansa: Tansa
    • qip: QIP
  • SEX list:
    • male: Male
    • female: Female
    • other: Other
  • TYPE list:
    • None
    • rs
    • misc
    • vendor
    • pg
    • institutional
    • prjstf
    • ug
    • fac
    • stf
    • intern
    • fac.confguest
    • dd
    • fac.guest
    • stf.home
    • fac.home

Send Mail API

    This application also provides a "send mail" API, which allows your application to send email to user from a simple endpoint. You need to have send_mail permission from user for this to work
  • Create a POST request like this:
    POST /sso/user/api/user/send_mail/ HTTP/1.1
    Host: gymkhana.iitb.ac.in
    Authorization: Bearer ACCESS_TOKEN
    Content-Type: application/json
    
    
    {
        "subject": "Hello World",
        "message": "Lorem Ipsum",
        "reply_to": [
            "email_address_1@example.com",
            "email_address_2@exapple.com"
        ]
    }
    
  • Response Data:
    {
        "Message-ID": "<20181211043255.8040.18668@web-gymkhana.gymkhana.iitb.ac.in>",
        "status": true
    }
    
    Message-ID is a unique identifier for each sent message. Its format is <timestamp.pid.random_number@fqdn>. Message-ID in this example is actually a valid generated identifier which is changing each time you open this page!
    status is either true or false depending on whether message was sent successfully. Remember status: true doesn't guarantee delivery of message
  • Final subject will be "[SSO] [<APPLICATION_NAME>] <YOUR SUBJECT>". This is automatically generated.
  • Final message will have these line appended:
    Sent via SSO by <APPLICATION_NAME>
    
    You received this message because you've provided the email sending permission to the application
    
  • reply_to is list of email address where you want your user to reply. Most of the mail servers honor this protocol and by clicking on "reply" will directly reply to these emails.
  • DISCLAIMER: We do not store emails in our database. We do store Message-ID, failure state, application and user for each email. This is stored for debugging and performance improvement purposes

Before reading this section, go through basic section once

For the ease of users and application developers, we've created some widgets for you. Using widgets will provide extra contextual information to your users

Login Widget

By including few lines of html and javascript in your web-page, you can get nice looking login button which changes according to user logged-in. Here is an example:

To include these widgets follow these steps
  • Include <script src="http://gymkhana.iitb.ac.in/sso/static/widget/js/login.min.js" type="application/javascript"></script> in your html file
  • Include <div id="sso-root"></div> in your html where you want to keep your login button
  • Now write some primary configuration for button to work
    
        <script type="application/javascript">
    
            new SSO_JS({
                config: {
                    client_id: 'your-long-client-id',   // Compulsory
                    scope: ['basic', 'profile'],    // Optional. Default is  ['basic']
                    state: '', // Optional. Default None
                    response_type: 'code',  // Optional. Default is 'code'
                    redirect_uri: 'uri-for-redirection',    //Optional
                    new_window: 'false',    // Optional.
                                            // Where authorization page should be opened in new tab or
                                            // same tab Default is false.
                    sso_root: document.getElementById('sso-root'),
                    /* Optional
                     document.getElementById don't work if your element is not in light DOM. In that case you need to
                     provide selector here. In most of the cases this will work.
                     */
                },
                colors: { // All Optional
                    button_div_bg_color: '303F9F', // Background color of button
                    button_anchor_color: 'FFFFFF', // Font color of Button
                    logout_anchor_color: '727272', // Font color of logout mark (The one with 'Login as other user'
                },
            }).init();
    
        </script>
    
    
  • That's it. You'll get a nice looking login button there.

While developing an application based on SSO, keep following things in mind!

  • Don't ask for too much permissions. Ask for necessary permissions only. Respect user's privacy!
  • Store refresh_token and access_token on your server. They can be used for background requests.
  • Maintain sessions for your user! Don't overwhelm the SSO server by authorization requests.
  • If user hasn't provided the necessary permissions, revoke the token! Otherwise user will see your application in list of connected apps.
  • Use login-button widget!

We are trying to provide best we can. Efforts from your side are appreciated. Here are few library implementations

PHP

BijoySingh is maintaining a PHP library The documentation is present here

Python

Python library is maintained here. This is currently in alpha version