Enable Single Sign-On
Utilize Single Sign-On and enable Users 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 Identity Provider (IDP). 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)
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.
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.
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_verifieris generated by the client application for every authorization request and transformed into code_challengeaccording 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.
To integrate with Raidiam for authentication, client applications need to push their authorization requests to Raidiam Authorisation Server 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.
Create an application (request Software Statement).
Within your application, register the same redirect_uri that you will use in the Single Sign-On 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 Administrator with a client identifier of your application (Software Statement ID) -- enabling the administrator to configure the application to request necessary scopes.
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:
You can utilize the below Postman API collection to quickly test the integration:
Below, you can find a Postman implementation of a pushed authorization request (PAR).
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. Defined 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] (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 | OpenID 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. | 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. | |
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:
Sample response:
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
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
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
Request Body:
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:
Inspecting the ID token received gives you the JSON with information similar to the below:
Alternatively, you can also use the access token to call the Connect's /me endpoint whenever needed.
Sample request:
Sample response:
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: