Enable Single Sign-On

utilize single sign on docid\ lnznuggqvr5ouarmyrhjw and enable users docid\ ijyftusvdonrn4rxsnsev to authenticate once and access mutliple applications and services deployed within an ecosystem or federation external applications and platforms can utilize raidiam connect as an oidc compliant sign up and sign in docid\ wst99gxr5y8dol1atvju3 the integration is based on the financial grade api (fapi) standard and uses pushed authorization requests (par) authorization code flow proof key of code exchange (pkce) authorization code flow in authorization code flow defined in the oauth 2 0 authorization framework (rfc6749) specification an authorization server sends a temporary (authorization) code to a client application the code is exchanged for security tokens access tokens, refresh tokens, and id tokens this flow is available for confidential clients, for example, web applications with a backend that can store credentials securely this way, the client can obtain one or more of the following token types the authorization code proves to the authorization server that the client requesting a token is permitted to do so the user consents that the client can access the resource before the authorization server passes the code pushed authorization requests oauth pushed authorization requests (par rfc9126) is an oauth 2 0 extension for the par endpoint that allows client applications to push the payloads of authorization requests to authorization server via direct requests to the par endpoint in return, the client application receives a request uri that is used as a reference to the previously sent payload data in a subsequent call to the authorization server's /authorization endpoint proof key of code exchange the proof key of code exchange (pkce) is an extension of the standard authorization code flow it is designed to be a secure substitute for the implicit flow for single page applications (spa) or native applications authorization code grant with pkce introduces a technique to prevent unauthorized access to resources in the case of code interception due to the raidiam authorisation server fapi 2 0 security profile compliance, using pkce is mandatory for all applications in pkce, the client application generates a code verifier and transforms it into code challenge code verifier is a random key that prevents the authorization code from being intercepted code verifier is generated by the client application for every authorization request and transformed into code challenge according to the code challenge method set for the client application in advance it’s mandatory to set the code challenge method value to s256 while sending the request to the par or authorization endpoints, the client application must include the code challenge in the request while requesting token, the requests to the authorization server must also include the code challenge of the same value that was sent to the par or authorization endpoint integration pattern for sso sequencediagram autonumber participant user participant app as client application participant as as raidiam authorization server activate user user >>app access activate app activate as app >>as post /par as >>app request uri=xyz app >>as /authorize\&request uri=xyz deactivate app as >>user redirect to login screen user >>as authenticate as >>user display consent user >>as give consent deactivate user as >>app issue authorization code activate app app >>as request token as >>as validate the request as >>app return token deactivate as deactivate app to integrate with raidiam for authentication, client applications need to push their authorization requests to raidiam authorisation servers docid\ aw0rfr 6i9dbui8sh7hkd in order to obtain the request uri that refers to their subsequent call to the oauth authorization endpoint once the application request authorization, the user is redirected to raidiam login screen where they can authenticate themselves once authenticated, the user provides their consent to share their data stored by raidiam and gets redirected back to the application at the same time, the client application receives an authorization code that can be exchanged for tokens the application can utilize the tokens issued by raidiam's authorization server in order to access its apis or get information about the authentication event and the user setting up directory add and manage applications docid x1gpnkw44xyryobh6wp6 (request applications docid\ at1zjk4wwrastj pdhvhx ) within your application, register the same redirect uri that you will use in the single sign on docid\ lnznuggqvr5ouarmyrhjw process the redirect uri tells raidiam's authorization server where to redirect the user after they authenticate themselves and provide their consent you can register multiple redirect uris after creating your software statement, any new redirect uri requires a manual update from raidiam's side provide your trust framework participants docid\ zwoo4fno16xiy1mcodij5 with a client identifier of your application (software statement id) enabling the administrator to configure the application to request necessary scopes discover raidiam authorization server configuration add raidiam authorization server's oidc discovery (/ well known) endpoint to your application utilize any oauth library you want for example, the urls for raidiam's demo environment look like the following openid discovery https //auth demo raidiam io/ well known/openid configuration https //auth demo raidiam io/ well known/openid configuration authorization endpoint https //auth demo raidiam io/auth https //auth demo raidiam io/auth", token endpoint https //matls auth demo raidiam io/token https //matls auth demo raidiam io/token user info endpoint https //auth demo raidiam io/me https //auth demo raidiam io/me postman collection you can utilize the below postman api collection to quickly test the integration https //archbee doc uploads s3 amazonaws com/7zxodbwrqgr4ilsctm5rl/misxghutzaliatystotqd 2023sso raidiam connect examplepostmancollection json push authorization request below, you can find a postman implementation of a pushed authorization request (par) https //archbee doc uploads s3 amazonaws com/7zxodbwrqgr4ilsctm5rl/b0rgap4wvji zt id6lnm sso raidiam connect example parpostmancollection json for par, call the "pushed authorization request endpoint" endpoint from the well known in this example, it's /request field required description value client id yes retrieved from the software statement oauth 2 0 client identifier valid at the authorization server my client app response type yes oauth 2 0 response type value that determines the authorization processing flow to be used, including what parameters are returned from the endpoints used code redirect uri yes redirection uri to which the response is sent d efined when creating the software statement (application) this uri must exactly match one of the redirection uri values for the client pre registered at the openid provider, with the matching performed as described in section 6 2 1 of \[rfc3986] https //openid net/specs/openid connect core 1 0 html#rfc3986 (simple string comparison) when using this flow, the redirection uri should use the https scheme; however, it may use the http scheme, provided that the client type is confidential , as defined in section 2 1 of oauth 2 0, and provided the op allows the use of http redirection uris in this case the redirection uri may use an alternate scheme, such as one that is intended to identify a callback into a native application scope yes o penid connect requests must contain the openid scope value if the openid scope value is not present, the behavior is entirely unspecified other scope values may be present scope values used that are not understood by an implementation should be ignored see sections 5 4 https //openid net/specs/openid connect core 1 0 html#scopeclaims and 11 https //openid net/specs/openid connect core 1 0 html#offlineaccess for additional scope values defined by this specification openid trust framework profile or openid profile trust framework profile nonce no string value used to associate a client session with an id token, and to mitigate replay attacks the value is passed through unmodified from the authentication request to the id token sufficient entropy must be present in the nonce values used to prevent attackers from guessing values for implementation notes, see section 15 5 2 https //openid net/specs/openid connect core 1 0 html#noncenotes response mode no controls how tokens are delivered to the requesting client application state no opaque value used to maintain state between the request and the callback typically, cross site request forgery (csrf, xsrf) mitigation is done by cryptographically binding the value of this parameter with a browser cookie code challenge yes utilized in pkce code challenge is a base64 url encoded result of transforming the code verifier using the sha256 algorithm base64url encode(sha256(ascii(code verifier))) code challenge method yes the algorithm used to create the code challenge s256 sample request post https //matls auth demo raidiam io/request body (x www form urlencoded) response type=code code challenge method=s256 nonce=gxgldlyaatu client id=b7add03c b18e 495f b6e5 499ef745a6b9 scope=openid trust framework profile redirect uri=https //www example com state=xyaaaabc124 code challenge=47deqpj8hbsa timw 5jceuqerkm5nmpjwzg3hsufupost https //matls auth demo raidiam io/request body (www url encoded) response type=code\&code challenge method=s256\&nonce=gxgldlyaatu\&client id=4f5e14e7 2cb8 476c 8bcf 7f9899f5dcd8\&scope=openid%20trust framework profile\&redirect uri=https%3a%2f%2fwww example com%2fcb\&state=xyaaaabc124\&code challenge=47deqpj8hbsa timw 5jceuqerkm5nmpjwzg3hsufu sample response {"expires in" 60,"request uri" "urn\ ietf\ params\ oauth\ request uri\ o34qcmivooqj iuwqpmn6"} authorize application using the connect's /auth endpoint, build out the full request endpoint by including the request uri you received in the previous section as a query parameter sample https //auth demo raidiam io/auth?request uri=urn\ ietf\ params\ oauth\ request uri\ o34qcmivooqj iuwqpmn6\&client id=b7add03c b18e 495f b6e5 499ef745a6b9 authorization server authenticates end user authorization server obtains end user consent/authorization authorization server redirects end user back to client the redirect url now contains a json web token (jwt) with the authorization code sample redirect https //www example com/?response=eyjhbgcioijquzi1niisinr5cci6ikpxvcisimtpzci6ije2mzixnteymzm0mzctzjdimznlywzmyyj9 eyjjb2rlijoiweyzrxnkvelrcfrosc12cxdvd0vfwg1td1jfndlnbmhvnkvmuurgwez1esisimf1zci6imi3ywrkmdnjlwixogutndk1zi1inmu1ltq5owvmnzq1ytziosisimv4cci6mty5nduymjuxnswiaxnzijoiahr0chm6ly9hdxrolmrlbw8ucmfpzglhbs5pbyj9 onxdxfmbiylhxk5l91htcree6ey2bulh5kfekalgopjl4qynlky2f3e075lnh4jggg5bbzghxwssi1ottbcoeobrzzf1z9rd1qnv3ksfgjeyb1keahpovxo34t5hpnnayxyvxhotdssrsjnadmvxluk6lf5hnt gjfze15o9pchyltsltwrytdt4g25huzxlzwbyt58kpjck0iybs8 ptni7gzn rc dgn1uvw2wriept wqyznv9ax5svb2qwggeq3ztzegpsnqa664metjlq0pa30tw9fpabrtdx4l7koaku0vtjygpmpy06tycdhjc1gsbeo1cecm0zfidsg6pw remember to properly validate all the fields in the jwt as well as its signature within the jwt you can find the authorisation code xf3esjtikpthh vqwoweexmswre49gnho6elqdfxfuy get tokens with the code returned from the auth endpoint, call the token endpoint to get the user's information you will need a transport certificate generating a transport certificate in order for the client to be able to talk to the directory and call the mtls protected endpoints such as the token endpoint, it needs valid transport certificates there is a good explanation on how to generate these on the 'directory operation manual' token url https //matls auth demo raidiam io/token https //matls auth demo raidiam io/token request body grant type\ authorization code redirect uri\ https //www example com code\ xf3esjtikpthh vqwoweexmswre49gnho6elqdfxfuy client id\ b7add03c b18e 495f b6e5 499ef745a6b9 code verifier\ dbjftjez4cvp mb92k27uhbuju1p1r ww1gfwfoejxk since you’re using pkce, you have to use the code verifier information of the code challenge provided doing a post with this information will give you { "access token" "nqa7 dzlufj4zpl7k1a1vrrkos8xzqyk29oozjihub5", "expires in" 3600, "id token" "eyjhbgcioijquzi1niisinr5cci6ikpxvcisimtpzci6ije2mzixnteymzm0mzctzjdimznlywzmyyj9 eyjzdwiioijsdwl6lnzpyw5hqhjhawrpyw0uy29tiiwidhhuijoictbsd01fdnprdjm5em9hmg5uskreyuptx1zicehmelnozui3d2flqi10vcisinrydxn0x2zyyw1ld29ya19wcm9mawxlijp7imjhc2ljx2luzm9ybwf0aw9uijp7inn0yxr1cyi6ikfjdgl2zsisinvzzxjfzw1hawwioijsdwl6lnzpyw5hqhjhawrpyw0uy29tin0simnlcnrpzmljyxrpb25fbwfuywdlcii6zmfsc2usim9yz19hy2nlc3nfzgv0ywlscyi6eyiwmmi2ndyznf9jnznlxzrlntvfowjizl9ingzkngixotu2mmqionsib3jnx2fkbwluijp0cnvllcjvcmdfcmvnaxn0cmf0aw9ux251bwjlcii6ikx1axpuzxn0t3jniiwib3jnyw5pc2f0aw9ux25hbwuioijmdwl6vgvzde9yzyj9fswic3vwzxjfdxnlcii6dhj1zswic3lzdgvtx3vzzxiionrydwv9lcjub25jzsi6imdyr2xkthlhyxr5iiwiyxrfagfzaci6imtuqthhwjfqtdktshlnumzkym1obxcilcjhdwqioijin2fkzdazyy1imthlltq5nwytyjzlns00otllzjc0nwe2yjkilcjlehaioje2otq1mjywodqsimlhdci6mty5nduymjq4ncwiaxnzijoiahr0chm6ly9hdxrolmrlbw8ucmfpzglhbs5pbyj9 enslp5rmzpkdo t5sjfqko5nwrubvycvmp1mhdjuznr2lb ykgk08n0xbbq1ixymratrpuki7q5zlyz6rxvpqa7rj jx dg pwf8nhij q14tlsr8slhxzo1emvzsvunawps48paomivb6ckcfruna wb9ib7uttvbexkamwjhcwnjvsv3mkrcuplj0jnut1y8pqb6nt4rlubtnd0ji vhahbnzat8d5qhjwrrk1cyarqbxc s0kszb b mzsdg51dhr89yyfhlwep xnlglxjoftua vrotipy6ftt76qmxfv2dmhb78wks0zfmcs0zfuxmcmskto erg0mhsmw", "scope" "openid trust framework profile", "token type" "bearer" } inspecting the id token received gives you the json with information similar to the below { "sub" "luiz viana\@raidiam com", "txn" "q0rwm vzkv39zoa0ntjddajm vhphlzsheb7wakb tt", "trust framework profile" { "basic information" { "status" "active", "user email" "luiz viana\@raidiam com" }, "certification manager" false, "org access details" { "02b64634 c73e 4e55 9bbf b4fd4b19562d" { "org admin" true, "org registration number" "luiztestorg", "organisation name" "luiztestorg" } }, "super user" true, "system user" true }, "nonce" "gxgldlyaaty", "at hash" "kna8az1jl9 hymrfdbmhmw", "aud" "b7add03c b18e 495f b6e5 499ef745a6b9", "exp" 1694526084, "iat" 1694522484, "iss" "https //auth demo raidiam io" } alternatively, you can also use the access token to call the connect's /me endpoint whenever needed sample request get https //matls auth demo raidiam io/me header {authorization "bearer nqa7 dzlufj4zpl7k1a1vrrkos8xzqyk29oozjihub5"} sample response { "sub" "luiz viana\@raidiam com", "txn" "q0rwm vzkv39zoa0ntjddajm vhphlzsheb7wakb tt", "trust framework profile" { "basic information" { "status" "active", "user email" "luiz viana\@raidiam com" }, "certification manager" false, "org access details" { "02b64634 c73e 4e55 9bbf b4fd4b19562d" { "org admin" true, "org registration number" "luiztestorg", "organisation name" "luiztestorg" } }, "super user" true, "system user" true } } get more information about authenticated user if you require additional information such as the user's name and national id number (cpf for brazil), you can add profile to your scope request by sending the scope openid profile trust framework profile , this is what the id token would contain { "sub" "luiz viana\@raidiam com", "txn" "q0rwm vzkv39zoa0ntjddajm vhphlzsheb7wakb tt", "trust framework profile" { "basic information" { "status" "active", "user email" "luiz viana\@raidiam com" }, "certification manager" false, "org access details" { "02b64634 c73e 4e55 9bbf b4fd4b19562d" { "org admin" true, "org registration number" "luiztestorg", "organisation name" "luiztestorg" } }, "super user" true, "system user" true }, "email" "luiz viana\@raidiam com", "email verified" true, "phone number" "+5584994170198", "phone number verified" true, "family name" "viana", "given name" "luiz", "name" "luiz viana" }