SSO with client secret

This page details the method for single sign-on with Setel using the client secret method. This flow will require actions from the partner on both the frontend and backend.

The diagram below shows how communication happens between our partners and the Setel API servers.

The information flow will be triggered from the partner's app and then sent to the partner's backend. The partner's backend is the one that will communicate with the Setel API's servers upon successful authentication.

Frontend

You will need to use a special authorisation URL to receive permission from your users. You will have to redirect the user to the URL automatically or upon a user action to begin the process.

The special authorisation URL follows a specific format, detailed below:

https://[setel-connect-url]/authorize?   
  response_type=code&   
  client_id=8fe6acc55e6dd02daff89dc876c4d7ee&   
  redirect_uri=https://my-site/stub/redirect-url&
  scope=user_info_read_scope&
  state=1234zyx

URL parameters

Parameter	Description
`response_type`	The type of flow for this URL. For authorisation flow, the value is `code`.
`client_id`	The ID of the your application. This is not the same as your merchant ID.
`redirect_uri`	The URL to be redirected to after the user grants you permission.
`scope`	The permissions that are given by the user.
`state`	A checking parameter to prevent injection attacks.

Once the URL is created, it can then be used to request users to allow access. Users are redirected to this URL with the list of permissions requested.

Once the user allows the authorisation, Setel's authorisation server will return a special authorisation code for the user.

You should have a special handling method to receive the authorisation code and use it to retrieve an accessToken.

Backend

The next steps are to be done on your backend.

You will need to verify the state parameter to determine if there was an injection attack.

https://my-site/stub/redirect-url?
  code=c019ea04ac14786f34bc4b7d1d61996b&
  state=1234zyx

This code will then be used to request an access token. The request is done by calling for the Issue OAuth Token API.

An example of the payload to be sent to the API is shown below.

{
  "grantType": "authorization_code",
  "code": "c019ea04ac14786f34bc4b7d1d61996b",
  "redirectUri": "https://my-site/stub/redirect-url",
  "clientId": "8fe6acc55e6dd02daff89dc876c4d7ee",
  "clientSecret": "f6d89400b2f9b9d9337f77e2270c0700582d1a23a88ca216d10d05a5e5c0d253"
}

The endpoint will then return the accessToken and refreshToken which can be used to request data from Setel.

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkNPWF9qU1hqMUpiRUlvdjRZdHYtdkZYSnU5TnBzNUxkTjVXZ1BSbVRlV2MifQ.eyJqdGkiOiIyMjI2NTc2OS0xZDZmLTQ1NTctOWE5NS03ODM5YmNmNDg0MzciLCJuYmYiOjAsImlzcyI6Imh0dHA6Ly9hcGkuZGV2Mi5zZXRlbC5teS9hdXRoL3JlYWxtcy9aQVAiLCJhdWQiOiJ6YXAtYWNjb3VudHMiLCJzdWIiOiJjN2EwMTkxZi1hOWQ4LTRmMGQtOTdjMi1mMjI4MzNmOTJkMDEiLCJ0eXAiOiJCZWFyZXIiLCJpc3N1ZXIiOiJodHRwczovL2FwaS5kZXYyLnNldGVsLm15OjgwL2FwaS9pYW0vc2V0ZWwtY3VzdG9tZXJzIiwibmFtZXNwYWNlIjoic2V0ZWwtY3VzdG9tZXJzIiwiaW50ZXJmYWNlIjp7ImlkZW50aWZpZXIiOiJkZWZhdWx0IiwidHlwZSI6ImRlZmF1bHQifSwic2Vzc2lvbl9zdGF0ZSI6IjhiNzljYmZlLTBlNmUtNDE4ZC05OWJhLWZiZTMyOTliZjJkMSIsInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbInVzZXIiXX19LCJncm91cHMiOlsib2lkY19jbGllbnRzIiwiYWNjb3VudCJdLCJpYXQiOjE2MjM3NTg0NzgsImV4cCI6MTYyMzc2MDI3OH0.LjXm2I5zYsqD4aJJ918Q90ZtylfniOI-qT1XTNpRy1LzAYfe7BKq_WgJ9rwiGo27jK7qORSQsiDhgudMUSlH-YYDAQdlyAuoZ--7xM6htfKsNpG0_qtLg4tfXdiaZuveHbz12RksLNVaNNuLMuuzem9G82zFFWo_AuL-9ipvGOPYG06tSBFjm4MatMJt0YcmkOojHl0vxUoLhF0VdnRBFR3tr3a4Vp8y3M7wP-X4SgdM5TRvwuZDQWb_YV86ZROgR_PbeV4XJOD4fTzFFUkofxNXjC3Uy6ulEf611wNV2SnFpAFrhH95C1_kSsxcs7CKYX-HsdXYrgrJYAHUHiz13A",
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJhOGY0MzQwZC0zNWQ2LTRmZDUtODNiMi00ZDVkODZhZmIyOTIiLCJ0eXAiOiJSZWZyZXNoIiwic3ViIjoiYzdhMDE5MWYtYTlkOC00ZjBkLTk3YzItZjIyODMzZjkyZDAxIiwic2Vzc2lvbl9zdGF0ZSI6IjhiNzljYmZlLTBlNmUtNDE4ZC05OWJhLWZiZTMyOTliZjJkMSIsImdyb3VwcyI6WyJvaWRjX2NsaWVudHMiLCJhY2NvdW50Il0sIm5hbWVzcGFjZSI6InNldGVsLWN1c3RvbWVycyIsImlhdCI6MTYyMzc1ODQ3OCwiZXhwIjoxNjI0MDk0NDc4fQ.VRkVQro5sgXDwZNI7lyGFji7sdwex7UkmcZJe3gErBRlvQqg6lkCKEQUm609_9xvyadF7xW9SO9d05mutfVnBbl14It251mYST4on_pci5BSOk-f3IIuol-9VfJL-H7Tw2DHF-iWQrljaQYWpuSKFSbUEceiKyQm0JfnDy3vT_lhZR1g3iq4KCdr628jofimYhsKb0Pa5bdyDf2PRMqB1HpU_FpFY-09_4XEYgi0AjZYE5DTXTm5kGar4TyqmIm44mdWZfFz0Fd23GtbapbZD63VfwBqimLxd_IpMDtTM5A6hsU--gAElJDQaXQHZdfsYT63t_EhoVC4BJvrKL_0YA",
  "expiresIn": 1800,
  "refreshExpiresIn": 336000
}

❗️
To maintain security, the tokens should never be passed to the frontend when the clientSecret is used.