WIXLIB

Synology SSO ServerDevelopment GuideTHIS DOCUMENT CONTAINS PROPRIETARY TECHNICAL INFORMATION WHICH ISTHE PROPERTY OF SYNOLOGY INCORPORATED AND SHALL NOT BE REPRODUCED,COPIED, OR USED AS THE BASIS FOR DESIGN, MANUFACTURING, OR SALE OFAPPARATUS WITHOUT WRITTEN PERMISSION OF SYNOLOGY INCORPORATED

and other countries.Synology Inc. 2015-2018 Synology Inc.All rights reserved.No part of this publication maybe reproduced, stored in aretrieval system, or transmitted,in any form or by any means,mechanical, electronic,photocopying, recording, orotherwise, without prior writtenpermission of Synology Inc.,with the following exceptions:Any person is hereby authorizedto store documentation on asingle computer for personaluse only and to print copies ofdocumentation for personal useprovided that the documentationcontains Synology’s copyrightnotice.The Synology logo is atrademark of Synology Inc.No licenses, express or implied,are granted with respect to anyof the technology described inthis document. Synology retainsall intellectual property rightsassociated with the technologydescribed in this document.This document is intended toassist application developersto develop applications only forSynology-labelled computers.Every effort has been madeto ensure that the informationin this document is accurate.Synology is not responsible fortypographical errors.Synology Inc.3F-3, No. 106, Chang-An W.Rd. Taipei 103, TaiwanSynology and the Synology logoare trademarks of Synology Inc.,registered in the United Statesand other countries.Marvell is registered trademarksof Marvell Semiconductor, Inc.or its subsidiaries in the UnitedStates and other countries.Freescale is registeredtrademarks of FreescaleSemiconductor, Inc. or itssubsidiaries in the United StatesOther products and companynames mentioned herein aretrademarks of their respectiveholders.Even though Synology hasreviewed this document,SYNOLOGY MAKESNO WARRANTY ORREPRESENTATION,EITHER EXPRESS ORIMPLIED, WITH RESPECTTO THIS DOCUMENT, ITSQUALITY, ACCURACY,MERCHANTABILITY, ORFITNESS FOR A PARTICULARPURPOSE. AS A RESULT, THISDOCUMENT IS PROVIDED “ASIS,” AND YOU, THE READER,ARE ASSUMING THE ENTIRERISK AS TO ITS QUALITY ANDACCURACY. IN NO EVENTWILL SYNOLOGY BE LIABLEFOR DIRECT, INDIRECT,SPECIAL, INCIDENTAL, ORCONSEQUENTIAL DAMAGESRESULTING FROM ANYDEFECT OR INACCURACYIN THIS DOCUMENT, even ifadvised of the possibility of suchdamages.THE WARRANTY ANDREMEDIES SET FORTH ABOVEARE EXCLUSIVE AND INLIEU OF ALL OTHERS, ORALOR WRITTEN, EXPRESS ORIMPLIED. No Synology dealer,agent, or employee is authorizedto make any modification,extension, or addition to thiswarranty.Some states do not allowthe exclusion or limitation ofimplied warranties or liabilityfor incidental or consequentialdamages, so the above limitationor exclusion may not apply toyou. This warranty gives youspecific legal rights, and you mayalso have other rights which varyfrom state to state.

Table of ContentsChapter 1: IntroductionChapter 2: UsageDSM JavaScript SDK Script LocationUsage55Chapter 3: Manual FlowChapter 4: Exchange User InformationTo exchange for user’s information8Chapter 5: Example CodeJavascript SDK Examples9Chapter 6: Error StringERR STRING12Synology SSO Server Development Guide 201810153 2015-2018 Synology Inc. All rights reserved.

1ChapterIntroductionSynology DSM SSO Server is based on the OAuth 2 protocol. We provide the JavaScript SDK for 3rd partydevelopment. SSO Server JavaScript SDK script will be installed automatically after SSO Server installation.4 2015-2018 Synology Inc. All rights reserved.

2ChapterJavascript SDKDSM JavaScript SDK Script Locationhttp://DSM IP OR ializationSYNOSSO.initSYNOSSO.init is used to initialize SYNOSSO SDK. You need to call SYNOSSO.init before calling any otherSYNOSSO APIs.Function parameters of SSOSYNO.init:Keyoauthserver urlapp idredirect uricallbackdomain name(optional)ldap baseDN(optional)ValuestringstringstringJavascript function objectstringstringDescriptionThe URL of the DSM where SSO Server is installed.APP ID registered on the DSM SSO ServerRedirect URI registered on the DSM SSO Server.User defined callback for handling login query/login response.Windows AD domain name of SSO client. Ex: "MYDOMAIN.COM"LDAP baseDN of SSO client. Ex: "dc myldap,dc com"*Directory service related options are for directory service checking. If one of these options is provided, SSOServer will validate if this directory service is the same as DSM that SSO Server belongs to.Example:SYNOSSO .init({ oauthserver url : 'http://10.13.20.131:5000' ,a pp id : '153fcb35b01571b49cb0adca3a4bda40' ,    redirect uri : 'http://10.13.20.130/relay.html' , //redirect url have to be the same as theone registered in SSO server, and can be a plain text html file. callback : authCallback});AuthenticationSYNOSSO.login();After calling SYNOSSO.login, a login popup window containing a dialog for SSO will appear. SYNOSSO.loginhas no arguments and will call the callback registered in SYNOSSO.init after the user logs in successfully.Example:SYNOSSO .login();Response:Response of Callback registered in SYNOSSO.init():Status5KeyChapter 2: UsageValueString:“login”/“not login”/ERRSTRINGDescriptionShow status of this user on SSO Server. 2015-2018 Synology Inc. All rights reserved.

KeyAccess tokenstringValueDescriptionAccess token returned from SSO Server after thisuser logs in successfully.If the user already login SSO Serverresponse:{ status : 'login',access token: 'ABCDE'}If the user didn’t login SSO Serverresponse:{ status : 'not login'}If any unexpected error occurred.response:{ status : 'ERR STRING'}* For ERR STRING, please refer to Chapter 6 for more details.LogoutSYNOSSO.logout(function(){//do something after logout.});Function parameters of SSOSYNO.logout:callbackKeyValueJavascript functionDescriptionThe callback which will be called after the user logs out from SSOServer.SYNOSSO.logout has a callback which will be called after user logs out from SSO Server. Before a user logs out from your application, call SYNOSSO.logout, and this method will log out this user fromSSO Server. SYNOSSO.init must be called before SYNOSSO.logout. SYNOSSO.logout only logs out the user from SSO Server and will not affect login status of the user in othersapplications.Response of Callback of SYNOSSO.logout has no arguments.6Chapter 2: Usage 2015-2018 Synology Inc. All rights reserved.

3ChapterManual FlowStep1: Bring the user to http://[DSM Oauth Server:5000]/webman/sso/SSOOauth.cgi with the following querystring parameters: app id : APP ID registered on DSM SSO Server. redirect uri : Redirect URI registered on DSM SSO Server. scope : Currently, SSO server only provide “user id” scope which means limited user information for SingleSign On. state(optional) : Use to protect CSRF.Then the login window will show up, waiting for the user to input username/password.Ex:SSO Server: 10.13.20.254SSO Client: OOauth.cgi?app id a5a78d55b7d30dab1b3067d26bc49e49&scope user id&redirect uri http://10.13.22.128/sso redirect relay.htmlStep2: User logs in to SSO ServerStep3: After logging in successfully, the user will be redirected back to the redirect URI which this app registeredon SSO Server with following hash values: access token: The access token which will be used to exchange user information. State(optional): If you provide the state at Step1, the exact same state will be returned.Ex:http://10.13.22.128/sso redirect relay.html#access token 58322f3eaaG7t69030edH2bcdee08brWc6250eba&state fabc21cf7Chapter 3: Manual Flow 2015-2018 Synology Inc. All rights reserved.

4ChapterExchange User InformationTo exchange for user’s information1 You need to use an accesstoken to get user id and user name2 Go to endpoing: oken.cgi with these query stringparameters: action: “exchange” access token: “ABCDE” app id: “ asfsf sdfsdf3e ” o/SSOAccessToken.cgi?action ”exchange”&access token ”ABCDE”&app id ”asfsffsdfsdf3e”Response:If the token is correct:{success : true, data :{user id : 1024 ,user name : john}}If any unexpected errors occurred:{success: false,error: 'ERR STRING'}8Chapter 4: Exchange User Information 2015-2018 Synology Inc. All rights reserved.

5ChapterExample CodeJavascript SDK ExamplesFontpage.html !DOCTYPE html html lang "en" head meta charset "utf-8" title Test App 1 /title meta name "viewport" content "width device-width,initial-scale 1.0" meta name "description" content "" meta name "author" content "" /head body div class "container" div class "form-signin" h1 class "form-signin-heading" Test App 1 /h1 h2 class "form-signin-heading" Please sign in via SynologyOauth /h2 button id "login-button" SSO Login /button /div /div /body script type "text/javascript" src "jquery-2.1.1.min.js" /script script type "text/javascript"src .js" /script script //SYNOSSO Javascript SDK don't depend on jQuery!//SSO Server: 10.13.20.254//SSO Client: 10.13.20.130 (function(){SYNOSSO.init({oauthserver url: 'http://10.13.20.254:5000',app id: '153fcb35b01571b49cb0adca3a4bda40',redirect uri: 'http://10.13.20.130/ssorelay.html',//redirect URI have to be the same as the one registered in SSO server, andshould be a plain text html filecallback: authCallback})login9function authCallback(response){console.log("client side");if('not login' response.status) { //user notconsole.log (response.status);} else if('login' response.status) {console.log (response.status);console.log (response.access token);Chapter 5: Example Code 2015-2018 Synology Inc. All rights reserved.

alert("access token: " response.access token); .ajax ({ url : '/login backend.php' ,cache: false,type: 'GET',data:{accesstoken:response.access token},error: function(xhr){alert("ajax error");//deal with errors},success: function(response){alert("success");//deal with success}});} else {alert("error");//deal with errors;}})() /script /html 10}var login button document.getElementById("login-button");login button.addEventListener('click' , SYNOSSO.login);Chapter 5: Example Code 2015-2018 Synology Inc. All rights reserved.

Login backend.php ?phpsession start(); accesstoken GET['accesstoken'];function httpGet ( url){ ch curl init();curl setopt( ch,curl setopt( ch,curl setopt( ch,curl setopt( ch,ignore checking CACURLOPT URL, url);CURLOPT RETURNTRANSFER, true);CURLOPT HEADER, false);CURLOPT SSL VERIFYHOST, false);//for testing,curl setopt( ch, CURLOPT SSL VERIFYPEER, false); output curl exec( ch);curl close( ch);return output;}//SSO Server: 10.13.20.254:5000 url str n.cgi?action exchange&access token ". accesstoken; resp httpGet( url str); json resp json decode( resp, true);if( json resp["success"] true){ userid json resp["data"]["user id"]; SESSION["user id"] userid;//login success} else {//not login, redirect to frontpage.html}? 11Chapter 5: Example Code 2015-2018 Synology Inc. All rights reserved.

6ChapterError StringERR STRING server error - SSO server error. parameter error - Parameter error when SYNOSSO.init. invalid app id - APP ID error. invalid redirect uri - Redirect URI error. invalid directory service - Different directory service between SYNOSSO.init and DSM SSO Server. invalid token - Invalid SSO access token. unknown error - Other unexpected errors.12Chapter 6: Error String 2015-2018 Synology Inc. All rights reserved.

synology sso server development guide this document contains proprietary technical information which is the property of synology incorporated and shall not be reproduced, copied, or used as the basis for design, manufacturing, or sale of apparatus without written permission of synology incorporated