SSO with PKCE

This page details the method for single sign-on with Setel if using the Proof Key for Code Exchange (PKCE) method.

For this flow, you will need to generate a code verifier. This is a cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters -, ., _, and ~ (hyphen, period, underscore, and tilde), between 43 and 128 characters long.

This string is then encrypted with the SHA256 function and turned into a base64url encoded string. This value is then stored as code_challenge and sent as part of the query in the special authorisation URL.

You can then begin requesting authorisation access from the user by redirecting the user to the special authorisation URL.

The special authorisation URL must be created based on the format 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&
  code_challenge=ODc4ODY1YTFkZDMwMDk5ZTRkYzFkYTgxZWU2MzFkYjI2ZWZlYTI3NjY2OTY4OTJiODBmMWU5NGRiMGRmMTU1ZA==&
  code_challenge_method=S256&
  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 application. This is not the same as your merchant ID.
`redirect_uri`	The URL to be redirected to after the customer grants you permission.
`scope`	The permissions that are given by the customer and the `code_verifier`.
`state`	A checking parameter to prevent injection attacks.

Retrieving the access token

Once the special authorisation 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.

You will then need to verify the state parameter to ensure that there was no injection attack.

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

After verifying, you can send a request to the Issue OAuth Token API for the access token.

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",
  "code_verifier": "9KWXSmHzhXIM4T2BxpMd9KWXSmHzhXIM4T2BxpMd9KWXSmHzhXIM4T2BxpMd" 
}

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
}